Duende IdentityServer v6.2 to v6.3

This upgrade guide covers upgrading from Duende IdentityServer v6.2 to v6.3 (release notes).

Duende IdentityServer 6.3 adds:

Support for OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) , a new OAuth specification for sender-constraining refresh tokens and access tokens.
A new Configuration API distributed through the separate Duende.IdentityServer.Configuration NuGet package that supports the OAuth and OIDC Dynamic Client Registration specifications.
Support for 3rd party initiated login through the new client configuration property InitiateLoginUri. This is typically used to create a client application portal page within an IdentityServer host.
Support for the OIDC prompt=create parameter, which gives the client application the ability to provide a hint that the user needs to register.
New configuration options for managing refresh token rotation.
Support for the unmet_authentication_requirements error response code, improving error responses during step-up flows.
Nullable reference type annotations on many public APIs.
Programmer quality of life improvements, bug fixes, and more! See the release notes for more details.

Step 1: Update NuGet package

In your IdentityServer host project, update the version of the NuGet package reference. For example in your project file:

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

would change to:

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

Step 2: Update Database Schema (if necessary)

IdentityServer 6.3 adds new four new properties to the Duende.IdentityServer.Models.Client model that are needed to support DPoP and 3rd party initiated login. If you are storing you Client configuration in a database, then you will need to update the database’s schema.

The InitiateLoginUri string is a nullable string used for Third Party Initiated Login. Existing clients only need a value set for this property if the IdentityServer host itself is using third party initiated login (e.g., if you are building a client application portal within your IdentityServer) and want the client to be part of the portal.
New properties added to the Client Model for DPoP support:
- RequireDPoP is a non-nullable boolean flag that controls if a client is required to use DPoP. Existing clients that are not using DPoP can set this to false.
- DPoPValidationMode is a non-nullable column that stores a “flags”-style enum that controls the DPoP validation mechanism. In most databases, this is represented as an integer. Existing clients that are not using DPoP can set its value to 0.
- DPoPClockSkew is a non-nullable timespan that controls how much clock skew is allowed for a particular DPoP client. Existing clients that are not using DPoP can set its value to a timespan of length 0.

IdentityServer is abstracted from the data store on multiple levels, so the exact steps involved in updating your data store will depend on your implementation details.

Custom Store Implementations

The core of IdentityServer is written against the store interfaces, which abstract all the implementation details of actually storing data. If your IdentityServer implementation includes a custom implementation of those stores, then you will have to determine how best to include the changes in the model in the underlying data store and make any necessary changes to schemas, if your data store requires that.

Duende.IdentityServer.EntityFramework

We also provide a default implementation of the stores in the Duende.IdentityServer.EntityFramework package, but this implementation is still highly abstracted because it is usable with any database that has an EF provider. Different database vendors have very different dialects of sql that have different syntax and type systems, so we don’t provide schema changes directly. Instead, we provide the Entity Framework entities and mappings which can be used with Entity Framework’s migrations feature to generate the schema updates that are needed in your database.

To generate a migration for the new columns, run the command below. Note that you might need to adjust paths based on your specific organization of the migration files.

dotnet ef migrations add Update_DuendeIdentityServer_v6_3 -c ConfigurationDbContext -o Migrations/ConfigurationDb

Then to apply this migration to your database:

dotnet ef database update -c ConfigurationDbContext

Some organizations prefer to use other tools for managing schema changes. You’re free to manage your schema however you see fit, as long as the entities can be successfully mapped. Even if you’re not going to ultimately use Entity Framework migrations to manage your database changes, generating a migration can be a useful development step to get an idea of what needs to be done.

Step 3: Verify Data Protection Configuration

IdentityServer depends on ASP.NET Data Protection. Data Protection encrypts and signs data using keys managed by ASP.NET. Those keys are isolated by application name, which by default is set to the content root path of the host. This prevents multiple applications from sharing encryption keys, which is necessary to protect your encryption against certain forms of attack. However, this means that if your content root path changes, the default settings for data protection will prevent you from using your old keys. Beginning in .NET 6, the content root path was normalized so that it ends with a directory separator. In .NET 7 that change was reverted. This means that your content root path might change if you upgrade from .NET 6 to .NET 7. This can be mitigated by explicitly setting the application name and removing the separator character. See Microsoft’s documentation for more information.

Step 4: Breaking changes

A new ITokenCleanupService interface has been extracted from the TokenCleanupService, and IdentityServer now depends on that interface, rather than the service itself. Customizations of TokenCleanupService that previously were implemented by deriving from that class and registering the derived class in the DI system need to
- Register the derived class as an implementation of ITokenCleanupService, and
- Remove the IServerSideSessionsMarker from any calls to the base constructor.
See issue #981.
The TokenCleanupService.RemoveExpiredGrantsAsync method was renamed to CleanupGrantsAsync to reflect that it performs all grant cleanup work, including removing consumed grants and expired device codes in addition to expired grants. In the strictest sense, this is a breaking change, but it is very unlikely to cause issues during an upgrade because even though RemoveExpiredGrantsAsync was public, it was not virtual. If you were using RemoveExpiredGrantsAsync elsewhere, update your code to use the new name.

See issue #981.
The value of the typ claim in the header of Logout tokens has changed to logout+jwt, which complies with OpenID Connect Back-Channel Logout 1.0. Clients that were previously validating the typ need to be updated, or the old typ can continue to be used via the new LogoutTokenJwtType configuration option.

See issue #1169.
The TokenResponseGenerator.ProcessTokenRequestAsync virtual method, which generates access and refresh tokens and adds them to a response object, is now called by all token flows except the refresh token flow. This unifies the programming and extensibility model of the generator, which previously had duplicated code in some flows. If you have overridden this virtual method, be aware that it will now be called in all flows. Previously, the authorization code flow, device code flow, and CIBA flow did not invoke this method.

See pull request: #1178.
One time use (rotated) refresh tokens are now deleted immediately when they are used by default. If you rely on the existing behavior of marking refresh tokens as consumed (perhaps to allow for lenient rotations or replay detection), set the new PersistentGrantOptions.DeleteOneTimeOnlyRefreshTokensOnUse option to false.

See issue #1102.

Step 5: Done!

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