[ASP.NET Core] Identity Server 4 – Signing credential

 ASP.NET Core   Identity Server 4   Signing Credential   Key rollover  

▌Introduction

---

Signing Credential in Identity Server 4 is an asymmetric key pair which is used for signing/validating JWTs.

In development mode, we can easily create/reuse the Signing Credential by

var builder = services.AddIdentityServer();

// Signing credential

if (this.env.IsDevelopment())

{

    builder.AddDeveloperSigningCredential();

}

The above codes will check if there is tempkey.rsa (Development Signing Credential) in your Idsrv4’s root path and create a new one if it doesn’t exists.

However, when the Development Signing Credential changes, we will encounter the problem that the signed JWTs by old (private) key will be invalid when being validated by the new (public) key. So it’s recommended to use the SSL/TLS certificate or use your own RSA key pair, and do the key rollover.

Key rollover means: 1.  Create a new Signing Credential that is used to ISSUE/VALIDATE JWT. 2.  Add old Signing Credentials as the Validation Keys to ONLY VALIDATE JWT. 3.  Retire the old Signing Credentials if we don’t need to validate the JWTs signed by them anymore. (This wont be discussed in this article).

In this tutorial, we will replace the Development Signing Credential in these ways:

From	Ho to do key rollover	Note
Certificate	Manually update the certificate	Some cert provider can renew cert automatically, like Let’s encrypt. You can combine the renew process to your CI.
File	Manually/Automatically	The key can be renewed automatically when having a Registry Server and integrate in your CI. This tutorial will only has the manually way.
Redis	Automatically	You can store the key in Database instead of Redis.

 

▋Related articles

01.      [OpenLDAP] Create an OpenLDAP container

02.      [ASP.NET Core] Identity Server 4 – Concepts

03.      [ASP.NET Core] Identity Server 4 – LDAP authentication

04.      [ASP.NET Core] Identity Server 4 – Secure Web API

05.      [ASP.NET Core] Identity Server 4 – Custom Event Sink

06.      [ASP.NET Core] Identity Server 4 – Refresh Token

07.      [ASP.NET Core] Identity Server 4 – Role based authorization

08.      [ASP.NET Core] Identity Server 4 – Policy based authorization

09.      [ASP.NET Core] Identity Server 4 - Dockerize

10.      [ASP.NET Core] Identity Server 4 – Client Credential

11.      [ASP.NET Core] Identity Server 4 – Policy based authorization with custom Authorization Handler

12.      [ASP.NET Core] Identity Server 4 – Signing credential

13.      [ASP.NET Core] Identity Server 4 – Authenticate by multiple LDAP

14.      [ASP.NET Core] Identity Server 4 – Cache and refresh Discovery document

15.      [ASP.NET Core] Identity Server 4 – PKCE Authorization Code Flow

16.      [ASP.NET Core] Identity Server 4 – PKCE Authorization Code Flow (Javascript client)

 

▌Environment

---

▋Docker 18.05.0-ce

▋.NET Core SDK 3.1.201

▋IdentityServer4 3.1.2

▋IdentityModel 4.0.0

▌Implement

---

The source code is on my Github.

▋Signing Credential from certificate (Linux container)

The Resource Server must have the Authentication/Authorization configuration. (Reference: [ASP.NET Core] Identity Server 4 – Secure Web API)

Notice that the Audience is “MyBackendApi2”.

First we have to create the certificate by OpenSSL, skip this step if you already have one.

▋(Optional) Create certificate

$ openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/Docker.key -x509 -days 3650 -out certs/Docker.crt

$ openssl pkcs12 -export -out certs/Docker.pfx -inkey certs/Docker.key -in certs/Docker.crt

For more self-signed certificate, see [ASP.Net Core] Self-signed SSL certificate.

▋Startup.cs: ConfigureServices

Add the certificate as Signing Credential as following, notice that I put the cert under certs/.

public void ConfigureServices(IServiceCollection services)

{

       // … skip other codes

var builder = services.AddIdentityServer(options =>

{

            // … set options here

      });

       var rootPath = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "Certs");

      var cert = new X509Certificate2(Path.Combine(rootPath, "Docker.pfx"), string.Empty);

      builder.AddSigningCredential(cert);

}

We can also add the old certificate as the validation key like this,

// Add validation keys if any

builder.AddValidationKey(old_cert);

