Skip to content

User Secrets for Local Development and Tests

This page explains how to manage sensitive data for .NET applications during local development and testing.

Important: Never store passwords or other sensitive data in source code or configuration files. Production secrets must never be used for development or test environments.

We use Azure Key Vaults to store all secrets securely.

Local Development Secrets

  • Secrets for local development and tests are stored in stage environment Key Vaults with the prefix local-
  • This prefix prevents conflicts with actual stage secrets
  • There are two types of Key Vaults:
    • Shared Key Vault (local-m-kv): Contains secrets shared across all areas
    • Area-specific Key Vaults: Contains secrets specific to each area (tagged with environment: stage and repo: <area-name>)
  • The reason why not all local secrets are int he local-m-kv is because we have too many secrets.
    • The KeyVault itself has quite low rate limits of fetching secrets.
    • The UI to manage secrets in Azure Portal is not built for more than 1-2 pages of secrets, i.e. there's no search or filter feature.

Secret Naming Convention

When creating secrets in Key Vault, follow these rules:
- Prefix: local-<secret_name>
- Replace : with -- (Key Vault doesn't support : in secret names)
- Example: local-MyConfig--ApiKey represents MyConfig:ApiKey in your application

Workflow for initializing secrets 
flowchart TD
    A[Start: Initialize Secrets Script] --> B[Connect to local-m-kv<br/>Shared KeyVault]
    B --> C[Fetch All Secrets from local-m-kv]
    C --> D1{Filter: Prefix = 'local-'?}
    D1 -->|Yes| E1[Add to Shared Secrets]
    D1 -->|No| F1[Skip]
    E1 --> G1[Transform Secret Names<br/>Replace '--' with ':']
    F1 --> H1{More Secrets?}
    G1 --> H1
    H1 -->|Yes| D1
    H1 -->|No| I[Query Area KeyVaults with Tags]

    I --> J[Tag: env:stage]
    I --> K[Tag: repo:area-name]
    J --> L[Get Area KeyVaults List]
    K --> L

    L --> M[Iterate Through Area KeyVaults]
    M --> N[Fetch All Secrets]
    N --> O{Filter: Prefix = 'local-'?}
    O -->|Yes| P[Add to Area Secrets]
    O -->|No| Q[Skip]
    P --> R[Transform Secret Names<br/>Replace '--' with ':']
    Q --> S{More Secrets?}
    R --> S
    S -->|Yes| O
    S -->|No| T[Merge Secrets<br/>Area secrets override shared]

    T --> U[Write to secrets.json]
    U --> V[End: Secrets Ready]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style I fill:#f3e5f5
    style T fill:#fff9c4
    style V fill:#c8e6c9
    style E1 fill:#c8e6c9
    style P fill:#c8e6c9

How to create new local user secrets

Create the secret in the shared keyvault local-m-kv or in your area keyvault.
Remember to follow the naming conventions:
- local-<secret_name>
- : should be replaced with --

Refresh your local secrets with your usual script.

How to migrate local user secrets to keyvault

See Migrate-local-usersecrets-to-kv.md.

Initialize secrets on development machine

Run 

Initialize-UserSecrets [AreaName|All]

To view the file on your local file system go here:

%APPDATA%\Microsoft\UserSecrets\[AreaName]\secrets.json

Never edit the secrets.json file manually as it will be cleared and overwritten on every run.

Note for Mac users

When using PowerShell for Mac, you may need to change the permissions of ~/.microsoft/usersecrets/minority/secrets.json to read/write.