ASP.NET Core 8.0安全令牌事件变更解析：从JwtSecurityToken到JsonWebToken

ASP.NET Core 8.0安全令牌事件变更解析：从JwtSecurityToken到JsonWebToken

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs

引言

在ASP.NET Core 8.0中，微软对安全令牌处理机制进行了重要优化，将默认的令牌实现从JwtSecurityToken迁移到了性能更优的JsonWebToken。这一变更影响了JwtBearer、WsFederation和OpenIdConnect等认证处理器的事件处理逻辑。本文将深入解析这一变更的技术细节、背景原因以及开发者需要注意的兼容性问题。

变更概述

在ASP.NET Core 8.0之前，当使用JWT(JSON Web Token)认证时，系统默认使用System.IdentityModel.Tokens.Jwt命名空间下的JwtSecurityToken类来表示安全令牌。从8.0版本开始，这一默认实现变更为Microsoft.IdentityModel.JsonWebTokens命名空间下的JsonWebToken类。

这一变更影响了以下认证处理器的事件上下文对象中的SecurityToken属性：

• JwtBearer认证的TokenValidatedContext.SecurityToken
• WsFederation认证的SecurityTokenValidatedContext.SecurityToken
• OpenIdConnect认证的TokenValidatedContext.SecurityToken和AuthorizationCodeReceivedContext.SecurityToken

技术背景

新旧实现对比

JwtSecurityToken是早期的JWT实现，属于System.IdentityModel.Tokens.Jwt库的一部分。它提供了完整的JWT处理功能，但在性能上存在优化空间。

JsonWebToken是新一代实现，属于Microsoft.IdentityModel.JsonWebTokens库。它针对现代应用场景进行了深度优化，具有以下优势：

1. 性能提升30%：通过优化内部数据结构和处理逻辑
2. 更可靠的元数据处理：采用"last known good"策略缓存OpenID Connect元数据
3. 原生支持异步处理模型
4. 更精简的内存占用

变更影响范围

虽然公共API的返回类型仍然是抽象的SecurityToken基类，但实际运行时类型发生了变化。这意味着：

• 如果代码仅通过SecurityToken抽象接口使用令牌对象，不受影响
• 如果代码将SecurityToken向下转型为具体的JwtSecurityToken类型，则需要调整

兼容性处理

推荐做法

最佳实践是尽量使用SecurityToken抽象接口，避免依赖具体实现类型。大多数标准场景（如获取声明、验证令牌等）都可以通过基类接口完成。

代码适配方案

如果现有代码确实需要访问具体类型的成员，有两种适配方案：

方案一：转型为JsonWebToken

services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options => {
    options.Events.OnTokenValidated = context => {
        // 新的转型方式
        if (context.SecurityToken is JsonWebToken jsonWebToken)
        {
            // 使用jsonWebToken访问特有成员
            var claim = jsonWebToken.GetClaim("custom_claim");
        }
        return Task.CompletedTask;
    };
});

方案二：回退到旧版处理器

可以通过设置选项属性强制使用旧版处理器：

services.Configure<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme, options => {
    options.UseSecurityTokenValidators = true; // 启用旧版处理器
    options.Events.OnTokenValidated = context => {
        // 保持原有代码不变
        if (context.SecurityToken is JwtSecurityToken jwtSecurityToken)
        {
            // 原有逻辑
        }
        return Task.CompletedTask;
    };
});

支持此配置的选项类包括：

• JwtBearerOptions.UseSecurityTokenValidators
• WsFederationOptions.UseSecurityTokenValidators
• OpenIdConnectOptions.UseSecurityTokenValidators

声明映射变更

除了令牌类型的变更外，默认的声明类型映射也有相应调整：

• 旧版：JwtSecurityTokenHandler.DefaultInboundClaimTypeMap
• 新版：JsonWebTokenHandler.DefaultInboundClaimTypeMap

如果应用依赖特定的声明映射规则，需要在迁移时注意这一变化。

升级建议

1. 评估影响：检查项目中是否存在对JwtSecurityToken的直接依赖
2. 性能测试：新版实现在高并发场景下性能提升明显
3. 逐步迁移：可以先在测试环境验证，再逐步推广到生产环境
4. 监控调整：关注认证相关的日志和指标，确保无异常

总结

ASP.NET Core 8.0将安全令牌的默认实现从JwtSecurityToken迁移到JsonWebToken是一项重要的性能优化。虽然大多数应用无需修改代码，但直接依赖具体类型的场景需要进行适配。开发者可以根据实际情况选择直接使用新类型或暂时回退到旧版处理器，平衡兼容性与性能需求。

docs This repository contains .NET Documentation. 项目地址: https://gitcode.com/gh_mirrors/docs2/docs