▋Signing Credential from certificate (Windows)

First, lets import the certificate into Windows Certificate Store by Certificate Management Store.

After importing the cert, we need to know the Thumbprint of it to get the right certificate in our code.

Right click on the cert -> Properties

Copy the value of Thumbprint in [Details] tab,

Now we can use it as Signing Credential in Idsrv.

▋Startup.cs: ConfigureServices

Add the certificate as Signing Credential from Windows Certificate Store as following,

public void ConfigureServices(IServiceCollection services)

{

       // … skip other codes

var builder = services.AddIdentityServer(options =>

{

            // … set options here

      });

       using (var certStore = new X509Store(StoreName.My, StoreLocation.LocalMachine))

      {

            certStore.Open(OpenFlags.ReadOnly);

            var certCollection = certStore.Certificates.Find(

                        X509FindType.FindByThumbprint,

                        "3c99282xxxxxxxxxxxxxxxxxxxxxxxxx", // Change this with the thumbprint of your certifiacte

                        validOnly: false);

            if (certCollection.Count > 0)

            {

               cert = certCollection[0];

               builder.AddSigningCredential(cert);

            }

     }

      // Add validation keys if any

// builder.AddValidationKey(old_cert);

}

PS. I put the above codes as an extension method here from class: IdentityServerBuilderExtensions.

▋Signing Credential from Redis

We will use 2 Redis keys to store the keys (Signing credentials):

Redis Key	Type	Description	Content format
SigningCredential	Strings	The Signing Credential for issuing and validating JWT	Object in JSON
SigningCredentialDeprecated	Strings	Deprecated Signing Credentials for validating JWT	Array in JSON

The Signing Credential(s) will be stored as object or array of custom type: SigningCredential,

▋Model: SigningCredential.cs

public class SigningCredential

{

        /// <summary>

        /// Key ID

        /// </summary>

        public string KeyId { get; set; }

        /// <summary>

        /// RSA parameters

        /// </summary>

        public RSAParameters Parameters { get; set; }

        /// <summary>

        /// Expire on

        /// </summary>

        public DateTimeOffset ExpireOn { get; set; }

}

This model is similar to the private class: TemporaryRsaKey in Crypto.cs from Idsrv4’s source code.

The only difference is we have the new property ExpireOn, which is used to check if the key needs to be renewed.

PS. The TemporaryRsaKey class is the text format in tempkey.rsa (Development Signing Credential).

※ How to create a new RSA Key pair as the Signing Credential?

We can use the same logic of IdentityServerBuilderExtensionsCrypto.AddDeveloperSigningCredential() in Crypto.cs from Idsrv4’s source code,

using IdentityServer4;

using IdentityServer4.Configuration;

using IdentityServer4.Models;

var key = CryptoHelper.CreateRsaSecurityKey();

RSAParameters parameters = key.Rsa == null ?

                   parameters = key.Parameters :

                   key.Rsa.ExportParameters(includePrivateParameters: true);

var expireOn = DateTimeOffset.UtcNow.AddYears(1);

var credential = new SigningCredential

{

      Parameters = parameters,

      KeyId = key.KeyId,

      ExpireOn = expireOn

};

Now we can implement the full logics with these steps:

1.  Check Redis’s current Signing Credential (from Redis key: SigningCredential) is valid or expired.s

2.  If current Signing Credential is valid, go to step 4.

3.  If current Signing Credential is missing or expired, move the old one to Redis key: SigningCredentialDeprecated and create a new one.

4.  Register the Signing Credential (from Redis key: SigningCredential) to Idsrv4.

5.  Register the Signing Credentials (from Redis key: SigningCredentialDeprecated) as the validation keys to Idsrv4.

▋IdentityServerBuilderExtensions.cs

public static IIdentityServerBuilder AddSigningCredentialByRedis(

            this IIdentityServerBuilder builder, AppSettings appSettings)

