OpenIddict 6.0 general availability

2024-12-17

Photo of Christmas gifts taken by Hello Aesthe

Ding ding ding... OpenIddict 6.0 is coming to town! 🎉

What's new?

Many of the new features already shipped in 5.x but some of them required introducing breaking changes and had to wait for 6.0:

The .NET 7.0 and .NET Framework 4.6.1 TFMs have been removed as these versions are no longer supported by Microsoft.
While most OpenIddict 6.0 packages can still be used on these versions thanks to their .NET Standard 2.0 or 2.1 TFMs, doing that is strongly discouraged and users are instead encouraged to migrate to .NET 8.0 and .NET Framework 4.6.2 (or higher).
The OpenIddict.MongoDb and OpenIddict.MongoDb.Models packages now reference MongoDB.Driver and MongoDB.Bson 3.0.0 and are now strong-named.

The third iteration of the C# MongoDB driver no longer supports .NET Standard 2.0 and requires .NET Framework 4.7.2 as the minimum version: OpenIddict users relying on the MongoDB integration and using the OpenIddict.MongoDb or OpenIddict.MongoDb.Models packages in projects targeting .NET Standard 2.0 or .NET Framework < 4.7.2 will need to update their projects when migrating to OpenIddict 6.0.

Some of the server endpoints have been renamed in OpenIddict 6.0 to be more specific or more closely match the official names. While it's a massive change, it should help reduce ambiguities and make migrating from other OAuth 2.0/OIDC stacks to OpenIddict easier:
- Cryptography endpoint -> JSON Web Key Set endpoint.
- Device endpoint -> Device authorization endpoint.
- Logout endpoint -> End-session endpoint.
- Userinfo endpoint -> UserInfo endpoint.
- Verification endpoint -> End-user verification endpoint.
A whole new client authentication method negotiation logic was introduced in the OpenIddict client. As part of this change, complete support for mTLS in the client stack was also added to allow integrating with identity providers that require using tls_client_auth or self_signed_tls_client_auth. See https://github.com/openiddict/openiddict-core/releases/tag/6.0.0-preview1 for more information.
A new "claims issuer" option has been added to the client and validation stacks to allow controlling the value OpenIddict uses to populate the Claim.Issuer and Claim.OriginalIssuer properties. This option is specially useful when using the OpenIddict client in legacy ASP.NET 4.6.2+ applications using ASP.NET Identity, since the Claim.Issuer property is directly reflected in the user interface:

options.AddRegistration(new OpenIddictClientRegistration
{
    // ...

    Issuer = new Uri("https://localhost:44395/", UriKind.Absolute),
    ClaimsIssuer = "Local authorization server"
});

options.UseWebProviders()
       .AddActiveDirectoryFederationServices(options =>
       {
           // ...

           options.SetClaimsIssuer("Contoso");
       });

New RevokeAsync()/RevokeByApplicationIdAsync()/RevokeBySubjectAsync() APIs modeled after the existing FindAsync() and RevokeByAuthorizationIdAsync() API have been added to the authorization/token managers/stores to allow revoking authorizations and tokens based on a given application identifier or user identifier more efficiently.
The existing IOpenIddictAuthorizationManager.FindAsync(...) and IOpenIddictTokenManager.FindAsync(...) overloads have been merged and replaced by a single method where all the parameters are now optional (for instance, if a null subject value is specified when calling IOpenIddictAuthorizationManager.FindAsync(...), the returned collection will contain authorizations for all users).
The OpenIddict server now fully supports the Initiating User Registration via OpenID Connect specification: it will now validate the prompt parameter to ensure the value is supported and return the supported values in the server configuration document using the new standard prompt_values_supported node. See https://github.com/openiddict/openiddict-core/pull/2197 for more information.

As part of this change, the OpenIddictConstants.Prompts class have been renamed to OpenIddictConstants.PromptValues and the OpenIddictRequest.GetPrompts()/OpenIddictRequest.HasPrompt() extensions have been renamed to OpenIddictRequest.GetPromptValues() and OpenIddictRequest.HasPromptValue() to match the names used in this specification. If you're using these APIs, make sure you're updating the corresponding calls when migrating to OpenIddict 6.0.

The ASP.NET Core and OWIN integrations now include the authentication properties attached to ProcessAuthenticationContext.Properties in errored authentication results, which can be used with the client stack to retrieve custom and non-custom properties attached to the state token when using the "error pass-through mode".
The OpenIddict server now automatically normalizes unique "amr" claims in identity tokens to ensure a JSON array is always returned (as required by the OpenID Connect specification), even if the developer didn't explicitly use JsonClaimValueTypes.JsonArray as the claim value type.
New methods allowing to register multiple certificates and keys at once have been added to the client/server/validation builders (thanks ionite34! ❤️)
Zendesk and EVE Online are now supported by the OpenIddict web providers package (thanks mozts2005 and kalaveijo! ❤️)

Migration

While OpenIddict 6.0 comes with some breaking changes, the migration process should be fairly easy. To help users with this process, an OpenIddict 6.0 migration guide was added to the documentation.

OpenIddict 6.0 is fully compatible with ASP.NET Core 2.1 (on .NET Framework), ASP.NET Core 6.0, ASP.NET Core 8.0 and ASP.NET Core 9.0, so the migration can be done without having to upgrade to the latest .NET runtime/ASP.NET Core version: when possible, it is even recommended to decouple the .NET runtime/OpenIddict updates for a smoother upgrade.

Support

With OpenIddict 6.0 being now generally available, the previous version, OpenIddict 5.0, stops being supported and won't receive bug fixes or security updates. As such, it is recommended to migrate to OpenIddict 6.0 to continue receiving bug and security fixes.

As for the previous major version, there are however two exceptions to this policy:

ABP Framework users receive patches for OpenIddict for as long as ABP Framework itself is supported by Volosoft (typically a year following the release of a major ABP version), whether they have a commercial ABP license or just use the free packages.

OpenIddict branch	ABP Framework branch	End of support date (estimated)
4.x	7.x	December 19, 2024
5.x	8.x	November 19, 2025
6.x (current)	9.x	Currently supported

OpenIddict sponsors are offered extended support depending on the selected sponsorship tier:
- $100/month sponsors get full support for the previous version 1 month following the release of a new major version.
- $250/month sponsors get full support for the previous version 6 months following the release of a new major version.
- $500/month sponsors get full support for the previous version 12 months following the release of a new major version.
- $1,000/month sponsors get full support for the previous version 24 months following the release of a new major version.

OpenIddict branch	Sponsorship tier	End of support date
4.x	$100/month (or more)	January 18, 2024
4.x	$250/month (or more)	June 18, 2024
4.x	$500/month (or more)	December 18, 2024
4.x	$1,000/month (or more)	December 18, 2025

5.x	$100/month (or more)	January 17, 2025
5.x	$250/month (or more)	June 17, 2025
5.x	$500/month (or more)	December 17, 2025
5.x	$1,000/month (or more)	December 17, 2026

6.x (current)	Any	Currently supported

Acknowledgements

As always, a new major release is a great opportunity to thank all the sponsors who have helped keep OpenIddict free for everyone:

Merry Christmas everyone! 🎄 🎁