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

[jmprieur]

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

• SecurityTokenValidatedContext.SecurityToken

In JwtBearerEvents

• TokenValidatedContext.SecurityToken

In OpenIdConnectEvents

• TokenValidatedContext.SecurityToken
• AuthorizationCodeReceivedContext.SecurityToken