Asos.UserSecretsRetriever 1.1.14

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

There is a known issue you might face when installing a .NET tool if you have a private (authenticated) feed in your list of sources. You can ignore the error using the following additional flag:

dotnet tool install -g Asos.UserSecretsRetriever --ignore-failed-sources

Some users have also reported getting the following exception when installing, even after adding the above flag:

<span style="color:red"> Unhandled exception: NuGet. Protocol. Core. Types. FatalProtocolException: Unable to load the service index for source. Response status code does not indicate success: 401 (Unauthorized).</span>.

This can be normally be solved by explicitly installing the Azure Artifacts Credential Provider via the instructions on the repo.

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 a ChainedTokenCredential. The following authentication types are included and attempted in order:

1. EnvironmentCredential
2. VisualStudioCredential
3. VisualStudioCodeCredential
4. AzureCliCredential
5. AzurePowerShellCredential
6. InteractiveBrowserCredential

See the Azure.Identity documentation for more details. For help understanding an authentication issue and to identify which credential type has been selected, use the --diagnostics flag when running the tool.

You will need read access to secrets within the key vaults you are accessing.