IdentityServer4 v4.1 to Duende IdentityServer v6

This upgrade guide covers upgrading from IdentityServer4 v4.1.x to Duende IdentityServer v6.

With any major release, there is always the possibility of some breaking changes. This issue tracks the list of updates where a breaking change might affect your use of IdentityServer. It would be useful to review it to understand if any of these changes affect you.

Step 1: Update to .NET 6

In your IdentityServer host project, update the version of the .NET framework. For example in your project file:

<TargetFramework>netcoreapp3.1</TargetFramework>

would change to:

<TargetFramework>net6.0</TargetFramework>

Also, any other NuGets that you were previously using that targeted an older version of .NET should be updated. For example, Microsoft.EntityFrameworkCore.SqlServer or Microsoft.AspNetCore.Authentication.Google. Depending on what your application was using, there may or may not be code changes based on those updated NuGet packages.

Step 2: Update the IdentityServer NuGet package

In your IdentityServer host project, update the IdentityServer NuGet being used from IdentityServer4 to Duende IdentityServer. For example in your project file:

<PackageReference Include="IdentityServer4" Version="4.1.1" />

would change to the latest version of Duende IdentityServer:

<PackageReference Include="Duende.IdentityServer" Version="6.0.0" />

If you’re using any of the other IdentityServer4 packages, such as IdentityServer4.EntityFramework or IdentityServer4.AspNetIdentity, then there are Duende equivalents such as Duende.IdentityServer.EntityFramework and Duende.IdentityServer.AspNetIdentity, respectively.

Step 3: Update Namespaces

Anywhere IdentityServer4 was used as a namespace, replace it with Duende.IdentityServer. For example:

using IdentityServer4;
using IdentityServer4.Models;

would change to:

using Duende.IdentityServer;
using Duende.IdentityServer.Models;

Step 4: Remove AddDeveloperSigningCredential

If in ConfigureServices in your Startup.cs you were previously using AddDeveloperSigningCredential, that can be removed. Automatic key management is now a built-in feature.

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 (more details).
  • A new table called IdentityProviders for storing the OIDC provider details (more details).
  • Add missing columns for created, updated, etc to EF entities (more details).
  • Add unique constraints to EF tables where duplicate records not allowed (more details).

If you are using the Duende.IdentityServer.EntityFramework package as the implementation for the database and you’re using EntityFramework Core migrations as the mechanism for managing those schema changes over time, the commands below will update those migrations with the new changes. Note that you might need to adjust based on your specific organization of the migration files.

dotnet ef migrations add UpdateToDuende_v6_0 -c PersistedGrantDbContext -o Data/Migrations/IdentityServer/PersistedGrantDb

dotnet ef migrations add UpdateToDuende_v6_0 -c ConfigurationDbContext -o Data/Migrations/IdentityServer/ConfigurationDb

You will likely get the warning “An operation was scaffolded that may result in the loss of data. Please review the migration for accuracy.”. This is due to the fact that in this release the column length for redirect URIs (for both login and logout) was reduced from 2000 to 400. This was needed because some database providers have limits on index size. This should not affect you unless you are using redirect URIs greater than 400 characters.

Then to apply those changes to your database:

dotnet ef database update -c PersistedGrantDbContext

dotnet ef database update -c ConfigurationDbContext

Step 6: Migrating signing keys (optional)

In IdentityServer4, the common way to configure a signing key in 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.

Since client apps and APIs commonly cache the key material published from the discovery document then when upgrading you need to consider how those applications will handle an upgraded token server with a new and different signing key.

If while upgrading you can simply restart all of the client apps and APIs that depend on those signing keys, then you can remove the old signing key and start to use the new automatic key management. When they are restarted they will reload the discovery document and thus be aware of the new signing key.

But if you can’t restart all the client apps and APIs then you will need to maintain the prior signing key while still publishing the new keys produced from the automatic key management feature. This can be achieved by still using AddSigningCredential(). A signing key registered with AddSigningCredential() will take precedence over any keys created by the automatic key management feature. Once the client apps and APIs have updated their caches (typically after 24 hours) then you can remove the prior signing key by removing the call to AddSigningCredential() and redeploy your IdentityServer.

Step 7: Done!

That’s it. Of course, at this point you can and should test that your IdentityServer is updated and working properly.