skip to content

User Secrets & Key Vault

Secret Manager keeps development secrets in a per-project secrets.json outside the repo, while production reads them from mounted files or Azure Key Vault. Interviewers ask where each secret lives.

part ofASP.NET Coreread it →
on this pageshow

explore

questions

5

With the .NET 10 SDK, how do dotnet user-secrets init and set keep a maps API key out of source control, and where is it stored?

level: juniorimportance: must knowfreq 72%

answer

  1. a GUID written into the project file
  2. UserSecretsId MSBuild property
  3. secrets.json under the user profile
  4. plain JSON, not encrypted
  5. set, list, remove, clear

basics

~10 s

dotnet user-secrets init writes a UserSecretsId GUID into the .csproj; dotnet user-secrets set "Maps:ApiKey" stores the value in a secrets.json file under that id in the user profile, outside the repository, as unencrypted JSON.

solid answer

~40 s

Secret Manager is the SDK's `dotnet user-secrets` command. `init` adds a `<UserSecretsId>` property holding a new GUID to the project file (or keeps the one already there), and at build time that property becomes an assembly-level `UserSecretsIdAttribute`. `dotnet user-secrets set "Maps:ApiKey" "<key>"` then writes to `%APPDATA%\Microsoft\UserSecrets\<id>\secrets.json` on Windows or `~/.microsoft/usersecrets/<id>/secrets.json` on Linux and macOS. Nothing lands in the project folder, so git never sees the value; the id is not a secret and is committed. In Development, `WebApplication.CreateBuilder` loads that file, so `builder.Configuration["Maps:ApiKey"]` returns the key. `list`, `remove` and `clear` manage the store, and `--project` targets another project. The file is plain text: a convenience for developer machines, not a vault.

code

bash · 6 lines
bash
cd src/Dispatch.Api
dotnet user-secrets init
dotnet user-secrets set "Maps:ApiKey" "mk_dev_123"
dotnet user-secrets list
# Maps:ApiKey = mk_dev_123
dotnet user-secrets remove "Maps:ApiKey"

go deeper

for a junior

Recall init, set and list, that init writes a UserSecretsId into the .csproj, and that the value is read with builder.Configuration like any other key.

for a middle

Name the secrets.json paths on Windows and on Linux or macOS, explain how the tool finds the id, and say that the file is flat and unencrypted.

for a senior

Treat the store as a laptop convenience: keep real production keys out of it, document required keys for new developers, and know the .NET 10 file-based app limits.

for a principal

Set a team rule for where each class of secret lives on laptops, in test environments and in production, so no developer key ever travels through the repository.

