In the previous tutorial I talked about managing secrets for ASP.NET Core websites using the secret manager tool. User secrets and the secret manager tool are intended for use during development on your local PC. This keeps the developer from storing secrets in configuration files that may accidentally be exposed and/or pushed to a Git repository.

In the previous tutorial I also mentioned Microsoft's Azure Key Vault, which provides a secure way to safeguard cryptographic keys and other secrets used by your Azure resources. Since a large part of my development involves developing and deploying Orchard Core web applications to Azure cloud services, I use Key Vault quite often with Orchard Core for storing secrets. In this tutorial I will briefly discuss using Key Vault with Orchard Core, which you will realize is not much different than using Key Vault directly with ASP.NET Core Razor Pages and ASP.NET Core MVC.

OrchardCore.Configuration.KeyVault

If you're an Orchard Core developer, you know that Orchard Core has built-in support for most, if not all, Azure cloud services and Key Vault is no exception. The Key Vault support in Orchard Core is not a feature that is enabled and disabled, but rather an extension that adds Key Vault to the list of configuration sources used by your Orchard Core website.

The extension, called AddOrchardCoreAzureKeyVault, does very little, because it needs to do very little. It simply reads some basic configuration information so it knows the name of the Key Vault, and adds a custom KeyVaultSecretManager class, called AzureKeyVaultSecretManager, that overrides how secret names are converted for use with Azure.

Configuring your Orchard Core Website to use Key Vault

Configuring your Orchard Core website to use Azure Key Vault is very simple. First, you need to add the package mentioned above, OrchardCore.Configuration.KeyVault. This module provides the AddOrchardCoreAzureKeyVault extension as well as the AzureKeyVaultSecretManager service. You can add this Orchard Core package from within Visual Studio by right-clicking the Orchard Core website and choosing Manage NuGet Packages, or from the command line using the .NET Core CLI.

$ dotnet add package OrchardCore.Configuration.KeyVault

Next, you need to add configuration information to your Orchard Core website to tell Orchard Core the name of the Azure Key Vault, and optionally, a reload interval that determines how often, if at all, Orchard Core will poll Key Vault for updated secrets. The configuration settings for the Orchard Core Key Vault implementation are as follows.

"OrchardCore": {
  "OrchardCore_KeyVault_Azure": {
    "KeyVaultName": "MyKeyVault",
    "ReloadInterval": ""
  }
}

Last, we need to tell the web host that Azure Key Vault is a possible location for Orchard Core secrets. Key Vault gets added as one of several configuration sources for the Orchard Core web application by calling the AddOrchardCoreAzureKeyVault extension when building the web host. Open up the Program.cs file and add the call to the extension.

public static IHost BuildHost(string[] args) =>
  Host.CreateDefaultBuilder(args)
      .AddOrchardCoreAzureKeyVault()
      ...

Adding Secrets to Key Vault for Orchard Core

There are a couple of things worth noting when naming secrets in Azure Key Vault. If you have used Key Vault before, you know that a colon ":" is an illegal character in Key Vault and generally gets converted to two dashes "--" when naming the secret. This, of course, applies to Orchard Core.

In addition, Orchard Core makes use of the underline character "_" a lot when reading configuration data for a module, which is also an illegal character in Azure. The AzureKeyVaultSecretManager service mentioned earlier converts an underline character to 3 dashes "---". Therefore, if you have a custom Orchard Core module, called MyModule.OrchardCore, that needs to access configuration data, it would normally be stored in appsettings.json as follows.

"MyModule_OrchardCore": {
  "ApiKey": "12345"
}

The ApiKey secret for the custom Orchard Core module would be named as such in Azure Key Vault.

MyModule---OrchardCore--ApiKey

Conclusion

That's all there is to using Azure Key Vault with Orchard Core. As you can tell, it's not much different than using Key Vault with ASP.NET Core Razor Pages and ASP.NET Core MVC. The extension included with OrchardCore.Configuration.KeyVault isn't doing anything that you wouldn't do in your own ASP.NET Core web apps, aside from maybe converting "_" to "---", which is a best practice for custom Orchard Core modules. However, if you're an Orchard Core developer using Orchard Core as a modular web application framework like myself, you are most likely using this same approach for storing configuration and secrets for your modular web applications.