Asos.UserSecretsRetriever 1.0.2-documentation.4

User secrets retriever

The user secrets retriever is a .NET tool that can be used to retrieve secrets from Azure Key Vault and add them via Secret Manager (user-secrets) for a project. The tool supports retrieving multiple secrets across multiple key vaults.

Why use this tool?

The .NET Secret Manager (dotnet user-secrets) is a recommended approach for storing secrets when developing on your local machine. However these secrets often have to be retrieved manually, resulting in additional overhead when getting started on an existing project and additional documentation to keep track of required secrets. This tool allows the definition (but not value) of required secrets to be stored in source control, and for the retrieval of the secrets to be automated through a single CLI command.

Why not just use the Key Vault configuration provider?

Using the Key Vault configuration provider is a valid approach to retrieving secrets in your local environment but adds additional constraints as it will query Key Vault every time you restart the application. Loading them into user-secrets prevents this and allows for a fully offline development experience.

Installation

The tool can be installed via the .NET cli:

dotnet tool install -g Asos.UserSecretsRetriever

Usage

To retrieve secrets for a project, add a appsettings.usersecrets.json configuration file in the same directory as your project file. The user secrets configuration file should define the secrets you want to retrieve and uses the following format:

{
  "Vaults": [
    {
      "Uri": "https://my-keyvault.vault.azure.net/",
      "Secrets": [
        {
          "SourceName": "MyKeyVaultSecretName",
          "DestinationName": "MyUserSecretName"
        },
        {
          "SourceName": "MySecondKeyVaultSecretName",
          "DestinationName": "MySecondUserSecretName"
        }
      ]
    },
    {
      "Uri": "https://my-second-keyvault.vault.azure.net/",
      "Secrets": [
        {
          "SourceName": "MyKeyVaultSecretName",
          "DestinationName": "MyUserSecretName"
        }
      ]
    }
  ]
}

Once the configuration file is present in the repository, any engineer with access to the key vault can retrieve the secrets using the following command:

dotnet user-secrets-retriever retrieve

Options

The tool supports the following options:

Authentication with Key Vault

The tool uses the Azure.Identity client library to authenticate with the specified Key Vaults using the DefaultAzureCredential. See the documentation on DefaultAzureCredential to understand which authentication mechanisms will be used. You will need read access to secrets within the key vaults you are accessing.