## What Secret Manager is for A taxi-dispatch API calls a maps service for routes and arrival times, and the maps provider issues each developer an **API key**. Putting that key in `appsettings.Development.json` would commit it to the repository. **Secret Manager**, the `dotnet user-secrets` command that is part of the .NET SDK, keeps such values in a JSON file **in the developer's user profile**, linked to the project by an id, so the repository holds only the id. ## Step 1: `init` `dotnet user-secrets init`, run in the project folder (or with `--project <path>`), edits the project file: | What changes | Detail | |---|---| | `.csproj` | A `<UserSecretsId>` property with a new GUID is added to the first unconditional `PropertyGroup` | | Build output | The user-secrets MSBuild targets emit `[assembly: UserSecretsId("...")]` while `GenerateUserSecretsAttribute` is not `false` | | Project folder | Nothing else: no file is created next to `Program.cs` | If the project already has an id, `init` reports that and leaves it alone unless you pass `--id` with a value of your choice. The id is **not secret**: it only names a folder, and teammates need it, so it is committed. ## Step 2: storing and managing values | Command | Effect | |---|---| | `dotnet user-secrets set "Maps:ApiKey" "mk_dev_123"` | Adds or replaces one key | | `dotnet user-secrets list` | Prints every key and value; `--json` wraps JSON output in `//BEGIN` and `//END` | | `dotnet user-secrets remove "Maps:ApiKey"` | Deletes one key | | `dotnet user-secrets clear` | Deletes every key for this project | The tool finds the id by evaluating the project. When it cannot, it fails with "Could not find the global property 'UserSecretsId'"; run `init`, point `--project` at the right project, or pass `--id` directly. `set` also accepts JSON piped on standard input, which is a quick way to import several values at once. ## Where the file lives The path is built from the id: - **Windows:** `%APPDATA%\Microsoft\UserSecrets\<UserSecretsId>\secrets.json`. - **Linux and macOS:** `~/.microsoft/usersecrets/<UserSecretsId>/secrets.json`. Because the folder is per user and per id, two projects share a store only when they share an id, and every developer keeps their own values. Nothing in the project folder changes, so `dotnet publish` never copies the file. ## What the file looks like The tool writes **flat keys**: ```json { "Maps:ApiKey": "mk_dev_123", "Sms:AuthToken": "tok_dev_456" } ``` The user-secrets provider reads the file with the ordinary JSON configuration provider, so a hand-edited nested object (`{ "Maps": { "ApiKey": "..." } }`) works too. The next `set` or `remove`, however, rewrites the whole file in the flat form, which surprises people who edited it by hand. ## What it is not 1. **Not encrypted.** The values sit in plain text; anyone who can read the user profile can read them. 2. **Not shared.** A teammate who clones the repo gets the id but no values and runs `set` themselves. 3. **Not for servers.** The default builder reads the store only in Development, and a server normally has no such file; production keys come from the platform or a vault. ## .NET 10 file-based apps .NET 10 can run a single `app.cs` without a project file. The tool gained `-f|--file <FILE>` for such apps, but `init` is not supported for them: add a `#:property UserSecretsId=<value>` directive at the top of the file yourself, then use `set --file app.cs`. ## Interview checklist - `init` writes `UserSecretsId` into the `.csproj`; the id is committed. - `set`, `list`, `remove`, `clear` work on `secrets.json` in the user profile. - Name both OS paths and say the file is plain text. - The value is read like any key: `builder.Configuration["Maps:ApiKey"]`.

  • A teammate clones the dispatch API and the maps key reads null on their machine. What do they need to do?
    Set their own value: the `UserSecretsId` came with the repo, but `secrets.json` lives in each developer's profile and is never shared. They run `dotnet user-secrets set "Maps:ApiKey" "<their key>"` in the project folder; `init` is not needed again. Listing the required keys in the README, or as empty placeholders in `appsettings.json`, saves the next person the hunt.
  • Why does dotnet user-secrets set fail with "Could not find the global property 'UserSecretsId'"?
    The tool evaluated a project that has no `UserSecretsId`: either `init` was never run, or the command picked a different project, for example in a folder with a solution and several projects. Run `init`, pass `--project` with the right `.csproj`, or give the id explicitly with `--id`.
  • Can you use Secret Manager with a .NET 10 file-based app?
    Yes. `dotnet user-secrets set --file app.cs "Maps:ApiKey" "..."` works once the app declares an id, but `init` is not supported for file-based apps: add a `#:property UserSecretsId=<value>` directive to the file yourself.

  • Secret Manager encrypts secrets.json, so it is fine for production credentials.
  • secrets.json is created in the project folder and must be added to .gitignore.
  • The UserSecretsId GUID is itself a secret and must never be committed.
  • dotnet user-secrets init moves existing appsettings values into the secret store.
  • Values stored with dotnet user-secrets are copied into the publish output.

Assumes the .NET 10 SDK (10.0.4xx) with ASP.NET Core 10; the --file option for file-based apps is new with .NET 10, while init, set, list, remove and clear behave as in earlier releases.

open as a page

In ASP.NET Core, why does a key stored with dotnet user-secrets load in Development but read null in Staging, and how do you load it elsewhere?

level: middleimportance: should knowfreq 50%

basics

~10 s

WebApplication.CreateBuilder adds the user-secrets source only when the environment is Development, finding the store through the app assembly's UserSecretsIdAttribute. In Staging nothing reads secrets.json; call builder.Configuration.AddUserSecrets<Program>() where a non-Development run really needs it.

open as a page

In ASP.NET Core 10, how do you load production secrets from Azure Key Vault with AddAzureKeyVault and DefaultAzureCredential, and what happens at startup when access fails?

level: seniorimportance: should knowfreq 52%

basics

~10 s

Reference Azure.Extensions.AspNetCore.Configuration.Secrets and Azure.Identity, then call builder.Configuration.AddAzureKeyVault(vaultUri, new DefaultAzureCredential()). The provider lists and reads every enabled secret while the source is added, so a missing credential or permission stops startup with an exception.

open as a page

With AddAzureKeyVault in ASP.NET Core, how does a secret named Maps--ApiKey become a configuration key, and how do a custom KeyVaultSecretManager and ReloadInterval change what loads?

level: seniorimportance: should knowfreq 32%

basics

~20 s

KeyVaultSecretManager.GetKey replaces -- with :, so Maps--ApiKey becomes Maps:ApiKey. A subclass can override Load to choose which secrets are fetched and GetKey to rename them; ReloadInterval, null by default, makes the provider poll for changes.

open as a page

In ASP.NET Core, how does AddKeyPerFile turn a directory of mounted secret files, such as /run/secrets, into configuration keys?

level: middleimportance: nice to knowfreq 22%

basics

~20 s

AddKeyPerFile reads every file in a directory: the file name, with __ turned into :, becomes the key and the file content becomes the value after one trailing newline is trimmed. A file named Maps__ApiKey therefore supplies Maps:ApiKey.

open as a page