6.4. Walkthrough: Local & Remote Secrets Management¶

6.4.1.2.1. Dotnet User-Secrets (Local Secrets)¶

Our local secrets manager is dotnet user-secrets. As you can see from by the command, this is a tool built into the dotnet CLI.

Using the dotnet user-secrets command we can create a secrets store. Each secrets store is unique to a .NET project. A secrets store is a directory on your local machine that the user-secrets manager creates to store your secrets. The secrets store directory is located separately from your project directory, which means there is no chance it will be committed to Git. Once a secrets store has been initialized in a project, you can add and manage secrets using the dotnet user-secrets tool. Secrets are saved as key-value pairs within the secrets store.

There are two commands we will be using:

• init: initializes a new secrets store for the project
• set: creates, or updates, a secret within the secrets store

To work with a secrets store you should first navigate to the project directory.

cd dotnet-user-secrets-az-keyvault
dotnet user-secrets init --id walkthrough-secrets
dotnet user-secrets set Name <yourname>

Once you have initialized your project’s secrets store you can create a new secret with set. The set command takes two arguments: the first is the key, and the second is the value. For our project, we will need a secret with a key of Name and a value of your first name.

# make sure to do this within your project directory
dotnet user-secrets set Name <yourname>

6.4.1.2.2. Application User-Secrets Integration¶

You may be wondering how our application will know where to find the secrets store. We must provide our application with the ID of our secrets store for it to be recognized. When we used dotnet user-secrets init, the ID we provided was registered in our api-user-secrets.csproj file automatically.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<?xml version="1.0" encoding="utf-8"?>
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
   <TargetFramework>netcoreapp3.1</TargetFramework>
   <RootNamespace>api_user_secrets</RootNamespace>
   <UserSecretsId>walkthrough-secrets</UserSecretsId>
</PropertyGroup>
<ItemGroup>
   <PackageReference Include="Microsoft.Azure.KeyVault" Version="3.0.5" />
   <PackageReference Include="Microsoft.Extensions.Configuration.AzureKeyVault" Version="3.1.2" />
</ItemGroup>
</Project>

It is this entry in the .csproj file that is responsible for integrating our application and our local secrets manager.

6.4.1.2.3. Accessing the Secrets Store¶

Now that our application can access the secrets store, how can our code access specific secrets? Let’s take a look at our Startup.cs file to find out.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

namespace api_user_secrets
{
   public class Startup
   {
      public static string secret;
      public Startup(IConfiguration configuration)
      {
            Configuration = configuration;
      }

      public IConfiguration Configuration { get; }

      // This method gets called by the runtime. Use this method to add services to the container.
      public void ConfigureServices(IServiceCollection services)
      {
            //accessing the Environment variables that .NET has loaded for us in Configuration
            secret = Configuration["Name"];
            services.AddSingleton<IConfiguration>(Configuration);
            services.AddControllers();
      }

      // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
      public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
      {
            if (env.IsDevelopment())
            {
               app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
               endpoints.MapControllers();
            });
      }
   }
}

On line 18 we are declaring a new public static field. The public modifier means it’s available to classes outside of the Startup class. The static modifier means an object doesn’t have to be instantiated to access this field. So this Startup.secret field will be available to any of our files.

When a secrets store is registered in a project, its secrets will be automatically loaded into the Configuration object. We can access a specific secret by its key. Line 30 assigns the value of the secret Name to the static field Startup.secret.

This static field allows any of the other files in our project to access the secret’s value.

6.4.1.2.4. Using the Secret¶

Where are we actually using our secret? Check out our lone controller file SecretController.cs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace api_user_secrets.Controllers
{
   [ApiController]
   [Route("[controller]")]
   public class SecretController : ControllerBase
   {

      private readonly ILogger<SecretController> _logger;

      public SecretController(ILogger<SecretController> logger)
      {
            _logger = logger;
      }

      [HttpGet]
      public IEnumerable<string> Get()
      {
            return new string[] { Startup.secret };
      }
   }
}

In our controller file there is one route for HTTP GET request /secret. This handler returns the value of the secret stored in the Startup.secret static field.

In this case, our secret isn’t very sensitive. However, this process is representative of how you can use secrets in a project. Typically your name wouldn’t be considered sensitive data, but many things are sensitive, such as a database connection string that includes a username and password.

6.4.1.3.1. Application Environments¶

We want to use our local secrets manager when we are developing our project, but want to use our remote secrets manager when we deploy our application. There are two different environments our application runs in: development (local) and production (remote). We will need to introduce some logic into our application that will allow it to use our local secrets manager when it detects a development environment, while using a remote secrets manager when it detects a production environment.

When you run an application with dotnet run .NET considers it a development environment. When you use dotnet publish and then run the build artifact it .NET considers that a production environment.

The logic for this needs to occur at the entry point of .NET applications, Program.cs.

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

// if not in Production environment (dotnet run) don't setup KeyVault and use the default Secret Storage managed through dotnet user-secrets
if (!context.HostingEnvironment.IsProduction()) return;

// if in Production environment (dotnet publish) setup KeyVault -- pull the KeyVault name from appsettings.json

var builtConfig = config.Build();

var azureServiceTokenProvider = new AzureServiceTokenProvider();
var keyVaultClient = new KeyVaultClient(
   new KeyVaultClient.AuthenticationCallback(
      azureServiceTokenProvider.KeyVaultTokenCallback
   )
);

config.AddAzureKeyVault(
   "https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
   keyVaultClient,
   new DefaultKeyVaultSecretManager()
);

Line 24 is a conditional statement. There are some comments explaining the different logical paths, but essentially the first path is that in a development environment we load the local secrets manager (dotnet user-secrets) by default. In a production environment, we configure and connect to the remote secrets manager (Azure Key Vault).

6.4.1.3.2. Application Key Vault Integration¶

How does our application know which Key Vault to use?

You may have noticed in Program.cs we are trying to access KeyVaultName from the builtConfig object on line 36. This object loads the key-value pairs from the appsettings.json file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
"Logging": {
   "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
   }
},
"AllowedHosts": "*",
"KeyVaultName": ""
}

Currently, there is an empty key-value pair with the key KeyVaultName. After we setup an Azure Key Vault we will have to provide its name as the value to this entry.