ASP.NET Core JwtBearer 认证包实战从 JWT 校验到事件扩展的完整指南【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore导读Microsoft.AspNetCore.Authentication.JwtBearer是 ASP.NET Core 框架中负责JWTJSON Web TokenBearer 认证的核心中间件组件。本文以该包在aspnetcore仓库包说明文档、源码目录中的实现为主线完整讲解其工作原理、配置项、事件钩子与实战用法。读完本文你将能够在 ASP.NET Core 应用含最小 API中快速接入 JWT 认证理解令牌从Authorization请求头解析到校验、生成ClaimsPrincipal的全流程掌握签发方/受众/签名密钥/有效期等TokenValidationParameters的每一项配置并学会利用JwtBearerEvents在认证链的关键节点注入自定义逻辑如从 Cookie 或查询参数读取令牌、审计登录、自定义 401 响应等。包概览与核心定位JwtBearer 包是一个面向 API 与 Web 服务的无状态认证中间件它不签发令牌只负责验证由外部认证服务器如 IdentityServer、Azure AD、自定义 STS签发的 JWT。认证成功后将令牌中的声明Claims组装为ClaimsPrincipal交由后续授权逻辑如[Authorize]、RequireAuthorization()使用。按仓库内 PACKAGE.md 的说明其关键特性包括与 ASP.NET Core 应用无缝集成通过services.AddAuthentication(...).AddJwtBearer(...)一行接入支持完整的 JWT 校验签名、签发方、受众、有效期提供高度灵活的TokenValidationParameters配置支持 .NET Core 3.0 及更新版本以及 .NET Standard 2.1。包中还内置了两个可直接运行、用于验证 API 的示例传统的 JwtBearerSample使用Startup类 OIDC 认证服务器与最小 API 风格的 MinimalJwtBearerSample。快速上手最小配置示例配置认证服务以下配置来自包文档的官方示例PACKAGE.md演示了使用对称密钥SymmetricSecurityKey进行本地签名校验的经典写法using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.Extensions.DependencyInjection; using Microsoft.IdentityModel.Tokens; using System.Text; public void ConfigureServices(IServiceCollection services) { services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, // 校验签发方 ValidateAudience true, // 校验受众 ValidateLifetime true, // 校验有效期过期/未生效 ValidateIssuerSigningKey true, // 校验签名密钥 ValidIssuer your_issuer, ValidAudience your_audience, IssuerSigningKey new SymmetricSecurityKey(Encoding.UTF8.GetBytes(your_secret_key)) }; }); // 其他配置... }注意AddAuthentication中传入的JwtBearerDefaults.AuthenticationScheme即字符串Bearer定义见 JwtBearerDefaults.cs它表示默认认证方案后续[Authorize]或RequireAuthorization()会默认走该方案。完整的最小 API 示例仓库中的 MinimalJwtBearerSample 展示了更贴近现代写法的接入方式并且同时注册了多个命名方案using System.Security.Claims; var builder WebApplication.CreateBuilder(args); builder.Services.AddAuthentication() .AddJwtBearer() .AddJwtBearer(ClaimedDetails) .AddJwtBearer(InvalidScheme); builder.Services.AddAuthorization(options options.AddPolicy(is_admin, policy { policy.RequireAuthenticatedUser(); policy.RequireClaim(is_admin, true); })); var app builder.Build(); app.MapGet(/protected, (ClaimsPrincipal user) $Hello {user.Identity?.Name}!) .RequireAuthorization(); app.MapGet(/protected-with-claims, (ClaimsPrincipal user) { return $Glory be to the admin {user.Identity?.Name}!; }) .RequireAuthorization(is_admin); app.Run();该示例体现了三点实战技巧多方案注册可多次调用AddJwtBearer(SchemeName)注册多个独立方案各自配置不同的校验参数声明策略授权RequireClaim(is_admin, true)直接基于令牌中的自定义声明做策略授权无需额外查库最小 API 直接注入ClaimsPrincipal user参数由框架自动注入可直接读取user.Identity.Name。集成 OIDC 认证服务器的典型配置在实际生产中JWT 通常由 OpenID Connect 认证服务器签发。此时无需手工指定签名密钥只需配置Authority权威端点与Audience受众框架会自动从/.well-known/openid-configuration获取元数据与签名密钥。仓库示例 JwtBearerSample/Startup.cs 给出了这种模式services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(o { // 需与前端 /wwwroot/app/scripts/app.js 中的配置保持一致 o.Authority Configuration[oidc:authority]; o.Audience Configuration[oidc:clientid]; });核心类型一览包文档列出的四个主要类型PACKAGE.md如下其中wtBearerOptions为文档笔误实际类型名为JwtBearerOptions类型文件职责JwtBearerDefaultsJwtBearerDefaults.cs提供默认认证方案名常量BearerJwtBearerEventsJwtBearerEvents.cs定义认证过程中的事件委托供应用注入自定义处理JwtBearerHandlerJwtBearerHandler.cs认证处理器核心负责令牌提取、校验、挑战Challenge与禁止ForbidJwtBearerOptionsJwtBearerOptions.cs认证行为的全部可配置项认证入口AddJwtBearer 扩展方法JwtBearerExtensions.cs 提供了 5 个重载覆盖无参默认方案 / 指定方案 / 指定方案配置委托 / 指定方案显示名配置委托等场景。其最完整的重载内部会注册JwtBearerConfigureOptions从IConfiguration绑定配置注册JwtBearerPostConfigureOptions补全元数据地址、创建回退通道等默认行为调用AddSchemeJwtBearerOptions, JwtBearerHandler(...)注册方案与处理器。public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder, string authenticationScheme, string? displayName, ActionJwtBearerOptions configureOptions) { builder.Services.TryAddEnumerable(ServiceDescriptor.SingletonIConfigureOptionsJwtBearerOptions, JwtBearerConfigureOptions()); builder.Services.TryAddEnumerable(ServiceDescriptor.SingletonIPostConfigureOptionsJwtBearerOptions, JwtBearerPostConfigureOptions()); return builder.AddSchemeJwtBearerOptions, JwtBearerHandler(authenticationScheme, displayName, configureOptions); }JwtBearerOptions 全量配置详解JwtBearerOptions.cs 继承自AuthenticationSchemeOptions其公开属性按功能可分为四组下表汇总了默认值均以当前仓库源码为准1. 令牌校验参数属性默认值说明TokenValidationParametersnew TokenValidationParameters()校验 JWT 的核心参数对象见下文专节Audiencenull期望的受众值若TokenValidationParameters.ValidAudience为空会被自动写入MapInboundClaimstrue是否将入站 JWT 声明名映射为 .NET 标准声明名如name→http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name同时同步到默认的JwtSecurityTokenHandler与JsonWebTokenHandlerUseSecurityTokenValidatorsfalsefalse时使用TokenHandlers异步、更快的JsonWebTokenHandlertrue时回退到旧的SecurityTokenValidators同步、JwtSecurityTokenHandler当TokenValidatedContext.SecurityToken需要JwtSecurityToken类型时使用2. 元数据发现与回退通道OIDC 模式属性默认值说明AuthoritynullOIDC 权威端点若未设置MetadataAddress会自动拼接/.well-known/openid-configurationMetadataAddressnull元数据发现端点优先级高于AuthorityRequireHttpsMetadatatrue元数据地址是否必须为 HTTPS仅在开发环境可设为false否则启动即抛InvalidOperationExceptionConfigurationnull直接提供的静态OpenIdConnectConfiguration设置后不再走元数据发现与回退通道ConfigurationManagernull负责元数据的获取、缓存与刷新默认由MetadataAddressBackchannel自动创建BackchannelHttpHandlernull拉取元数据所用的HttpMessageHandlerBackchannelnull拉取元数据的HttpClient自动创建BackchannelTimeout1 分钟回退通道 HTTP 调用的超时时间AutomaticRefreshIntervalConfigurationManager默认值元数据自动刷新间隔RefreshIntervalConfigurationManager默认值元数据获取失败或显式请求刷新时的最小重试间隔RefreshOnIssuerKeyNotFoundtrue遇到SecurityTokenSignatureKeyNotFoundException签名密钥轮换时自动请求刷新元数据默认开启3. 响应与令牌处理属性默认值说明ChallengeBearer即JwtBearerDefaults.AuthenticationScheme写入WWW-Authenticate响应头的质询文本IncludeErrorDetailstrue校验失败时是否在WWW-Authenticate头中返回error/error_description设false可避免向调用方泄露错误细节SaveTokentrue认证成功后是否把access_token存入AuthenticationProperties供后续重放/转发4. 事件属性默认值说明Eventsnew JwtBearerEvents()处理认证各阶段事件的对象见下文专节TokenValidationParameters 各校验开关该对象由Microsoft.IdentityModel.Tokens提供是令牌校验的裁判常用开关如下属性作用ValidateIssuer校验签发方是否在ValidIssuer/ValidIssuers中ValidIssuer/ValidIssuers合法签发方单个 / 多个ValidateAudience校验受众是否在ValidAudience/ValidAudiences中ValidAudience/ValidAudiences合法受众单个 / 多个ValidateLifetime校验nbf生效时间与exp过期时间ValidateIssuerSigningKey校验签名密钥IssuerSigningKey/IssuerSigningKeys对称密钥或公钥单个 / 多个多个可支持密钥轮换ClockSkew时钟偏移容忍量默认约 5 分钟缓解认证服务器与应用服务器时间差配置选项的自动绑定AddJwtBearer会自动注册 JwtBearerConfigureOptions.cs它会把appsettings.json中Authentication:Schemes:Bearer等配置节按方案名匹配绑定到选项上。支持从配置直接读取Authority、MetadataAddress、Challenge、IncludeErrorDetails、MapInboundClaims、SaveToken、RequireHttpsMetadata、RefreshOnIssuerKeyNotFound、BackchannelTimeout、RefreshInterval以及TokenValidationParameters下的ValidateIssuer、ValidIssuer(s)、ValidateAudience、ValidAudience(s)并通过SigningKeys:Issuer/SigningKeys:Value数组自动构造对称签名密钥。这意味着密钥等敏感配置可安全存放于配置系统配合用户机密/环境变量。认证处理流程JwtBearerHandler 源码解析JwtBearerHandler.cs 是理解 JwtBearer 内部机制的关键其HandleAuthenticateAsync方法L56-L220完整展现了认证流水线触发MessageReceived事件先给应用机会从其它位置如 Cookie、查询字符串提供令牌或直接拒绝请求L62-L65从请求头提取令牌若无事件提供的令牌则读取Authorization头若以Bearer 不区分大小写开头则截取其后内容并Trim()无头或无令牌时返回NoResult()L74-L94准备校验参数SetupTokenValidationParametersAsync会克隆TokenValidationParameters以避免并发请求间的竞态并在使用ConfigurationManager时合并元数据中的ValidIssuers与IssuerSigningKeysL239-L261逐个校验器尝试默认遍历TokenHandlers调用ValidateTokenAsyncUseSecurityTokenValidatorstrue时遍历SecurityTokenValidators先CanReadToken再ValidateToken。任一校验器成功即中断L101-L147校验成功构造ClaimsPrincipal把ValidTo/ValidFrom写入Properties.ExpiresUtc/IssuedUtc触发TokenValidated事件若SaveTokentrue则将令牌以access_token名义存入AuthenticationProperties最后Success()L149-L177校验失败汇总所有校验异常单个或AggregateException触发AuthenticationFailed事件后返回Fail(...)L180-L194密钥轮换自动恢复RecordTokenValidationError在捕获SecurityTokenSignatureKeyNotFoundException且RefreshOnIssuerKeyNotFoundtrue时调用ConfigurationManager.RequestRefresh()刷新元数据L222-L237。HandleChallengeAsyncL275-L346则负责生成 401 响应当IncludeErrorDetails且存在认证失败时会依据异常类型生成符合 RFC 6750 的WWW-Authenticate: Bearer errorinvalid_token, error_description...头。错误描述与异常类型一一对应例如SecurityTokenExpiredException→The token expired at ...SecurityTokenInvalidAudienceException→The audience ... is invalidSecurityTokenInvalidIssuerException→The issuer ... is invalidSecurityTokenSignatureKeyNotFoundException→The signature key was not foundHandleForbiddenAsyncL349-L367在授权失败时返回 403 并触发Forbidden事件。JwtBearerEvents认证事件扩展点JwtBearerEvents.cs 提供 5 个事件委托均默认为空操作覆盖认证全生命周期事件触发时机典型用途OnMessageReceived收到协议消息、提取令牌之前从 Cookie/查询参数等其它位置获取令牌拒绝特定令牌OnTokenValidated令牌通过校验、ClaimsIdentity生成后加载附加声明、写审计日志、二次校验、下发自定义令牌OnChallenge返回 401 质询之前自定义 401 响应体、改写WWW-Authenticate头OnAuthenticationFailed令牌校验失败后记录失败原因、返回自定义错误OnForbidden授权失败返回 403 时自定义 403 响应各事件对应的上下文类型继承自ResultContextJwtBearerOptions可通过设置context.Result干预默认行为。例如MessageReceivedContext.Token属性MessageReceivedContext.cs允许在事件中手动注入令牌TokenValidatedContext.SecurityTokenTokenValidatedContext.cs持有校验后的令牌对象JwtBearerChallengeContextJwtBearerChallengeContext.cs暴露Error/ErrorDescription/ErrorUri/Handled供自定义质询。services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.Events new JwtBearerEvents { OnMessageReceived context { // 从查询字符串读取令牌如 WebSocket / SignalR 场景 var accessToken context.Request.Query[access_token]; if (!string.IsNullOrEmpty(accessToken)) { context.Token accessToken; } return Task.CompletedTask; }, OnTokenValidated context { // 令牌校验成功后写审计日志或补充声明 Console.WriteLine($Token validated for {context.Principal.Identity?.Name}); return Task.CompletedTask; }, OnChallenge context { // 自定义 401 响应内容 context.HandleResponse(); context.Response.StatusCode 401; return context.Response.WriteAsJsonAsync(new { error unauthorized }); } }; });注意当context.HandleResponse()被调用时处理器将跳过默认的 401 写入逻辑见 JwtBearerChallengeContext.cs因此需要自行设置状态码与响应内容。元数据发现与配置后处理JwtBearerPostConfigureOptions.cs 在配置阶段完成默认行为的兜底若TokenValidationParameters.ValidAudience为空且设置了Audience则自动写入L23-L26若未提供ConfigurationManager有静态Configuration则包装为StaticConfigurationManager否则从Authority推导MetadataAddress追加/.well-known/openid-configuration校验 HTTPS 要求创建带默认请求头Microsoft ASP.NET Core JwtBearer handler、10 MB 响应上限与超时设置的HttpClient最后构造ConfigurationManagerL28-L66。这解释了为何只配置Authority就能完成 OIDC 模式的自动发现与签名密钥下载。从源码构建与测试仓库内 README.md 给出了构建与测试指引在src/Security/Authentication目录下执行./build.cmd构建、./build.cmd -t运行测试也可在测试项目目录下用dotnet test运行单个项目的测试。完整的源码构建流程可参考仓库 docs/BuildFromSource.md。结语Microsoft.AspNetCore.Authentication.JwtBearer以轻配置、强校验、可扩展的设计成为 ASP.NET Core 生态中接入 JWT 认证的标准路径本地对称密钥场景只需配置一组TokenValidationParameters生产级 OIDC 场景则通过Authority/Audience实现元数据自动发现与密钥轮换自愈而JwtBearerEvents五个事件钩子让开发者能够在认证链的任何关键节点注入自定义逻辑。理解 JwtBearerHandler 的认证流水线与其选项模型即可在真实项目中游刃有余地定制安全认证方案。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ASP.NET Core JwtBearer 认证包实战：从 JWT 校验到事件扩展的完整指南
ASP.NET Core JwtBearer 认证包实战从 JWT 校验到事件扩展的完整指南【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore导读Microsoft.AspNetCore.Authentication.JwtBearer是 ASP.NET Core 框架中负责JWTJSON Web TokenBearer 认证的核心中间件组件。本文以该包在aspnetcore仓库包说明文档、源码目录中的实现为主线完整讲解其工作原理、配置项、事件钩子与实战用法。读完本文你将能够在 ASP.NET Core 应用含最小 API中快速接入 JWT 认证理解令牌从Authorization请求头解析到校验、生成ClaimsPrincipal的全流程掌握签发方/受众/签名密钥/有效期等TokenValidationParameters的每一项配置并学会利用JwtBearerEvents在认证链的关键节点注入自定义逻辑如从 Cookie 或查询参数读取令牌、审计登录、自定义 401 响应等。包概览与核心定位JwtBearer 包是一个面向 API 与 Web 服务的无状态认证中间件它不签发令牌只负责验证由外部认证服务器如 IdentityServer、Azure AD、自定义 STS签发的 JWT。认证成功后将令牌中的声明Claims组装为ClaimsPrincipal交由后续授权逻辑如[Authorize]、RequireAuthorization()使用。按仓库内 PACKAGE.md 的说明其关键特性包括与 ASP.NET Core 应用无缝集成通过services.AddAuthentication(...).AddJwtBearer(...)一行接入支持完整的 JWT 校验签名、签发方、受众、有效期提供高度灵活的TokenValidationParameters配置支持 .NET Core 3.0 及更新版本以及 .NET Standard 2.1。包中还内置了两个可直接运行、用于验证 API 的示例传统的 JwtBearerSample使用Startup类 OIDC 认证服务器与最小 API 风格的 MinimalJwtBearerSample。快速上手最小配置示例配置认证服务以下配置来自包文档的官方示例PACKAGE.md演示了使用对称密钥SymmetricSecurityKey进行本地签名校验的经典写法using Microsoft.AspNetCore.Authentication.JwtBearer; using Microsoft.Extensions.DependencyInjection; using Microsoft.IdentityModel.Tokens; using System.Text; public void ConfigureServices(IServiceCollection services) { services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.TokenValidationParameters new TokenValidationParameters { ValidateIssuer true, // 校验签发方 ValidateAudience true, // 校验受众 ValidateLifetime true, // 校验有效期过期/未生效 ValidateIssuerSigningKey true, // 校验签名密钥 ValidIssuer your_issuer, ValidAudience your_audience, IssuerSigningKey new SymmetricSecurityKey(Encoding.UTF8.GetBytes(your_secret_key)) }; }); // 其他配置... }注意AddAuthentication中传入的JwtBearerDefaults.AuthenticationScheme即字符串Bearer定义见 JwtBearerDefaults.cs它表示默认认证方案后续[Authorize]或RequireAuthorization()会默认走该方案。完整的最小 API 示例仓库中的 MinimalJwtBearerSample 展示了更贴近现代写法的接入方式并且同时注册了多个命名方案using System.Security.Claims; var builder WebApplication.CreateBuilder(args); builder.Services.AddAuthentication() .AddJwtBearer() .AddJwtBearer(ClaimedDetails) .AddJwtBearer(InvalidScheme); builder.Services.AddAuthorization(options options.AddPolicy(is_admin, policy { policy.RequireAuthenticatedUser(); policy.RequireClaim(is_admin, true); })); var app builder.Build(); app.MapGet(/protected, (ClaimsPrincipal user) $Hello {user.Identity?.Name}!) .RequireAuthorization(); app.MapGet(/protected-with-claims, (ClaimsPrincipal user) { return $Glory be to the admin {user.Identity?.Name}!; }) .RequireAuthorization(is_admin); app.Run();该示例体现了三点实战技巧多方案注册可多次调用AddJwtBearer(SchemeName)注册多个独立方案各自配置不同的校验参数声明策略授权RequireClaim(is_admin, true)直接基于令牌中的自定义声明做策略授权无需额外查库最小 API 直接注入ClaimsPrincipal user参数由框架自动注入可直接读取user.Identity.Name。集成 OIDC 认证服务器的典型配置在实际生产中JWT 通常由 OpenID Connect 认证服务器签发。此时无需手工指定签名密钥只需配置Authority权威端点与Audience受众框架会自动从/.well-known/openid-configuration获取元数据与签名密钥。仓库示例 JwtBearerSample/Startup.cs 给出了这种模式services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(o { // 需与前端 /wwwroot/app/scripts/app.js 中的配置保持一致 o.Authority Configuration[oidc:authority]; o.Audience Configuration[oidc:clientid]; });核心类型一览包文档列出的四个主要类型PACKAGE.md如下其中wtBearerOptions为文档笔误实际类型名为JwtBearerOptions类型文件职责JwtBearerDefaultsJwtBearerDefaults.cs提供默认认证方案名常量BearerJwtBearerEventsJwtBearerEvents.cs定义认证过程中的事件委托供应用注入自定义处理JwtBearerHandlerJwtBearerHandler.cs认证处理器核心负责令牌提取、校验、挑战Challenge与禁止ForbidJwtBearerOptionsJwtBearerOptions.cs认证行为的全部可配置项认证入口AddJwtBearer 扩展方法JwtBearerExtensions.cs 提供了 5 个重载覆盖无参默认方案 / 指定方案 / 指定方案配置委托 / 指定方案显示名配置委托等场景。其最完整的重载内部会注册JwtBearerConfigureOptions从IConfiguration绑定配置注册JwtBearerPostConfigureOptions补全元数据地址、创建回退通道等默认行为调用AddSchemeJwtBearerOptions, JwtBearerHandler(...)注册方案与处理器。public static AuthenticationBuilder AddJwtBearer(this AuthenticationBuilder builder, string authenticationScheme, string? displayName, ActionJwtBearerOptions configureOptions) { builder.Services.TryAddEnumerable(ServiceDescriptor.SingletonIConfigureOptionsJwtBearerOptions, JwtBearerConfigureOptions()); builder.Services.TryAddEnumerable(ServiceDescriptor.SingletonIPostConfigureOptionsJwtBearerOptions, JwtBearerPostConfigureOptions()); return builder.AddSchemeJwtBearerOptions, JwtBearerHandler(authenticationScheme, displayName, configureOptions); }JwtBearerOptions 全量配置详解JwtBearerOptions.cs 继承自AuthenticationSchemeOptions其公开属性按功能可分为四组下表汇总了默认值均以当前仓库源码为准1. 令牌校验参数属性默认值说明TokenValidationParametersnew TokenValidationParameters()校验 JWT 的核心参数对象见下文专节Audiencenull期望的受众值若TokenValidationParameters.ValidAudience为空会被自动写入MapInboundClaimstrue是否将入站 JWT 声明名映射为 .NET 标准声明名如name→http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name同时同步到默认的JwtSecurityTokenHandler与JsonWebTokenHandlerUseSecurityTokenValidatorsfalsefalse时使用TokenHandlers异步、更快的JsonWebTokenHandlertrue时回退到旧的SecurityTokenValidators同步、JwtSecurityTokenHandler当TokenValidatedContext.SecurityToken需要JwtSecurityToken类型时使用2. 元数据发现与回退通道OIDC 模式属性默认值说明AuthoritynullOIDC 权威端点若未设置MetadataAddress会自动拼接/.well-known/openid-configurationMetadataAddressnull元数据发现端点优先级高于AuthorityRequireHttpsMetadatatrue元数据地址是否必须为 HTTPS仅在开发环境可设为false否则启动即抛InvalidOperationExceptionConfigurationnull直接提供的静态OpenIdConnectConfiguration设置后不再走元数据发现与回退通道ConfigurationManagernull负责元数据的获取、缓存与刷新默认由MetadataAddressBackchannel自动创建BackchannelHttpHandlernull拉取元数据所用的HttpMessageHandlerBackchannelnull拉取元数据的HttpClient自动创建BackchannelTimeout1 分钟回退通道 HTTP 调用的超时时间AutomaticRefreshIntervalConfigurationManager默认值元数据自动刷新间隔RefreshIntervalConfigurationManager默认值元数据获取失败或显式请求刷新时的最小重试间隔RefreshOnIssuerKeyNotFoundtrue遇到SecurityTokenSignatureKeyNotFoundException签名密钥轮换时自动请求刷新元数据默认开启3. 响应与令牌处理属性默认值说明ChallengeBearer即JwtBearerDefaults.AuthenticationScheme写入WWW-Authenticate响应头的质询文本IncludeErrorDetailstrue校验失败时是否在WWW-Authenticate头中返回error/error_description设false可避免向调用方泄露错误细节SaveTokentrue认证成功后是否把access_token存入AuthenticationProperties供后续重放/转发4. 事件属性默认值说明Eventsnew JwtBearerEvents()处理认证各阶段事件的对象见下文专节TokenValidationParameters 各校验开关该对象由Microsoft.IdentityModel.Tokens提供是令牌校验的裁判常用开关如下属性作用ValidateIssuer校验签发方是否在ValidIssuer/ValidIssuers中ValidIssuer/ValidIssuers合法签发方单个 / 多个ValidateAudience校验受众是否在ValidAudience/ValidAudiences中ValidAudience/ValidAudiences合法受众单个 / 多个ValidateLifetime校验nbf生效时间与exp过期时间ValidateIssuerSigningKey校验签名密钥IssuerSigningKey/IssuerSigningKeys对称密钥或公钥单个 / 多个多个可支持密钥轮换ClockSkew时钟偏移容忍量默认约 5 分钟缓解认证服务器与应用服务器时间差配置选项的自动绑定AddJwtBearer会自动注册 JwtBearerConfigureOptions.cs它会把appsettings.json中Authentication:Schemes:Bearer等配置节按方案名匹配绑定到选项上。支持从配置直接读取Authority、MetadataAddress、Challenge、IncludeErrorDetails、MapInboundClaims、SaveToken、RequireHttpsMetadata、RefreshOnIssuerKeyNotFound、BackchannelTimeout、RefreshInterval以及TokenValidationParameters下的ValidateIssuer、ValidIssuer(s)、ValidateAudience、ValidAudience(s)并通过SigningKeys:Issuer/SigningKeys:Value数组自动构造对称签名密钥。这意味着密钥等敏感配置可安全存放于配置系统配合用户机密/环境变量。认证处理流程JwtBearerHandler 源码解析JwtBearerHandler.cs 是理解 JwtBearer 内部机制的关键其HandleAuthenticateAsync方法L56-L220完整展现了认证流水线触发MessageReceived事件先给应用机会从其它位置如 Cookie、查询字符串提供令牌或直接拒绝请求L62-L65从请求头提取令牌若无事件提供的令牌则读取Authorization头若以Bearer 不区分大小写开头则截取其后内容并Trim()无头或无令牌时返回NoResult()L74-L94准备校验参数SetupTokenValidationParametersAsync会克隆TokenValidationParameters以避免并发请求间的竞态并在使用ConfigurationManager时合并元数据中的ValidIssuers与IssuerSigningKeysL239-L261逐个校验器尝试默认遍历TokenHandlers调用ValidateTokenAsyncUseSecurityTokenValidatorstrue时遍历SecurityTokenValidators先CanReadToken再ValidateToken。任一校验器成功即中断L101-L147校验成功构造ClaimsPrincipal把ValidTo/ValidFrom写入Properties.ExpiresUtc/IssuedUtc触发TokenValidated事件若SaveTokentrue则将令牌以access_token名义存入AuthenticationProperties最后Success()L149-L177校验失败汇总所有校验异常单个或AggregateException触发AuthenticationFailed事件后返回Fail(...)L180-L194密钥轮换自动恢复RecordTokenValidationError在捕获SecurityTokenSignatureKeyNotFoundException且RefreshOnIssuerKeyNotFoundtrue时调用ConfigurationManager.RequestRefresh()刷新元数据L222-L237。HandleChallengeAsyncL275-L346则负责生成 401 响应当IncludeErrorDetails且存在认证失败时会依据异常类型生成符合 RFC 6750 的WWW-Authenticate: Bearer errorinvalid_token, error_description...头。错误描述与异常类型一一对应例如SecurityTokenExpiredException→The token expired at ...SecurityTokenInvalidAudienceException→The audience ... is invalidSecurityTokenInvalidIssuerException→The issuer ... is invalidSecurityTokenSignatureKeyNotFoundException→The signature key was not foundHandleForbiddenAsyncL349-L367在授权失败时返回 403 并触发Forbidden事件。JwtBearerEvents认证事件扩展点JwtBearerEvents.cs 提供 5 个事件委托均默认为空操作覆盖认证全生命周期事件触发时机典型用途OnMessageReceived收到协议消息、提取令牌之前从 Cookie/查询参数等其它位置获取令牌拒绝特定令牌OnTokenValidated令牌通过校验、ClaimsIdentity生成后加载附加声明、写审计日志、二次校验、下发自定义令牌OnChallenge返回 401 质询之前自定义 401 响应体、改写WWW-Authenticate头OnAuthenticationFailed令牌校验失败后记录失败原因、返回自定义错误OnForbidden授权失败返回 403 时自定义 403 响应各事件对应的上下文类型继承自ResultContextJwtBearerOptions可通过设置context.Result干预默认行为。例如MessageReceivedContext.Token属性MessageReceivedContext.cs允许在事件中手动注入令牌TokenValidatedContext.SecurityTokenTokenValidatedContext.cs持有校验后的令牌对象JwtBearerChallengeContextJwtBearerChallengeContext.cs暴露Error/ErrorDescription/ErrorUri/Handled供自定义质询。services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options { options.Events new JwtBearerEvents { OnMessageReceived context { // 从查询字符串读取令牌如 WebSocket / SignalR 场景 var accessToken context.Request.Query[access_token]; if (!string.IsNullOrEmpty(accessToken)) { context.Token accessToken; } return Task.CompletedTask; }, OnTokenValidated context { // 令牌校验成功后写审计日志或补充声明 Console.WriteLine($Token validated for {context.Principal.Identity?.Name}); return Task.CompletedTask; }, OnChallenge context { // 自定义 401 响应内容 context.HandleResponse(); context.Response.StatusCode 401; return context.Response.WriteAsJsonAsync(new { error unauthorized }); } }; });注意当context.HandleResponse()被调用时处理器将跳过默认的 401 写入逻辑见 JwtBearerChallengeContext.cs因此需要自行设置状态码与响应内容。元数据发现与配置后处理JwtBearerPostConfigureOptions.cs 在配置阶段完成默认行为的兜底若TokenValidationParameters.ValidAudience为空且设置了Audience则自动写入L23-L26若未提供ConfigurationManager有静态Configuration则包装为StaticConfigurationManager否则从Authority推导MetadataAddress追加/.well-known/openid-configuration校验 HTTPS 要求创建带默认请求头Microsoft ASP.NET Core JwtBearer handler、10 MB 响应上限与超时设置的HttpClient最后构造ConfigurationManagerL28-L66。这解释了为何只配置Authority就能完成 OIDC 模式的自动发现与签名密钥下载。从源码构建与测试仓库内 README.md 给出了构建与测试指引在src/Security/Authentication目录下执行./build.cmd构建、./build.cmd -t运行测试也可在测试项目目录下用dotnet test运行单个项目的测试。完整的源码构建流程可参考仓库 docs/BuildFromSource.md。结语Microsoft.AspNetCore.Authentication.JwtBearer以轻配置、强校验、可扩展的设计成为 ASP.NET Core 生态中接入 JWT 认证的标准路径本地对称密钥场景只需配置一组TokenValidationParameters生产级 OIDC 场景则通过Authority/Audience实现元数据自动发现与密钥轮换自愈而JwtBearerEvents五个事件钩子让开发者能够在认证链的任何关键节点注入自定义逻辑。理解 JwtBearerHandler 的认证流水线与其选项模型即可在真实项目中游刃有余地定制安全认证方案。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
