Token formats
+ +JSON Web Token
+OpenIddict 3.0 implements the JSON Web Token, JSON Web Signature and JSON Web Encryption standards and relies on the +Azure Active Directory IdentityModel Extensions for .NET library +developed and maintained by Microsoft to generate signed and encrypted JWT tokens using the encryption and signing credentials registered in the server options.
+JWT token types
+To protect against token substitution and confused deputy attacks, OpenIddict 3.0 uses the standard typ JWT header to convey the actual token type.
+This mechanism replaces the private token_usage claim used for the same purpose in previous versions of OpenIddict.
As required by the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens draft,
+access tokens produced by OpenIddict 3.0 are always issued with a "typ": "at+jwt" header while identity tokens still use "typ": "JWT" for backward compatibility.
+Other types of tokens – only accepted by OpenIddict's own endpoints – use private token types prefixed by oi_.
Disabling JWT access token encryption
+By default, OpenIddict enforces encryption for all the token types it supports. While this enforcement cannot be disabled for authorization codes, +refresh tokens and device codes for security reasons, it can be relaxed for access tokens when integration with third-party APIs/resource servers is desired. +Access token encryption can also be disabled if the resource servers receiving the access tokens don't fully support JSON Web Encryption.
+services.AddOpenIddict()
+ .AddServer(options =>
+ {
+ options.DisableAccessTokenEncryption();
+ });
+ASP.NET Core Data Protection
+OpenIddict 3.0 can also be configured to use ASP.NET Core Data Protection to create +Data Protection tokens instead of JWT tokens. ASP.NET Core Data Protection is supported for all types of tokens, except identity tokens, that are always JWT tokens.
+Unlike JWT, ASP.NET Core Data Protection tokens only support symmetric encryption and rely on a binary format developed by the ASP.NET team rather than on a standard like JWT. +While this prevents using such tokens in scenarios where interoperability is needed, opting for ASP.NET Core Data Protection rather than JWT has actually a few advantages:
+-
+
- ASP.NET Core Data Protection tokens don't use a JSON representation and therefore are generally a bit shorter. +
- ASP.NET Core Data Protection has been designed to achieve high throughput as it's natively used by ASP.NET Core for authentication cookies, +antiforgery tokens and session cookies. +
Warning
Despite its name, ASP.NET Core Data Protection is not tied to ASP.NET Core and can be used in any
+.NET Standard 2.0-compatible application, including legacy ASP.NET 4.x applications using Microsoft.Owin.
To enable ASP.NET Core Data Protection support in the OpenIddict OWIN server and validation hosts, you need to
+manually reference the OpenIddict.Server.DataProtection and OpenIddict.Validation.DataProtection packages.
Switching to Data Protection tokens
+ASP.NET Core Data Protection support is provided by the OpenIddict.Server.DataProtection and OpenIddict.Validation.DataProtection packages.
+These packages are referenced by the OpenIddict.AspNetCore metapackage and therefore don't have to be referenced explicitly.
To enable ASP.NET Core Data Protection support, call options.UseDataProtection() in both the server and validation options:
services.AddOpenIddict()
+ .AddServer(options =>
+ {
+ options.UseDataProtection();
+ })
+
+ .AddValidation(options =>
+ {
+ options.UseDataProtection();
+ });
+Note
Switching to ASP.NET Core Data Protection tokens doesn't prevent JWT tokens issued before Data Protection support was enabled from being validated: +existing tokens can still be used alongside newly issued ASP.NET Core Data Protection tokens until they expire. When sending a refresh token request containing +a JWT refresh token, the application will receive an ASP.NET Core Data Protection refresh token and the previous one will be automatically marked as redeemed.
+By default, enabling ASP.NET Core Data Protection support will automatically switch the token format from JWT to Data Protection for all tokens, except JWT tokens. +The OpenIddict/Data Protection integration can be configured to prefer JWT when creating new tokens, which can be useful to use the ASP.NET Core Data Protection +format for specific token types only (e.g for authorization codes and refresh tokens, but not for access tokens).
+services.AddOpenIddict()
+ .AddServer(options =>
+ {
+ options.UseDataProtection()
+ .PreferDefaultAccessTokenFormat()
+ .PreferDefaultAuthorizationCodeFormat()
+ .PreferDefaultDeviceCodeFormat()
+ .PreferDefaultRefreshTokenFormat()
+ .PreferDefaultUserCodeFormat();
+ });
+Warning
When the authorization and API/resource servers are not part of the same application, ASP.NET Core Data Protection MUST be configured to use +the same application name and share the same key ring to allow OpenIddict validation's handler to read ASP.NET Core Data Protection tokens +generated by an authorization server located in another project.
+For more information, read Configure ASP.NET Core Data Protection.
+