Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Breaking change]: JwtBearer, WsFederation, and OpenIdConnect events context properties of type SecurityToken now return a JSonWebToken by default #508

Open
1 of 3 tasks
jmprieur opened this issue Jul 19, 2023 · 0 comments
Labels
8.0.0 Breaking change Documented The breaking change has been published to the .NET Core docs

Comments

@jmprieur
Copy link

jmprieur commented Jul 19, 2023

Description

The JwtBearerEvents, WsFederationEvents and OpenIdConnectEvents are authentication events fired respectively by the JwtBearer, WsFederation and OpenIdConnect authentication handlers. For example the OnTokenValidated event is fired when a security token is validated. These events are fired with a context (for instance TokenValidatedContext) that exposes a SecurityToken property of abstract type SecurityToken. The default real implementation of SecurityToken changed from JwtSecurityToken to JsonWebToken.
If you really need to keep using JwtSecurityToken, you can re-enable it by setting UseSecurityTokenValidators on the JwtBearerOptions, WsFederationOptions, OpenIdConnectOptions.

For details #aspnetcore/49469 API Review.

Version

.NET 8 Preview 7

Previous behavior

Until ASP.NET Core 8-preview 7, these SecurityToken properties were implemented by a sub-class of SecurityToken named JwtSecurityToken, which is the previous generation of implementation of JWT. These JwtSecurityToken were produced by SecurityTokenValidators.

New behavior

From ASP.NET Core 8-preview 7, by default the class derived from SecurityToken implenting these properties is JSonWebToken which are produced by more optimized TokenHandlers.

Type of breaking change

  • Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
  • Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
  • Behavioral change: Existing binaries may behave differently at run time.

Reason for change

This change was made because JSonWebToken (and its associated JSonWebTokenHandler) are bringing:

  • 30% performance improvement.
  • Improved reliability by the usage of a Last Known Good metadata (such as the OpenIdConnectMetadata)
  • async processing

Recommended action

For most of you, this shouldn't be a problem as the type of the properties (SecurityToken) has not changed, and you were not supposed to look at the real type.

However, if you were downcasting one of these SecurityToken properties to JwtSecurityToken (for example to get the claims), you will now need to:

  • either down-cast them to JSonWebToken

    service.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme,  options => {
        options.Events.TokenValidated = (context) => {
            // Replace your cast to JwtSecurityToken.
            JSonWebToken token = context.SecurityToken as JSonWebToken;
            // Do something ...
        };
    });
  • or set one of the UseSecurityTokenValidators boolean properties on the corresponding options (JtwBearerOptions, WsFederationOptions, OpenIdConnectOptions) to true, in which case the authentication handlers will keep using the JwtTokenValidators and will keep producing JwtSecurityTokens.

    service.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme,  options => {
        options.UseSecurityTokenValidators = true;
        options.Events.TokenValidated = (context) => {
            // As you were doing before
            JwtSecurityToken token = context.SecurityToken as JwtSecurityToken;
            // Do something ...
        };
    });

Affected APIs

The properties that are concerned are the following:

In WsFederationEvents

In JwtBearerEvents

In OpenIdConnectEvents

@ghost ghost locked as resolved and limited conversation to collaborators Jul 19, 2023
@gewarren gewarren added the Documented The breaking change has been published to the .NET Core docs label Aug 2, 2023
@guardrex guardrex added the 8.0.0 label Nov 14, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
8.0.0 Breaking change Documented The breaking change has been published to the .NET Core docs
Projects
None yet
Development

No branches or pull requests

3 participants