ASP.NET Core Data Protection integration clientservervalidation

Both the OpenIddict client and server features can be configured to use ASP.NET Core Data Protection to create opaque binary tokens instead of JSON Web Tokens. ASP.NET Core Data Protection uses its own key ring to encrypt and protect tokens against tampering and is supported for all types of tokens, except identity tokens, that are always JWT tokens.

Unlike JWTs, ASP.NET Core Data Protection tokens only support symmetric encryption and rely on a binary format created 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.

TIP

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.

Basic configuration clientservervalidation

To configure the ASP.NET Core integration, you'll need to:

• Reference the OpenIddict.Client.DataProtection and/or OpenIddict.Server.DataProtection and/or OpenIddict.Validation.DataProtection packages (depending on whether you need the client and/or server and/or validation features in your project):

IMPORTANT

These packages are referenced by the OpenIddict.AspNetCore metapackage (and therefore don't have to be referenced explicitly when using it) but they are not referenced by the OpenIddict.Owin metapackage: if you want to use ASP.NET Core Data Protection in a legacy ASP.NET 4.6.1+ application, you need to manually reference the OpenIddict.Client.DataProtection, OpenIddict.Server.DataProtection and OpenIddict.Validation.DataProtection packages.

• Call options.UseDataProtection() for each OpenIddict feature (client, server and validation) with which you want to use ASP.NET Core Data Protection:

services.AddOpenIddict()
    .AddClient(options =>
    {
        options.UseDataProtection();
    })
    .AddServer(options =>
    {
        options.UseDataProtection();
    })
    .AddValidation(options =>
    {
        options.UseDataProtection();
    });

IMPORTANT

If you decide to use ASP.NET Core Data Protection for the tokens generated by the server stack, make sure you're also enabling the ASP.NET Core Data Protection integration in the validation options (so that the access tokens can be properly validated by your APIs).

NOTE

Switching to ASP.NET Core Data Protection tokens doesn't prevent JWT tokens issued before Data Protection support was enabled 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.

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 the OpenIddict validation 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.

Advanced configuration

Default token format clientservervalidation

By default, enabling ASP.NET Core Data Protection support will automatically switch the token format from JWT to Data Protection for all types of tokens (except identity tokens, that are always JWT tokens by definition).

The OpenIddict/Data Protection integration can be configured to prefer JWT when creating new tokens, which can be useful when using 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()
    .AddClient(options =>
    {
        options.UseDataProtection()
               .PreferDefaultStateTokenFormat();
    })
    .AddServer(options =>
    {
        options.UseDataProtection()
               .PreferDefaultAccessTokenFormat()
               .PreferDefaultAuthorizationCodeFormat()
               .PreferDefaultDeviceCodeFormat()
               .PreferDefaultRefreshTokenFormat()
               .PreferDefaultUserCodeFormat();
    });