This post shows how you can create and use X509 certificates in Azure Key Vault. The certificates are created using Azure CLI and are used inside an ASP.NET Core application.

Code: StsServerIdentity/Services/Certificate

Setup using Azure CLI

Azure CLI can be used to setup the Azure Key Vault and also create certificates for an existing Key Vault. Azure CLI is documented and can be downloaded here: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

When Azure CLI is installed and running, you need to login.

 
az login

If the login does not work, you might have to allow your default browser to open the insecure redirect URL to complete the login. For example, when using Chrome, use the following to reset the HSTS. Unsecure URLs are required for this Azure az login. Maybe this should be fixed.

 
chrome://net-internals/#hsts

Creating certificates in an Azure Key Vault

A policy is required to create certificates in Azure Key Vault. You can get the default policy from your Azure subscription using the following request:

az keyvault certificate get-default-policy | Out-File `
 -Encoding utf8 defaultpolicy.json

Your policy could look like this:

{
  "issuerParameters": {
    "certificateTransparency": null,
    "name": "Self"
  },
  "keyProperties": {
    "curve": null,
    "exportable": true,
    "keySize": 2048,
    "keyType": "RSA",
    "reuseKey": true
  },
  "lifetimeActions": [
    {
      "action": {
        "actionType": "AutoRenew"
      },
      "trigger": {
        "daysBeforeExpiry": 90
      }
    }
  ],
  "secretProperties": {
    "contentType": "application/x-pkcs12"
  },
  "x509CertificateProperties": {
    "keyUsage": [
      "cRLSign",
      "dataEncipherment",
      "digitalSignature",
      "keyEncipherment",
      "keyAgreement",
      "keyCertSign"
    ],
    "subject": "CN=CLIGetDefaultPolicy",
    "validityInMonths": 12
  }
}

Now you can create a certificate in the Azure Key Vault. Using the policy above, enter an existing Key Vault name and the name of the certificate family.

az keyvault certificate create `
  --vault-name vaultName `
  -n certificatesKeyVaultName `
  --policy `@defaultpolicy.json

This can be viewed in the Azure Portal Key Vault.

Call the command a second time so that a second certificate is created.

Using the certificates in ASP.NET Core

The following example uses the created certificates for IdentityServer4 signing credentials. We will use the Azure Key Vault to get the new certificates. The newest certificate will be used for signing, the second newest will be used for support of existing sessions. This would make it possible to load a new certificate to the Key Vault, for example in a deployment, and when the hosted application is restarted, the certificates will be updated.

A configuration class is used to setup the certificate management. This can then be used to return the two certificates.

public class CertificateConfiguration
{
	public bool UseLocalCertStore { get; set; }
	public string CertificateThumbprint { get; set; }
	public string CertificateNameKeyVault { get; set; }
	public string KeyVaultEndpoint { get; set; }
	public string DevelopmentCertificatePfx { get; set; }
	public string DevelopmentCertificatePassword { get; set; }
}
	
private static async Task<(X509Certificate2 ActiveCertificate, X509Certificate2 SecondaryCertificate)>
	GetCertificates(IWebHostEnvironment environment, IConfiguration configuration)
{
	var certificateConfiguration = new CertificateConfiguration
	{
		// Use an Azure key vault
		CertificateNameKeyVault = configuration["CertificateNameKeyVault"], 
		KeyVaultEndpoint = configuration["AzureKeyVaultEndpoint"], 

		// development certificate
		DevelopmentCertificatePfx = Path.Combine(environment.ContentRootPath, "sts_dev_cert.pfx"),
		DevelopmentCertificatePassword = "1234" //configuration["DevelopmentCertificatePassword"] 
	};

	(X509Certificate2 ActiveCertificate, X509Certificate2 SecondaryCertificate) 
		certs = await CertificateService.GetCertificates(
		certificateConfiguration).ConfigureAwait(false);

	return certs;
}

The GetCertificates can the be used to get the certificates from the Azure Key Vault. If the app.settings are configured for the Key Vault, the KeyVaultCertificateService will be used to get the certificates.

public static async Task<(X509Certificate2 ActiveCertificate, X509Certificate2 SecondaryCertificate)> GetCertificates(CertificateConfiguration certificateConfiguration)
{
	(X509Certificate2 ActiveCertificate, X509Certificate2 SecondaryCertificate) certs = (null, null);

	if (certificateConfiguration.UseLocalCertStore)
	{
		using X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
		store.Open(OpenFlags.ReadOnly);
		var storeCerts = store.Certificates.Find(
			X509FindType.FindByThumbprint, 
			certificateConfiguration.CertificateThumbprint, 
			false);
			
		certs.ActiveCertificate = storeCerts[0];
		store.Close();
	}
	else
	{
		if (!string.IsNullOrEmpty(certificateConfiguration.KeyVaultEndpoint))
		{
			var keyVaultCertificateService = new KeyVaultCertificateService(
					certificateConfiguration.KeyVaultEndpoint,
					certificateConfiguration.CertificateNameKeyVault);

			certs = await keyVaultCertificateService
				.GetCertificatesFromKeyVault().ConfigureAwait(false);
		}
	}

	// search for local PFX with password, usually local dev
	if(certs.ActiveCertificate == null)
	{
		certs.ActiveCertificate = new X509Certificate2(
			certificateConfiguration.DevelopmentCertificatePfx,
			certificateConfiguration.DevelopmentCertificatePassword);
	}

	return certs;
}

The KeyVaultCertificateService searches for the certificates and returns the two newest ones as required.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Microsoft.Azure.KeyVault;
using Microsoft.Azure.KeyVault.Models;
using Microsoft.Azure.Services.AppAuthentication;

namespace StsServerIdentity.Services.Certificate
{
    public class KeyVaultCertificateService
    {
        private readonly string _keyVaultEndpoint;
        private readonly string _certificateName;

        public KeyVaultCertificateService(string keyVaultEndpoint, string certificateName)
        {
            if (string.IsNullOrEmpty(keyVaultEndpoint))
            {
                throw new ArgumentException("missing keyVaultEndpoint");
            }
            
            _keyVaultEndpoint = keyVaultEndpoint; // "https://damienbod.vault.azure.net"
            _certificateName = certificateName; // certificateName
        }

        public async Task<(X509Certificate2 ActiveCertificate, X509Certificate2 SecondaryCertificate)> GetCertificatesFromKeyVault()
        {
            (X509Certificate2 ActiveCertificate, X509Certificate2 SecondaryCertificate) certs = (null, null);
            var azureServiceTokenProvider = new AzureServiceTokenProvider();
            var keyVaultClient = new KeyVaultClient(new KeyVaultClient.AuthenticationCallback(azureServiceTokenProvider.KeyVaultTokenCallback));

            var certificateItems = await GetAllEnabledCertificateVersionsAsync(keyVaultClient);
            var item = certificateItems.FirstOrDefault();
            if (item != null)
            {
                certs.ActiveCertificate = await GetCertificateAsync(item.Identifier.Identifier, keyVaultClient);
            }

            if (certificateItems.Count > 1)
            {
                certs.SecondaryCertificate = await GetCertificateAsync(certificateItems[1].Identifier.Identifier, keyVaultClient);
            }

            return certs;
        }

        private async Task<List<CertificateItem>> GetAllEnabledCertificateVersionsAsync( KeyVaultClient keyVaultClient)
        {
            // Get all the certificate versions (this will also get the currect active version
            var certificateVersions = await keyVaultClient.GetCertificateVersionsAsync(_keyVaultEndpoint, _certificateName);

            // Find all enabled versions of the certificate and sort them by creation date in decending order 
            return certificateVersions
              .Where(certVersion => certVersion.Attributes.Enabled.HasValue && certVersion.Attributes.Enabled.Value)
              .OrderByDescending(certVersion => certVersion.Attributes.Created)
              .ToList();
        }

        private async Task<X509Certificate2> GetCertificateAsync(string identitifier, KeyVaultClient keyVaultClient)
        {
            var certificateVersionBundle = await keyVaultClient.GetCertificateAsync(identitifier);
            var certificatePrivateKeySecretBundle = await keyVaultClient.GetSecretAsync(certificateVersionBundle.SecretIdentifier.Identifier);
            var privateKeyBytes = Convert.FromBase64String(certificatePrivateKeySecretBundle.Value);
            var certificateWithPrivateKey = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);
            return certificateWithPrivateKey;
        }

    }
}

Now the certificates can be used in the ConfigureServices Startup method.

            
var x509Certificate2Certs = 
	GetCertificates(_environment, _configuration)
		.GetAwaiter().GetResult();	
			

var identityServer = services.AddIdentityServer()
	.AddSigningCredential(x509Certificate2Certs.ActiveCertificate)
	.AddInMemoryIdentityResources(Config.GetIdentityResources())
	.AddInMemoryApiResources(Config.GetApiResources())
	.AddInMemoryClients(Config.GetClients(stsConfig))
	.AddAspNetIdentity<ApplicationUser>()
	.AddProfileService<IdentityWithAdditionalClaimsProfileService>();

if (x509Certificate2Certs.SecondaryCertificate != null)
{
	identityServer.AddValidationKey(
		x509Certificate2Certs.SecondaryCertificate);
}

When the IdentityServer4 hosted application is started, the signing credentials created from the certificates can be viewed using the jwks endpoint

/.well-known/openid-configuration/jwks

If a new certificate is created in the Azure Key Vault, and the ASP.NET Core application is restarted, the latest certificate will be used to sign the tokens, and the previous certificate will also be supported for existing sessions.

Improvements

This shows one way how Azure Key Vault certificates can be used in an ASP.NET Core application. This could be improved in many ways. For example, it would be good if the certificates were rotated directly from the application, instead of a forced create and application restart. The async method is used in the ConfigureServices method. This could be added directly to the IdentityServer4 extension method for this by using a custom implementation. The next certificate which will be used, could also be made public before the existing certificate is replaced.

Links:

https://github.com/damienbod/IdentityServer4AspNetCoreIdentityTemplate/issues/30

https://docs.microsoft.com/en-us/cli/azure/install-azure-cli

Using Azure Key Vault with ASP.NET Core and Azure App Services

Deploying ASP.NET Core App Services using Azure Key Vault and Azure Resource Manager templates

Using Azure Key Vault from a non-Azure App