Asos.UserSecretsRetriever 1.1.35

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

Troubleshooting Installation Issues

If you encounter issues during installation, please refer to the following common problems and solutions:

Issue 1: Private Feed Conflicts

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

Issue 2: 401 Unauthorized Error

Some users have reported getting the following exception when installing, even after adding the --ignore-failed-sources flag:

<span style="color:red">Unhandled exception: System.Net.Http.HttpRequestException: Response status code does not indicate success: 401 (Unauthorized)</span>

Or:

<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 typically occurs when you have private Azure DevOps/Azure Artifacts feeds configured in your NuGet sources that require authentication. There are two recommended approaches to resolve this:

Solution A: Azure Artifacts Credential Provider (Recommended)

The recommended approach is to install the Azure Artifacts Credential Provider, which automatically handles authentication for Azure Artifacts feeds.

Windows:

1. Open PowerShell as Administrator
2. Run the following command:

   iex "& { $(irm https://aka.ms/install-artifacts-credprovider.ps1) }"
   

macOS/Linux:

1. Open Terminal
2. Run the following command:

   sh -c "$(curl -fsSL https://aka.ms/install-artifacts-credprovider.sh)"
   

After installing the credential provider, try installing the tool again:

dotnet tool install -g Asos.UserSecretsRetriever

Solution B: Manual NuGet Configuration (Alternative)

If you prefer to configure authentication manually or the credential provider doesn't work for your setup, you can add credentials directly to your NuGet configuration.

1. Locate your NuGet configuration file:

   • Windows: %APPDATA%\NuGet\nuget.config
   • macOS/Linux: ~/.nuget/NuGet/NuGet.Config

2. Add your private feed and credentials to the configuration file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="PE-ASOS" value="https://pkgs.dev.azure.com/asos/ASOS%20PE/_packaging/PE-ASOS/nuget/v3/index.json" />
    
  </packageSources>
  <packageSourceCredentials>
    <PE-ASOS>
      <add key="Username" value="firstname.lastname@asos.com" />
      <add key="ClearTextPassword" value="your-azure-devops-pat-token" />
    </PE-ASOS>
    
  </packageSourceCredentials>
</configuration>

3. Replace firstname.lastname@asos.com with your ASOS email address
4. Replace your-azure-devops-pat-token with a Personal Access Token (PAT) that has Packaging (read) permissions

After configuring your credentials, try installing the tool again:

dotnet tool install -g Asos.UserSecretsRetriever

Note: While Solution B works, we recommend Solution A (Azure Artifacts Credential Provider) as it's more secure and doesn't require storing credentials in plain text files.

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.