Migration : IdentityServer4 to Duende IdentityServer6

Why migration needed?

IdentityServer4 was reached its end of life (EOL) from 13th December 2022. So, if you want to use IdentityServer, it is strongly advised to migrate over to Duende IdentityServer.

Migration process

As part of successfull migration process, one has to follow below steps:

Step 1: Update to .NET 6

Step 2: Update the IdentityServer NuGet package

Step 3: Update Namespaces

Step 4: Remove AddDeveloperSigningCredential

Step 5: Update Database Schema (if needed)

Step 6: Migrating signing keys (optional)

Step 7: Data Protection Configuration

Step 1: Update to .NET 6

Update the version of your .Net project to target framework net6.0

FROM
<TargetFramework>netcoreapp3.1</TargetFramework>
TO
<TargetFramework>net6.0</TargetFramework>

Step 2: Update the IdentityServer NuGet package

In your IdentityServer project, update the IdentityServer NuGet being used from IdentityServer4 to Duende IdentityServer.

FROM
<PackageReference Include="IdentityServer4" Version="4.1.1" />
TO
<PackageReference Include="Duende.IdentityServer" Version="6.0.0" />

Similarly, update all your IdentityServer4 packages to Duende.IdentityServer like Duende.IdentityServer.EntityFramework and Duende.IdentityServer.AspNetIdentity, respectively

Step 3: Update Namespaces

Replace all the IdentityServer4 namespace with Duende.IdentityServer.

FROM
using IdentityServer4;
using IdentityServer4.Models;
TO
using Duende.IdentityServer;
using Duende.IdentityServer.Models;

Step 4: Remove AddDeveloperSigningCredential

In your Startup.cs file, remove the line (if any) AddDeveloperSigningCredential because now Automatic key management is now a built-in feature in Duende IdentityServer.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllersWithViews();

    var builder = services.AddIdentityServer()
        .AddInMemoryIdentityResources(Config.IdentityResources)
        .AddInMemoryApiScopes(Config.ApiScopes)
        .AddInMemoryClients(Config.Clients)
        .AddTestUsers(TestUsers.Users);

    //REMOVE BELOW LINE IN Duende IdentityServer6
    builder.AddDeveloperSigningCredential();
    .......
    .......
}

Step 5: Update Database Schema (if needed)

If you are using a database for your configuration and operational data, then there are database schema updates. These include:

• A new Keys table for the automatic key management feature in the operational database.
• A new RequireResourceIndicator boolean column on the ApiResources table in the configuration database.
• A new index on the ConsumedTime column in the PersistedGrants table
• A new table called IdentityProviders for storing the OIDC provider details.
• Add missing columns for created, updated, etc to EF entities.
• Add unique constraints to EF tables where duplicate records not allowed.

Script for ConfigurationDb.sql

Script for PersistedGrantDb.sql

Step 6: Migrating signing keys (optional)

The way to configure a signing key in IdentityServer4 Startup was to use AddSigningCredential() and provide key material (such as an X509Certificate2). In Duende IdentityServer, the automatic key management feature can manage those keys for you.

Automatic Key Management is included in IdentityServer Business Edition or higher.

Automatic Key Management follows best practices for handling signing key material, including

• automatic rotation of keys
• secure storage of keys at rest using data protection
• announcement of upcoming new keys
• maintenance of retired keys

var builder = services.AddIdentityServer(options =>
{   
    // new key every 30 days
    options.KeyManagement.RotationInterval = TimeSpan.FromDays(30);
    
    // announce new key 2 days in advance in discovery
    options.KeyManagement.PropagationTime = TimeSpan.FromDays(2);
    
    // keep old key for 7 days in discovery for validation of tokens
    options.KeyManagement.RetentionDuration = TimeSpan.FromDays(7);

    // don't delete keys after their retention period is over
    options.KeyManagement.DeleteRetiredKeys = false;
});

Automatic Key Management stores keys through the abstraction of the ISigningKeyStore. You can implement this extensibility point to customize the storage of your keys (perhaps using a key vault of some kind), or use one of the two implementations of the ISigningKeyStore that we provide:

• the default FileSystemKeyStore, which writes keys to the file system.
• the EntityFramework operational store which writes keys to a database using EntityFramework.

The default FileSystemKeyStore writes keys to the KeyPath directory configured in your IdentityServer host, which defaults to the directory ~/keys. This directory should be excluded from source control.

If you are deploying in a load balanced environment and wish to use the FileSystemKeyStore, all instances of IdentityServer will need read/write access to the KeyPath.

var builder = services.AddIdentityServer(options =>
{   
    // set path to store keys
    options.KeyManagement.KeyPath = "/home/shared/keys";
});

Step 7: Data Protection Configuration

Will cover in Next Article.

Happy coding !!

References

Duende Software Documentation

Samples by IdentityServerv6

Samples/IdentityServer/v6/Quickstarts at main · DuendeSoftware/Samples