{

            // Variables

            const int DEFAULT_EXPIRY_YEAR = 1;

            var utcNow = DateTimeOffset.UtcNow;

            var redisKeyWorkingSk = CacheKeyFactory.SigningCredential();

            var redisKeyDeprecatedSk = CacheKeyFactory.SigningCredential(isDeprecated: true);

            // RSA key object

            Microsoft.IdentityModel.Tokens.RsaSecurityKey key = null; // The Key for Idsrv

            // Signing credetial object from Redis

            SigningCredential credential = null; // The Signing credential stored in Redis

            List<SigningCredential> deprecatedCredentials = null; // The Deprecated Signing credentials stored in Redis

            using (ICacheService redis = new RedisService(appSettings))

            {

                bool isSigningCredentialExists = redis.GetCache(redisKeyWorkingSk, out credential);

                if (isSigningCredentialExists && credential.ExpireOn >= utcNow)

                {

                    // Use the RSA key pair stored in redis

                    key = CryptoHelper.CreateRsaSecurityKey(credential.Parameters, credential.KeyId);

                }

                else if (isSigningCredentialExists && credential.ExpireOn < utcNow)

                {

                    #region Move the expired Signing credential to Redis's Decprecated-Signing-Credential key

                    _ = redis.GetCache(redisKeyDeprecatedSk, out deprecatedCredentials);

                    if (deprecatedCredentials == null)

                    {

                        deprecatedCredentials = new List<SigningCredential>();

                    }

                    deprecatedCredentials.Add(credential);

                    redis.SaveCache(redisKeyDeprecatedSk, deprecatedCredentials);

                    #endregion

                    #region Clear the expired Signing credential from Redis's Signing-Credential key

                    redis.ClearCache(redisKeyWorkingSk);

                    #endregion

                    // Set flag as False

                    isSigningCredentialExists = false;

                }

                #region If no available Signing credial, create a new one

                if (!isSigningCredentialExists)

                {

                    key = CryptoHelper.CreateRsaSecurityKey();

                    RSAParameters parameters = key.Rsa == null ?

                        parameters = key.Parameters :

                        key.Rsa.ExportParameters(includePrivateParameters: true);

                    var expireOn = appSettings.Global?.SigningCredential?.DefaultExpiry == null ?

                                    utcNow.AddYears(DEFAULT_EXPIRY_YEAR) :

                                    appSettings.Global.SigningCredential.DefaultExpiry.GetExpireOn();

                    credential = new SigningCredential

                    {

                        Parameters = parameters,

                        KeyId = key.KeyId,

                        ExpireOn = expireOn

                    };

                    // Save to Redis

                    redis.SaveCache(redisKeyWorkingSk, credential);

                }

                #endregion

                // Add the key as the Signing credential for Idsrv

                builder.AddSigningCredential(key, IdentityServerConstants.RsaSigningAlgorithm.RS256);

                // Also add the expired key for clients' old tokens

                if (redis.GetCache(redisKeyDeprecatedSk, out deprecatedCredentials))

                {

                    IList<SecurityKeyInfo> deprecatedKeyInfos = new List<SecurityKeyInfo>();

                    deprecatedCredentials.ForEach(dc =>

                    {

                        var deprecatedKeyInfo = new SecurityKeyInfo

                        {

                            Key = CryptoHelper.CreateRsaSecurityKey(dc.Parameters, dc.KeyId),

                            SigningAlgorithm = SecurityAlgorithms.RsaSha256

                        };

                        deprecatedKeyInfos.Add(deprecatedKeyInfo);

                    });

                    builder.AddValidationKey(deprecatedKeyInfos.ToArray());

                }

            }

            return builder;

}

And don’t forget to update Startup: ConfigureServices!

▋Startup.cs: ConfigureServices

public void ConfigureServices(IServiceCollection services)

{

       // … skip other codes

var builder = services.AddIdentityServer(options =>

{

            // … set options here

      });

       builder.AddSigningCredentialByRedis(this.appSettings);

}

▋Demo

After starting the Auth Server, we will find that a new Signing Credential is stored in Redis.

Next time we restart the Auth Server, the expired Signing Credential will be removed and create a new one.

▋Signing Credential from Files

We will use 2 files to store the keys (Signing credentials):

Redis Key	Path	Description	Content format
SigningCredential.rsa	Keys/	The Signing Credential for issuing and validating JWT	Object in JSON
DeprecatedSigningCredentials.rsa	Keys/	Deprecated Signing Credentials for validating JWT	Array in JSON

The way to generate/store Signing Credential is almost as same as using Redis, except that it cannot renew key automatically.

▋IdentityServerBuilderExtensions.cs

public static class IdentityServerBuilderExtensions

{

    public static IIdentityServerBuilder AddSigningCredentialsByFile(

            this IIdentityServerBuilder builder, AppSettings appSettings)

