Environment Variables and User Secrets

Secrets — database connection strings, API keys, JWT signing keys, payment processor credentials — must never appear in source control. ASP.NET Core provides two mechanisms for keeping secrets out of committed files: User Secrets for local development (stored outside the project in the user’s profile directory) and environment variables for staging and production (set at the infrastructure level, never in code). Together these two mechanisms provide secret management for every environment without a single sensitive value in the repository.

User Secrets — Local Development #

// ── Setup: initialise User Secrets for a project ──────────────────────────
// dotnet user-secrets init --project src/BlogApp.Api
// Adds: <UserSecretsId>guid-here</UserSecretsId> to .csproj

// ── Set secrets ────────────────────────────────────────────────────────────
// dotnet user-secrets set "JwtSettings:SecretKey" "my-super-secret-key-32chars"
// dotnet user-secrets set "ConnectionStrings:Default" "Server=.;Database=BlogApp;..."
// dotnet user-secrets set "Smtp:Password" "SMTP_API_KEY_HERE"

// ── List and remove secrets ────────────────────────────────────────────────
// dotnet user-secrets list                          # show all
// dotnet user-secrets remove "Smtp:Password"        # remove one
// dotnet user-secrets clear                         # remove all

// ── Storage location (outside the project — never committed) ──────────────
// Windows: %APPDATA%\Microsoft\UserSecrets\{UserSecretsId}\secrets.json
// Linux/macOS: ~/.microsoft/usersecrets/{UserSecretsId}/secrets.json

// ── In code — User Secrets load automatically in Development ──────────────
// WebApplication.CreateBuilder adds User Secrets when IsDevelopment() is true
// No code change needed — secrets are available via IConfiguration as normal:
var key = builder.Configuration["JwtSettings:SecretKey"];  // reads from User Secrets in Dev

Environment Variables for Production #

// ── Environment variables override appsettings.json ───────────────────────
// The colon (:) in config keys becomes double underscore (__) in env vars:
// Config key: "JwtSettings:SecretKey"
// Env var:    "JwtSettings__SecretKey"     (double underscore on Linux/macOS)
// Env var:    "JwtSettings:SecretKey"       (colon works on Windows only)

// ── Setting env vars in different environments ─────────────────────────────
// Linux/macOS shell:
//   export JwtSettings__SecretKey="prod-secret-key"
//   export ConnectionStrings__Default="Server=prod-sql;Database=BlogApp;..."

// Docker Compose:
//   environment:
//     - JwtSettings__SecretKey=${JWT_SECRET}
//     - ConnectionStrings__Default=${DB_CONNECTION_STRING}

// Kubernetes (via ConfigMap or Secret):
//   env:
//     - name: JwtSettings__SecretKey
//       valueFrom:
//         secretKeyRef:
//           name: blogapp-secrets
//           key: jwt-secret-key

// Azure App Service (Application Settings):
//   JwtSettings__SecretKey = <value from Key Vault reference>

// ── Reading in code — identical to appsettings.json ───────────────────────
// No code change needed — IConfiguration merges all sources transparently
var secret = builder.Configuration["JwtSettings:SecretKey"];
// Works whether value came from appsettings.json, User Secrets, or env var

Common Mistakes #

Mistake 1 — Using colon separator in environment variables on Linux (silently fails) #

❌ Wrong — colon in env var name is invalid on Linux; the configuration key is never set:

// export JwtSettings:SecretKey="value"   ← Linux ignores this silently!

✅ Correct — use double underscore on Linux/macOS/Docker: JwtSettings__SecretKey.

Mistake 2 — Relying on User Secrets in non-Development environments #

❌ Wrong — User Secrets do not load in Staging or Production; services use empty/null config values.

✅ Correct — use environment variables or vault for all non-Development environments.