Managing Secrets

A secret is any value that grants access: a database password, an API key, a signing key, a client secret, a storage account key, a token for a partner's service. It is the part of your configuration that you cannot show to anyone.

Everything else about configuration is ordinary. A page size, a feature flag, a timeout, a base URL — those belong in appsettings.json, in the repository, reviewed alongside the code that reads them. Secrets are the exception, and they need somewhere else to live.

The orders application has four of them in a typical deployment: the database connection string, the signing key for its tokens, the API key for the courier's tracking service, and the credential for the storage account holding invoice PDFs. This lesson is about where each one lives, how it reaches the running process, and what to do on the day one of them ends up somewhere public.

# One-off per project: records a UserSecretsId in the .csproj file.
# The values themselves are stored in your own user profile, not in the repo.
dotnet user-secrets init --project src/Orders.Api

# Set a value. The key uses the same colon-separated path as appsettings.json,
# so the application reads it with no code change.
dotnet user-secrets set "ConnectionStrings:Orders" "Server=localhost;Database=Orders;Trusted_Connection=True" --project src/Orders.Api
dotnet user-secrets set "Courier:ApiKey" "REPLACE_WITH_YOUR_OWN_DEV_KEY" --project src/Orders.Api

# See what is set, without going looking for the file.
dotnet user-secrets list --project src/Orders.Api

# Scan staged changes before the commit is created. Wire this into a
# pre-commit hook so it runs without anyone remembering to.
gitleaks protect --staged --redact

# Scan the whole history once, to find what is already there.
gitleaks detect --redact

• user-secrets init adds an id to the project file. The id is not a secret and is meant to be committed; it is the key under which your machine stores the values.
• The key path matters more than it looks. ConnectionStrings:Orders is the same configuration key that appsettings.json would use, so the application reads it through the ordinary configuration system and has no idea where the value came from. That is the property you want: nothing in your code is development-specific.
• User secrets are added to the configuration by the default host builder in the Development environment only. In any other environment the provider is not registered, so a value set this way on a server would be ignored — which is the correct behaviour, and worth knowing before you spend an afternoon on it.
• The values are stored as plain JSON in your profile. That keeps them out of git, which is the goal here. It does not protect them from anything with access to your machine, so development credentials should be development credentials, with no reach into a shared system.
• The placeholder for the courier key is deliberately obvious. Never put a real value in a command you might paste into a ticket, a wiki page or a chat message — shell history is also a file somebody can read.
• gitleaks is one of several scanners; your hosting platform probably offers push protection as well, and using both is reasonable. The important part is not which tool, it is that the check runs automatically. A scan somebody has to remember is a scan that stops happening in the week you are busy.
• Run the staged scan in a pre-commit hook and the full scan in the pipeline. Hooks are local and can be skipped; the pipeline cannot. Expect a few false positives on test fixtures and sample data, and handle them with a documented allow list rather than by switching the scan off.

var builder = WebApplication.CreateBuilder(args);

// FLAWED SHAPE. A fallback that contains a working credential is how a
// misconfigured deployment silently connects to the wrong database — or how
// the same development password ends up in production. Never write this.
// var connection = builder.Configuration.GetConnectionString("Orders")
//                  ?? "Server=dev-sql;Database=Orders;User Id=sa;Password=Passw0rd!";

// CORRECT. Missing configuration stops the application at startup, loudly,
// before it serves a single request.
var ordersConnection = builder.Configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "ConnectionStrings:Orders is not configured. Set it with dotnet user-secrets locally, "
        + "or in this environment's secret store.");

builder.Services.AddDbContext<OrdersDbContext>(options =>
    options.UseSqlServer(ordersConnection));

// The courier issued this key, so it has to exist as a value. It belongs in
// the secret store, bound to a typed options class like any other setting.
builder.Services
    .AddOptions<CourierOptions>()
    .Bind(builder.Configuration.GetSection("Courier"))
    .ValidateDataAnnotations()
    .ValidateOnStart();

// No credential at all. The platform hands this process a short-lived token
// for its own identity, so there is no stored value to leak or rotate.
builder.Services.AddSingleton(new BlobServiceClient(
    new Uri("https://ordersfiles.example-company.com"),
    new DefaultAzureCredential()));

var app = builder.Build();

• The commented-out fallback is here to be recognised, not used. Search your own configuration code for the null-coalescing operator next to a credential: it is a quiet way for a development value to become the production value on the day an environment variable is misspelled.
• Throwing at startup is the point of the corrected version. A missing secret is a deployment fault, and the useful behaviour is to fail immediately with a message naming the setting, rather than to start and then fail on the first request that touches the database.
• ValidateOnStart does the same job for the options class. Without it, a missing or malformed courier key surfaces the first time someone tracks a delivery, which may be hours after the deploy and in front of a customer.
• Nothing in this file says where the values come from. Configuration providers are layered by the host — appsettings.json, then the environment-specific file, then user secrets in development, then environment variables, then whatever you add for the secret store — and a later provider wins. Your code reads a key and stays out of it.
• The storage client takes a credential object rather than a key. The platform issues a short-lived token for the identity assigned to this container, the SDK refreshes it, and no secret is configured anywhere. DefaultAzureCredential is one cloud's implementation of the idea; workload identity on Kubernetes and instance roles elsewhere are the same pattern, and Microsoft Entra authentication does it for SQL Server too.
• That last point is worth taking further than it first appears. Every secret you remove is one you never have to store, rotate, scan for or explain. Before designing where a credential will live, check whether the service it is for supports an identity-based connection, because that removes the work rather than organising it.
• One honest cost: identity-based access is harder to set up the first time, and harder to run locally, since your laptop is not the deployed workload. Development usually falls back to your own signed-in identity, which means the local and deployed paths differ slightly. That is a real trade against not holding a credential, and it is a trade worth making.