This upgrade guide covers upgrading from Duende IdentityServer v5.2 to v6.0 (release notes). The most significant aspect of this upgrade is that Duende IdentityServer v6.0 targets .NET 6, and CIBA support was added.
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.
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.
In your IdentityServer host project, update the version of the Duende IdentityServer NuGet. For example in your project file:
<PackageReference Include="Duende.IdentityServer" Version="5.2.0" />
would change to:
<PackageReference Include="Duende.IdentityServer" Version="6.0.0" />
If you are using a database for your configuration data, then there is a small database schema update. This includes:
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.
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, 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_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 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.
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 is now normalized so that it ends with a directory separator. This means that your content root path might change when you upgrade to .NET 6. This can be mitigated by explicitly setting the application name and removing the separator character. See Microsoft’s documentation for more information.
That’s it. Of course, at this point you can and should test that your IdentityServer is updated and working properly.