Migrate to OpenIddict 5.0

What's new?

The most important changes introduced in 5.0 can be found here.

NOTE

Migrating to OpenIddict 5.0 requires making changes to your database: existing properties have been reworked and new ones have been added to support the new features.

Update your packages references

For that, update your .csproj file to reference the OpenIddict 5.x packages. For instance:

<ItemGroup>
  <!-- OpenIddict 4.x: -->
  <PackageReference Include="OpenIddict.AspNetCore" Version="4.10.1" />
  <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="4.10.1" />

  <!-- OpenIddict 5.x: -->
  <PackageReference Include="OpenIddict.AspNetCore" Version="5.7.0" />
  <PackageReference Include="OpenIddict.EntityFrameworkCore" Version="5.7.0" />
</ItemGroup>

NOTE

Migrating to ASP.NET Core 8.0 is not required, as OpenIddict 5.0 is still natively compatible with ASP.NET Core 2.1 (.NET Framework-only), ASP.NET Core 6.0 and ASP.NET Core 7.0. Moving to a newer .NET runtime or ASP.NET Core can be done separately for a simpler/decoupled upgrade:

Web framework version	.NET runtime version
ASP.NET Core 2.1	.NET Framework 4.6.1
ASP.NET Core 2.1	.NET Framework 4.7.2
ASP.NET Core 2.1	.NET Framework 4.8
ASP.NET Core 6.0	.NET 6.0
ASP.NET Core 7.0	.NET 7.0
ASP.NET Core 8.0	.NET 8.0
Microsoft.Owin 4.2	.NET Framework 4.6.1
Microsoft.Owin 4.2	.NET Framework 4.7.2
Microsoft.Owin 4.2	.NET Framework 4.8

Use OpenIddictApplicationDescriptor.ClientType instead of OpenIddictApplicationDescriptor.Type

To avoid confusion with the new OpenIddictApplicationDescriptor.ApplicationType property, the existing OpenIddictApplicationDescriptor.Type property was replaced by a new OpenIddictApplicationDescriptor.ClientType property. The old property is still present but is obsolete and will be removed in the next major version.

await manager.CreateAsync(new OpenIddictApplicationDescriptor
{
    ClientId = "mvc",
    ClientSecret = "901564A5-E7FE-42CB-B10D-61EF6A8F3654",

    // Before:
    Type = ClientTypes.Confidential

    // After:
    ClientType = ClientTypes.Confidential
});

If applicable, add and apply migrations

If your application uses Entity Framework Core or Entity Framework 6, add a migration to react to the schema changes listed below and apply it.

Added properties

Table	Column name	Type	Nullable
OpenIddictApplications	ApplicationType	string	Yes
OpenIddictApplications	JsonWebKeySet	string	Yes
OpenIddictApplications	Settings	string	Yes

Renamed properties

Table	Old column name	New column name
OpenIddictApplications	Type	ClientType

If applicable, update your OpenIddict MongoDB applications

To avoid confusion with the new OpenIddictMongoDbApplication.ApplicationType property, the existing OpenIddictMongoDbApplication.Type property was renamed to OpenIddictMongoDbApplication.ClientType (client_type in the BSON schema). To ensure the existing applications are correctly updated to use the new name, the following script can be used to update all the existing applications at once very efficiently:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using MongoDB.Bson;
using MongoDB.Driver;
using OpenIddict.MongoDb;

var services = new ServiceCollection();
services.AddOpenIddict()
    .AddCore()
    .UseMongoDb()
    .UseDatabase(new MongoClient("mongodb://localhost:27017").GetDatabase("openiddict"));

await using var provider = services.BuildServiceProvider();
var context = provider.GetRequiredService<IOpenIddictMongoDbContext>();
var options = provider.GetRequiredService<IOptionsMonitor<OpenIddictMongoDbOptions>>().CurrentValue;
var database = await context.GetDatabaseAsync(CancellationToken.None);

var applications = database.GetCollection<BsonDocument>(options.ApplicationsCollectionName);
await applications.UpdateManyAsync(
    filter: Builders<BsonDocument>.Filter.Empty,
    update: Builders<BsonDocument>.Update.Rename("type", "client_type"));

If applicable, update your custom stores to implement the new APIs

To support the new features introduced in 5.0, new store APIs have been added to IOpenIddictApplicationStore and will need to be implemented:

ValueTask<string?> GetApplicationTypeAsync(TApplication application, CancellationToken cancellationToken);
ValueTask<JsonWebKeySet?> GetJsonWebKeySetAsync(TApplication application, CancellationToken cancellationToken);
ValueTask<ImmutableDictionary<string, string>> GetSettingsAsync(TApplication application, CancellationToken cancellationToken);
ValueTask SetApplicationTypeAsync(TApplication application, string? type, CancellationToken cancellationToken);
ValueTask SetJsonWebKeySetAsync(TApplication application, JsonWebKeySet? set, CancellationToken cancellationToken);
ValueTask SetSettingsAsync(TApplication application, ImmutableDictionary<string, string> settings, CancellationToken cancellationToken);

A new API has also been added to IOpenIddictTokenStore:

ValueTask<long> RevokeByAuthorizationIdAsync(string identifier, CancellationToken cancellationToken);

The PruneAsync(DateTimeOffset threshold, CancellationToken cancellationToken) API present in both IOpenIddictAuthorizationStore and IOpenIddictTokenStore has also been updated to return the number of removed entries:

// OpenIddict 4.x:
ValueTask PruneAsync(DateTimeOffset threshold, CancellationToken cancellationToken);

// OpenIddict 5.x:
ValueTask<long> PruneAsync(DateTimeOffset threshold, CancellationToken cancellationToken);

Consider using client assertions (optional)

OpenIddict 5.0 introduces native support for client assertions in the server and validation stacks (client assertions were already supported by the client stack in OpenIddict 4.0). Client assertions offer a more secure alternative to client secrets and are now the recommended way for confidential applications to authenticate in OpenIddict 5.0.

For more information, read OpenIddict 5.0 general availability.