Earlier today, the OpenIddict 7.0 packages were pushed to NuGet.org 🎉
For those familiar with OpenIddict's release cadence, this may sound surprising (as major versions typically ship in December), but there are two reasons for that:
- OpenIddict 7.0 replaces ASP.NET Core 2.1 by ASP.NET Core 2.3 as the new minimal version, which has important implications.
- OpenIddict 7.0 introduces OAuth 2.0 Token Exchange support in both the client and server stacks: since it was by far the most requested feature, I didn't want to wait December for users to be able to play with it 😊
This blog post will highlight the most important changes, but the complete list can be found in the release notes of the four 7.0 preview releases:
What's new?
ASP.NET Core 2.3 replaces 2.1 as the minimal version on .NET Framework
If you're using ASP.NET Core 2.1 (or 2.2) on .NET Framework, you're probably already aware that the ASP.NET team re-released ASP.NET Core 2.1 as ASP.NET Core 2.3 in January.
That move may sound surprising, but the ASP.NET team realized that a lot of users were still using ASP.NET Core 2.2 (the latest ASP.NET Core version compatible with .NET Framework). Unlike ASP.NET Core 2.1, 2.2 is longer supported, but since it's listed as the latest 2.x version available on NuGet.org, many people use it thinking it is the supported version. By rebranding 2.1 to 2.3, the unsupported 2.2 packages no longer appear as the latest 2.x packages.
The thing is: while it was released as a minor version update, ASP.NET Core 2.3 is not 100% compatible with ASP.NET Core 2.2, as none of the changes or APIs introduced in 2.2 – no longer supported since December 2019 – is present in 2.3. Unfortunately, since security fixes for the ASP.NET Core 2.x branch now exclusively ship as 2.3.x packages, updating the version referenced by OpenIddict was essential to ensure OpenIddict users are always running a supported and secure version.
When migrating to OpenIddict 7.0, you'll need to carefully review your dependencies to ensure your application doesn't accidentally depend on any ASP.NET Core 2.2-specific API or package and still runs fine on 2.3.
OpenIddict 7.0 now references .NET Extensions 8.0 on .NET Framework 4.6.2+ and .NET Standard 2.0/2.1
While ASP.NET Core 2.1 referenced the 2.1 version of the Microsoft.Extensions.*
packages, ASP.NET Core 2.3 now references the 8.0 version: as such, all the OpenIddict packages – even those who don't reference ASP.NET Core – have been updated to use the 8.0 version, which allowed introducing some significant improvements
Canary testing has confirmed that OWIN/Katana or "legacy" ASP.NET 4.6.2+ applications are not negatively impacted by this change: in almost all cases, regenerating (or manually updating the binding redirects if necessary) after migrating to OpenIddict 7.0 is enough to ensure the application will still work fine after the migration.
For more information, see Update the .NET Framework/.NET Standard TFMs to reference ASP.NET Core/Entity Framework Core 2.3 and the .NET Extensions version 8.0.
The Entity Framework Core stores now require Entity Framework Core 2.3+
Exactly like ASP.NET Core, Entity Framework Core 2.1 was re-released as 2.3 (but doesn't include any of the changes introduced in 2.2). Since security and critical bug fixes for Entity Framework Core on .NET Framework will be released as 2.3.x packages, I decided to also require 2.3 as the minimal version for projects referencing the .NET Framework 4.6.2+ and .NET Standard 2.0/2.1 assemblies of the OpenIddict Entity Framework Core stores.
When migrating to OpenIddict 7.0, you'll need to test your application to ensure it doesn't depend on any Entity Framework Core 2.2-specific API or logic.
The OpenIddict packages are now trimming/Native AOT-compatible on .NET 9.0 and higher
As part of this release, a huge effort was dedicated to making all the OpenIddict assemblies trimming and Native AOT-compatible. While removing code that couldn't be statically analyzed by the IL trimmer required introducing massive changes in the core stack, these changes should be transparent to most users.
MongoDB and Entity Framework Core are not yet fully compatible with trimming and Native AOT, so rough edges are expected when using the OpenIddict MongoDB or Entity Framework Core stores. It's likely future versions will improve that.
For more information, see Remove all the store resolvers and mark all the assemblies as trimming/Native AOT-compatible.
OAuth 2.0 Token Exchange is now supported by the client and server stacks
OAuth 2.0 Token Exchange was by far the most requested feature and it's finally landing in OpenIddict 7.0!
If you've already implemented the refresh token flow in your application, implementing OAuth 2.0 Token Exchange should feel extremely familiar:
1 | services.AddOpenIddict() |
1 | // Ask OpenIddict to send the specified subject token (and actor token, if available). |
1 | [ ] |
For more information, see Implement built-in delegation/impersonation support (RFC8693) and Implement OAuth 2.0 Token Exchange support.
OpenIddict 7.0 implements the Updates to Audience Values for OAuth 2.0 Authorization Servers draft to address a security issue
OpenIddict 7.0 proactively implements the Updates to Audience Values for OAuth 2.0 Authorization Servers draft: while it hasn't been officially adopted yet, it fixes a vulnerability affecting the standard private_jwt_key
client authentication method. Since this draft introduces important breaking changes in multiple OAuth 2.0 and OpenID Connect specifications to mitigate the vulnerability, implementing it in OpenIddict 7.0 was a better option than having to the next major version to address this issue.
Due to this change, the following cases won't be supported by OpenIddict 7.0:
- The application authenticates using the OpenIddict client with a third-party server that requires the use of the
token_endpoint
as the audience of client assertions, even for endpoints other than the token endpoint (e.g., the "pushed authorization endpoint" or the "introspection endpoint"). - The application authenticates using the OpenIddict client with a third-party server that does not support the new
client-authentication+jwt
JSON Web Token type defined by the specification for client assertions. - The application uses the OpenIddict server and allows clients to authenticate with client assertions that use
token_endpoint
instead ofissuer
as the audience. - The application uses the OpenIddict server and allows clients to authenticate with client assertions that do not use the new
client-authentication+jwt
JSON Web Token type.
The OpenIddict client, server and validation stacks have all been updated to support the new requirements introduced by this specification and it is expected that other implementations will make similar changes in the future. OpenIddict 7.0 doesn't allow reverting to the unsafe behavior, but I'll monitor the situation to determine whether opt-in compatibility quirks should be introduced in a future version to support unsafe client assertions.
Migration
While OpenIddict 7.0 comes with some breaking changes, the migration process shouldn't be too complicated. To help users with this process, an OpenIddict 7.0 migration guide was added to the documentation.
OpenIddict 7.0 is fully compatible with ASP.NET Core 2.3 (on .NET Framework), 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 7.0 being now generally available, the previous version, OpenIddict 6.0, stops being supported and won't receive bug fixes or security updates. As such, it is recommended to migrate to OpenIddict 7.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 | 9.x | Currently supported |
7.x (current) | Not supported yet | Not supported yet |
- OpenIddict sponsors are offered extended support depending on the selected sponsorship tier:
- Tier 6 sponsors get full support for the previous version 1 month following the release of a new major version.
- Tier 7 sponsors get full support for the previous version 6 months following the release of a new major version.
- Tier 8 sponsors get full support for the previous version 12 months following the release of a new major version.
- Tier 9 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 | Tier 6 | January 18, 2024 |
4.x | Tier 7 | June 18, 2024 |
4.x | Tier 8 | December 18, 2024 |
4.x | Tier 9 | December 18, 2025 |
5.x | Tier 6 | January 17, 2025 |
5.x | Tier 7 | June 17, 2025 |
5.x | Tier 8 | December 17, 2025 |
5.x | Tier 9 | December 17, 2026 |
6.x | Tier 6 | August 7, 2025 |
6.x | Tier 7 | January 7, 2026 |
6.x | Tier 8 | July 7, 2026 |
6.x | Tier 9 | July 7, 2027 |
7.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:
Happy summer everyone! 🏖️