跳到正文

Fast.JwtBearer ​

逐成员 API、参数与返回参考

参考源码版本 3.5.51,目标 net8.0、net9.0、net10.0,依赖 Fast.Runtime 3.5.37;ASP.NET Core JwtBearer 中央依赖版本按上述目标依次为 8.0.33、9.0.22、10.0.14。

从旧版升级且使用平台标志时,见 Runtime H5 迁移说明。本包的版本对齐记录见依赖链变更。

注册与认证链路 ​

AddJwtBearerSetting 仅配置工具;AddJwtBearerAuthentication 保留仅 Bearer 认证的原有合同,不自动加入应用会话验证或 Fast 权限。完整入口 AddJwtBearer 保留原有 Bearer 认证处理器,在授权阶段沿用自动刷新和业务回调。端点授权中间件和 MVC 全局授权过滤器均在最终结果阶段区分拒绝:身份检查失败选择 Challenge,权限不足选择 Forbid。此行为不依赖 UnifyResult,不改造底层 JWT 认证缓存。

csharp
builder.Services.AddScoped<IJwtBearerHandle, ApplicationJwtHandle>();
builder.Services.AddJwtBearer(builder.Configuration);
// 管道顺序:UseRouting → UseAuthentication → UseAuthorization → 端点

ApplicationJwtHandle 由应用实现。签名密钥从应用的安全配置读取。本次无需新增刷新存储服务,不新增刷新接口。

会话与权限 ​

IJwtBearerHandle.AuthorizeHandle 返回 false 或抛出异常时进入 AuthorizeFailHandle,HTTP 返回 401;PermissionHandle 返回 false 或抛出异常时进入 PermissionFailHandle,HTTP 返回 403。失败回调接收原异常。取消异常直接传播,不进入失败回调;失败回调自身的异常也直接传播。JWT 签名有效不能覆盖应用会话失效的结果。

AuthorizeHandle 保留授权阶段的调用位置和原有上下文,端点授权使用 HttpContext,MVC 授权使用 AuthorizationFilterContext;二者同时存在时会分别执行回调。它应只验证已有会话,不创建或恢复会话。保留现有回调接口,不需要新增业务会话模型。

Fast 权限通过只确认自身要求,不替 Roles、Claims 或第三方策略通过。AllowForbidden 只跳过 Fast 权限;AllowAnonymous 保留公开访问语义。SignalR 握手使用 HTTP 认证,已建立连接的 Hub 调用拒绝使用 Hub 协议。

AuthorizeFailHandle、PermissionFailHandle 保留原有失败回调位置,端点和 MVC 均会调用。返回非 null 对象时写为 JSON;返回 null 时使用默认 Challenge/Forbid 响应,安装 UnifyResult 后可由它补充统一正文。自定义正文 code 应分别为 401、403;框架通过 Challenge 保留 Bearer 的 WWW-Authenticate 语义。响应开始后不重复改状态或写正文。

端点授权的刷新与 HTTP 状态 ​

情况HTTP 结果
无有效 JWT,且不能刷新401
JWT 有效或刷新成功,但 AuthorizeHandle 返回 false 或抛出非取消异常401,不交付新 Token 头
刷新成功、会话有效、权限满足继续原请求
会话有效,但 PermissionHandle 返回 false、抛出非取消异常,或其他权限要求不满足403,保留已完成的正常刷新结果

自动刷新仍按原流程设置 access-token 和 x-access-token;若后续身份检查失败,在响应开始前移除这两个头,避免交付无效会话的新凭据,响应使用 no-store/no-cache。统一响应层不再根据新 Token 头把 401 改成 403。客户端仍应成对保存新凭据,包括带正常刷新结果的 403 响应。

保留的工具与配置 ​

GenerateToken、GenerateRefreshToken、Exchange/ExchangeAsync、AutoRefreshToken/AutoRefreshTokenAsync 的公开签名及参数保留,不标记过时。完整注册入口沿用授权阶段的刷新,应用不需要在业务回调里重复刷新。读取 JWT 只解析,不证明真实性。

JWT ClockSkew 默认 5 秒,继续用于生命周期验证。历史工具参数 clockSkew 仍表示刷新凭据重复消费的兼容容差,默认 0,单位秒;不是 JWT 生命周期容差。本次不新增结果复用窗口,不改变两个参数的原有语义。

RequireRefreshTokenCache、ValidateAccessToken、黑名单有效期及现有缓存消费流程保持原合同。标准注册仍提供分布式内存缓存回退;本次没有新增或验证跨实例原子轮换能力,不能将进程锁和普通缓存 Get/Set 视为分布式原子保证。

验证范围 ​

3.5.44 仅更新 ASP.NET Core JwtBearer 依赖补丁版本,身份与权限失败、刷新响应头、端点及 MVC 最终结果处理合同保持不变。本轮已完成 net8.0、net9.0、net10.0 Release 构建及本地 NuGet 包版本、目标产物和依赖核验,未重新执行 HTTP 回归测试。未连接真实数据库或 Redis,未验证 Fast.Admin 实际接入、SignalR 运行时或多实例刷新协调。

2026-11-02 依赖链变更 ​

2026-11-02 依赖链同步:本包从 3.5.50 递增至 3.5.51,依赖更新为 Fast.Runtime 3.5.37。本模块自身实现与公开声明未变。Runtime 新增移动端 H5,并将 Android 及后续位依次后移;数字协议和掩码须迁移,消费端须重新编译并同步前端枚举,见 Runtime H5 迁移说明。

2026-10-24 版本与依赖 ​

2026-10-24 将本包从 3.5.46 递增至 3.5.47,依赖更新至 Fast.Runtime 3.5.34。本模块自身实现和公开声明未改。

使用 AppEnvironmentEnum 的消费端需按 Runtime 鸿蒙迁移说明迁移数值并重新编译。本轮只核对源码与 MSBuild 有效包元数据,按要求不运行测试,也未执行还原、构建、打包或消费端运行验证。

2026-10-30 依赖补丁更新 ​

Fast.JwtBearer 从 3.5.47 递增至 3.5.48。Microsoft.AspNetCore.Authentication.JwtBearer 按 net8.0 / net9.0 / net10.0 分别使用 8.0.33 / 9.0.22 / 10.0.14。Fast.Runtime 3.5.34 保持不变。

本次依赖升级未调整模块实现或公开 API。已重新还原并完成三个目标的 Release 构建和本地打包,核验包身份、依赖分组及 DLL/XML 与构建产物一致,最终构建无警告或错误。本次未执行宿主、HTTP/序列化/ORM 运行时回归、数据库或 Redis 操作,也未重新编译本页的消费端示例。