    {

            // Variables

            const int DEFAULT_EXPIRY_YEAR = 1;

            const string DIR_NAME_KEYS = "Keys";

            const string FILE_NAME_WORKING_SC = "SigningCredential.rsa";

            const string FILE_NAME_DEPRECATED_SC = "DeprecatedSigningCredentials.rsa";

            var rootDir = Path.Combine(AppContext.BaseDirectory, DIR_NAME_KEYS);

            var workingScDir = Path.Combine(rootDir, FILE_NAME_WORKING_SC);

            var deprecatedScDir = Path.Combine(rootDir, FILE_NAME_DEPRECATED_SC);

            var utcNow = DateTimeOffset.UtcNow;

            // RSA key object

            Microsoft.IdentityModel.Tokens.RsaSecurityKey key = null; // The Key for Idsrv

            // Signing credetial object

            SigningCredential credential = null; // The Signing credential stored in file

            List<SigningCredential> deprecatedCredentials = null; // The Deprecated Signing credentials stored in file

            #region Add exist or new Signing Credentials

            var strWorkingSc = FileUtils.ReadFileAsync(workingScDir).Result;

            var strDeprecatedScs = FileUtils.ReadFileAsync(deprecatedScDir).Result;

            if (!string.IsNullOrEmpty(strWorkingSc))

            {

                // Use the RSA key pair stored in file

                credential = JsonConvert.DeserializeObject<SigningCredential>(strWorkingSc);

                key = CryptoHelper.CreateRsaSecurityKey(credential.Parameters, credential.KeyId);

                // Warning if key expires

                if (credential.ExpireOn < utcNow)

                {

                    logger.Warn($"Auth Server's Signing Credential (ID: {credential.KeyId}) is expired at {credential.ExpireOn.ToLocalTime()}!");

                }

            }

            else

            {

                // Create new RSA key pair

                key = CryptoHelper.CreateRsaSecurityKey();

                RSAParameters parameters = key.Rsa == null ?

                    parameters = key.Parameters :

                    key.Rsa.ExportParameters(includePrivateParameters: true);

                var expireOn = appSettings.Global?.SigningCredential?.DefaultExpiry == null ?

                    utcNow.AddYears(DEFAULT_EXPIRY_YEAR) :

                    appSettings.Global.SigningCredential.DefaultExpiry.GetExpireOn();

                credential = new SigningCredential

                {

                    Parameters = parameters,

                    KeyId = key.KeyId,

                    ExpireOn = expireOn

                };

                // Save to fiile

                FileUtils.SaveFileAsync(workingScDir, JsonConvert.SerializeObject(credential)).Wait();

            }

            // Add the key as the Signing credential for Idsrv

            builder.AddSigningCredential(key, IdentityServerConstants.RsaSigningAlgorithm.RS256);

            #endregion

            #region Add Deprecated Signing Credentials for clients' old tokens

            deprecatedCredentials = string.IsNullOrEmpty(strDeprecatedScs) ? new List<SigningCredential>() : JsonConvert.DeserializeObject<List<SigningCredential>>(strDeprecatedScs);

            IList<SecurityKeyInfo> deprecatedKeyInfos = new List<SecurityKeyInfo>();

            deprecatedCredentials.ForEach(dc =>

            {

                var deprecatedKeyInfo = new SecurityKeyInfo

                {

                    Key = CryptoHelper.CreateRsaSecurityKey(dc.Parameters, dc.KeyId),

                    SigningAlgorithm = SecurityAlgorithms.RsaSha256

                };

                deprecatedKeyInfos.Add(deprecatedKeyInfo);

            });

            builder.AddValidationKey(deprecatedKeyInfos.ToArray());

            #endregion

            return builder;

    }

}

▋Startup.cs: ConfigureServices

public void ConfigureServices(IServiceCollection services)

{

       // … skip other codes

var builder = services.AddIdentityServer(options =>

{

            // … set options here

      });

       builder.AddSigningCredentialsByFile(this.appSettings);

}

▋Demo

After starting the Auth Server, we will find that a new Signing Credential is stored in Keys/SigningCredential.rsa.

We can put the expired Signing Credential(s) as the validation key(s) as following.

▋Source Code

Github: KarateJB/AspNetCore.IdentityServer4.Sample

▌Reference

---

▋IdentityServer/IdentityServer4: Cryptography, Keys and HTTPS