跳到正文

Fast.JwtBearer 公开 API ​

目标 net8.0;net9.0;net10.0。从本页目录选择类型,查看其声明和成员。配置、运行示例和边界见模块用法。

参考版本 3.5.51。源码提交 a8bd407bf5f6b811da7fb7bd1db827f4da119a94。

Fast.JwtBearer.AllowForbiddenAttribute ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[SuppressSniffer]
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class AllowForbiddenAttribute : Attribute

跳过 Fast 自身的权限检查,不跳过身份、角色、声明或第三方授权要求。

Fast.JwtBearer.AllowForbiddenAttribute.ToString ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public override string ToString()

说明继承自接口或基类,需结合对应声明阅读。

Microsoft.AspNetCore.Authorization.PermissionAttribute ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[SuppressSniffer]
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
public class PermissionAttribute : Attribute

权限

Microsoft.AspNetCore.Authorization.PermissionAttribute.TagList ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public List<string> TagList { get; set; }

权限标识集合

Microsoft.AspNetCore.Authorization.PermissionAttribute.PermissionAttribute ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public PermissionAttribute()

权限

Microsoft.AspNetCore.Authorization.PermissionAttribute.PermissionAttribute ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public PermissionAttribute(params string[] tagList)

权限

  • 参数 tagList:权限匹配使用的标签集合

Fast.JwtBearer.JwtBearerAlgorithmEnum ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[FastEnum("JwtBearer 加密算法")]
public enum JwtBearerAlgorithmEnum : byte

JwtBearer 加密算法

Fast.JwtBearer.JwtBearerAlgorithmEnum.HS256 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("HS256")]
    HS256 = 0

HS256 默认的

Fast.JwtBearer.JwtBearerAlgorithmEnum.HS384 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("HS384")]
    HS384 = 1

HS384

Fast.JwtBearer.JwtBearerAlgorithmEnum.HS512 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("HS512")]
    HS512 = 2

HS512

Fast.JwtBearer.JwtBearerAlgorithmEnum.PS256 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("PS256")]
    PS256 = 3

PS256

Fast.JwtBearer.JwtBearerAlgorithmEnum.PS384 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("PS384")]
    PS384 = 4

PS384

Fast.JwtBearer.JwtBearerAlgorithmEnum.PS512 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("PS512")]
    PS512 = 5

PS512

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES256 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("ES256")]
    ES256 = 6

ES256

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES256K ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("ES256K")]
    ES256K = 7

ES256K

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES384 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("ES384")]
    ES384 = 8

ES384

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES512 ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("ES512")]
    ES512 = 9

ES512

Fast.JwtBearer.JwtBearerAlgorithmEnum.EdDSA ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[Description("EdDSA")]
    EdDSA = 10

EdDSA

Fast.JwtBearer.IServiceCollectionExtension ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[SuppressSniffer]
public static class IServiceCollectionExtension

为 IServiceCollection 提供 JWT Bearer 配置、认证与授权扩展

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearerSetting ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static IServiceCollection AddJwtBearerSetting(this IServiceCollection services, IConfiguration configuration,
        string section = "JWTSettings")

添加 JwtBearer 设置

说明:适用于只使用工具类

  • 参数 services:要添加服务的服务集合
  • 参数 configuration:用于读取模块设置的配置
  • 参数 section:JSON 配置文件节点的 Key 默认值:JWTSettings
  • 返回:返回 services,便于链式调用

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearerSetting ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static IServiceCollection AddJwtBearerSetting(this IServiceCollection services,
        Action<JWTSettingsOptions> optionAction)

添加 JwtBearer 设置

说明:适用于只使用工具类

  • 参数 services:要添加服务的服务集合
  • 参数 optionAction:JWT 配置操作
  • 返回:返回 services,便于链式调用

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearerAuthentication ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static IServiceCollection AddJwtBearerAuthentication(this IServiceCollection services, IConfiguration configuration,
        string section = "JWTSettings")

添加 JwtBearer 授权

说明:适用于自定义验证

  • 参数 services:要添加服务的服务集合
  • 参数 configuration:用于读取模块设置的配置
  • 参数 section:JSON 配置文件节点的 Key 默认值:JWTSettings
  • 返回:返回 services,便于链式调用

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearerAuthentication ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static IServiceCollection AddJwtBearerAuthentication(this IServiceCollection services,
        Action<JWTSettingsOptions> optionAction)

添加 JwtBearer 授权

说明:适用于自定义验证

  • 参数 services:要添加服务的服务集合
  • 参数 optionAction:JWT 配置操作
  • 返回:返回 services,便于链式调用

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearer ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static IServiceCollection AddJwtBearer(this IServiceCollection services, IConfiguration configuration,
        string section = "JWTSettings")

添加 JwtBearer 服务

  • 参数 services:要添加服务的服务集合
  • 参数 configuration:用于读取模块设置的配置
  • 参数 section:JSON 配置文件节点的 Key 默认值:JWTSettings
  • 返回:返回 services,便于链式调用

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearer ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static IServiceCollection AddJwtBearer(this IServiceCollection services, Action<JWTSettingsOptions> optionAction)

添加 JwtBearer 服务

  • 参数 services:要添加服务的服务集合
  • 参数 optionAction:JWT 配置操作
  • 返回:返回 services,便于链式调用

Fast.JwtBearer.IJwtBearerHandle ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[SuppressSniffer]
public interface IJwtBearerHandle

定义 JWT 身份验证和权限检查的自定义处理契约

Fast.JwtBearer.IJwtBearerHandle.AuthorizeHandle ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
Task<bool> AuthorizeHandle(AuthorizationHandlerContext context, HttpContext httpContext);

执行身份验证后的附加授权检查

说明:调用此方法前,框架已完成令牌验证和自动刷新。返回 false 或抛出异常时 框架先调用 AuthorizationHandlerContext.Fail(),再调用 AuthorizeFailHandle 生成可选的 HTTP 401 响应。取消异常直接传播,不进入失败回调。

  • 参数 context:当前授权处理上下文
  • 参数 httpContext:当前请求上下文
  • 返回:授权通过时返回 true;返回 false 或抛出异常时进入失败处理

Fast.JwtBearer.IJwtBearerHandle.AuthorizeFailHandle ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
Task<object> AuthorizeFailHandle(AuthorizationHandlerContext context, HttpContext httpContext, Exception exception);

创建身份验证失败时的自定义响应数据

说明:授权始终保持失败。HTTP 端点和 MVC 均通过 Challenge 返回 401,非 null 结果作为响应数据; 不依赖 UnifyResult。已建立的 SignalR 连接由框架处理调用拒绝,不再写入 HTTP 响应。

  • 参数 context:当前授权处理上下文
  • 参数 httpContext:当前请求上下文
  • 参数 exception:身份验证检查抛出的异常;没有捕获到异常时为 null
  • 返回:自定义响应数据;使用默认失败处理时返回 null

Fast.JwtBearer.IJwtBearerHandle.PermissionHandle ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
Task<bool> PermissionHandle(AuthorizationHandlerContext context, IAuthorizationRequirement requirement,
        HttpContext httpContext);

判断当前请求是否满足指定授权要求

说明:返回 false 或抛出异常时,框架将调用 PermissionFailHandle,HTTP 返回 403。 取消异常直接传播,不进入失败回调。

  • 参数 context:当前授权处理上下文
  • 参数 requirement:Fast 自身的权限要求;不用于代替角色、声明或第三方策略验证
  • 参数 httpContext:当前请求上下文
  • 返回:权限检查通过时返回 true;返回 false 或抛出异常时进入失败处理

Fast.JwtBearer.IJwtBearerHandle.PermissionFailHandle ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
Task<object> PermissionFailHandle(AuthorizationHandlerContext context, IAuthorizationRequirement requirement,
        HttpContext httpContext, Exception exception);

创建权限检查失败时的自定义响应数据

说明:权限始终保持失败。HTTP 端点和 MVC 均通过 Forbid 返回 403,非 null 结果作为响应数据; 不依赖 UnifyResult。已建立的 SignalR 连接由框架处理调用拒绝,不再写入 HTTP 响应。

  • 参数 context:当前授权处理上下文
  • 参数 requirement:验证失败的授权要求
  • 参数 httpContext:当前请求上下文
  • 参数 exception:权限检查抛出的异常;没有捕获到异常时为 null
  • 返回:自定义响应数据;使用默认失败处理时返回 null

Fast.JwtBearer.JWTSettingsOptions ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[SuppressSniffer]
public sealed class JWTSettingsOptions : IPostConfigure

JWT 配置

Fast.JwtBearer.JWTSettingsOptions.ValidateIssuerSigningKey ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? ValidateIssuerSigningKey { get; set; }

验证签发方密钥

说明:默认 true

Fast.JwtBearer.JWTSettingsOptions.IssuerSigningKey ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public string IssuerSigningKey { get; set; }

签发方密钥

Fast.JwtBearer.JWTSettingsOptions.ValidateIssuer ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? ValidateIssuer { get; set; }

验证签发方

说明:默认 true

Fast.JwtBearer.JWTSettingsOptions.ValidIssuer ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public string ValidIssuer { get; set; }

签发方

Fast.JwtBearer.JWTSettingsOptions.ValidateAudience ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? ValidateAudience { get; set; }

验证签收方

说明:默认 true

Fast.JwtBearer.JWTSettingsOptions.ValidAudience ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public string ValidAudience { get; set; }

签收方

Fast.JwtBearer.JWTSettingsOptions.ValidateLifetime ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? ValidateLifetime { get; set; }

验证生存期

说明:默认 true

Fast.JwtBearer.JWTSettingsOptions.ValidateAccessToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? ValidateAccessToken { get; set; }

验证 AccessToken

说明:默认false需调用 JwtBearerUtil.SetExpiredToken 才会验证

Fast.JwtBearer.JWTSettingsOptions.ClockSkew ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public long? ClockSkew { get; set; }

过期时间容错值,解决服务器端时间不同步问题(秒)

说明:默认 5 秒

Fast.JwtBearer.JWTSettingsOptions.TokenExpiredTime ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public long? TokenExpiredTime { get; set; }

Token 过期时间(分钟)

说明:默认 20 分钟

Fast.JwtBearer.JWTSettingsOptions.RefreshTokenExpireTime ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public long? RefreshTokenExpireTime { get; set; }

刷新 Token 过期时间(分钟)

说明:默认 1440 分钟(24 小时)

Fast.JwtBearer.JWTSettingsOptions.RequireRefreshTokenCache ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? RequireRefreshTokenCache { get; set; }

刷新 Token 时是否强制使用分布式缓存进行重放校验

说明:默认 true;标准注册流程未配置共享缓存时会自动使用进程内缓存如果应用绕过标准注册且没有提供 IDistributedCache,则拒绝刷新以避免 RefreshToken 被重复使用

Fast.JwtBearer.JWTSettingsOptions.Algorithm ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public JwtBearerAlgorithmEnum? Algorithm { get; set; }

加密算法

说明:默认 HS256

Fast.JwtBearer.JWTSettingsOptions.Enable ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public bool? Enable { get; set; }

启用

说明:默认true

Fast.JwtBearer.JWTSettingsOptions.PostConfigure ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public void PostConfigure()

说明继承自接口或基类,需结合对应声明阅读。

Fast.JwtBearer.AppAuthorizeRequirement ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
[SuppressSniffer]
public sealed class AppAuthorizeRequirement : IAuthorizationRequirement

策略对应的需求

Fast.JwtBearer.AppAuthorizeRequirement.AppAuthorizeRequirement ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public AppAuthorizeRequirement(params string[] policies)

初始化类的新实例

  • 参数 policies:授权策略名称集合

Fast.JwtBearer.AppAuthorizeRequirement.Policies ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public string[] Policies { get; private set; }

策略

Fast.JwtBearer.JwtBearerUtil ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static class JwtBearerUtil

JwtBearer 工具类

`Fast.JwtBearer.JwtBearerUtil.DateTypeClaimTypes = ​

[
    JwtRegisteredClaimNames.Iat, JwtRegisteredClaimNames.Nbf, JwtRegisteredClaimNames.Exp
]`

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static readonly string[] DateTypeClaimTypes =
    [
        JwtRegisteredClaimNames.Iat, JwtRegisteredClaimNames.Nbf, JwtRegisteredClaimNames.Exp
    ];

日期类型的 Claim 类型

Fast.JwtBearer.JwtBearerUtil.RefreshTokenClaims = ["f", "e", "s", "l", "k"] ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static readonly string[] RefreshTokenClaims = ["f", "e", "s", "l", "k"];

刷新 Token 身份标识

Fast.JwtBearer.JwtBearerUtil.CreateTokenValidationParameters ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static TokenValidationParameters CreateTokenValidationParameters(JWTSettingsOptions jwtSettings)

生成 Token 验证参数

  • 参数 jwtSettings:JWT 签发与验证配置
  • 返回:生成的 Token 验证参数

Fast.JwtBearer.JwtBearerUtil.GenerateToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static string GenerateToken(IDictionary<string, object> payload, long? expiredTime = null)

生成 Token

  • 参数 payload:要写入令牌的载荷
  • 参数 expiredTime:令牌过期时间
  • 返回:生成的 Token

Fast.JwtBearer.JwtBearerUtil.GenerateRefreshToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static string GenerateRefreshToken(string accessToken)

生成刷新 Token

  • 参数 accessToken:访问令牌
  • 返回:生成的刷新 Token

Fast.JwtBearer.JwtBearerUtil.GetJwtBearerToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static string GetJwtBearerToken(HttpContext httpContext, string headerKey = "Authorization",
        string tokenPrefix = "Bearer ")

获取 JWT Bearer Token

  • 参数 httpContext:当前请求上下文
  • 参数 headerKey:承载令牌的请求头名称
  • 参数 tokenPrefix:请求头中位于令牌之前的前缀
  • 返回:获取到的 JWT Bearer Token

Fast.JwtBearer.JwtBearerUtil.Validate ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static (bool IsValid, JsonWebToken Token, TokenValidationResult validationResult) Validate(string accessToken)

验证 Token

  • 参数 accessToken:访问令牌
  • 返回:验证 Token

Fast.JwtBearer.JwtBearerUtil.ValidateAsync ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static async Task<(bool IsValid, JsonWebToken Token, TokenValidationResult validationResult)> ValidateAsync(
        string accessToken)

异步验证 Token

  • 参数 accessToken:访问令牌
  • 返回:表示异步验证 Token 的任务,任务结果为验证 Token

Fast.JwtBearer.JwtBearerUtil.ValidateJwtBearerToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static bool ValidateJwtBearerToken(DefaultHttpContext httpContext, out JsonWebToken token,
        string headerKey = "Authorization", string tokenPrefix = "Bearer ")

验证 Token

  • 参数 httpContext:当前请求上下文
  • 参数 token:要解析或验证的令牌
  • 参数 headerKey:承载令牌的请求头名称
  • 参数 tokenPrefix:请求头中位于令牌之前的前缀
  • 返回:请求中存在且验证通过的访问令牌返回 true;否则返回 false

Fast.JwtBearer.JwtBearerUtil.ReadJwtToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static JsonWebToken ReadJwtToken(string accessToken)

读取 Token,不含验证

  • 参数 accessToken:访问令牌
  • 返回:读取到的 Token,不含验证

Fast.JwtBearer.JwtBearerUtil.SecurityReadJwtToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static JwtSecurityToken SecurityReadJwtToken(string accessToken)

读取 Token

说明:仅解析令牌,不会验证签名、签发方或有效期;安全决策请使用 Validate

  • 参数 accessToken:访问令牌
  • 返回:读取到的 Token

Fast.JwtBearer.JwtBearerUtil.Exchange ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static string Exchange(HttpContext httpContext, string expiredToken, string refreshToken, long? expiredTime = null,
        long? clockSkew = null)

通过过期 Token 和 刷新 Token 换取新的 Token

  • 参数 httpContext:当前请求上下文
  • 参数 expiredToken:已过期但签名仍需验证的访问令牌
  • 参数 refreshToken:刷新令牌
  • 参数 expiredTime:令牌过期时间
  • 参数 clockSkew:允许同一刷新令牌重复提交的兼容容差(秒);默认 0,禁止重放。
  • 返回:通过过期 Token 和 刷新 Token 换取新的 Token

Fast.JwtBearer.JwtBearerUtil.ExchangeAsync ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static async Task<string> ExchangeAsync(HttpContext httpContext, string expiredToken, string refreshToken,
        long? expiredTime = null, long? clockSkew = null)

异步使用过期 Token 和刷新 Token 换取新的 Token

  • 参数 httpContext:当前请求上下文
  • 参数 expiredToken:已过期但签名仍需验证的访问令牌
  • 参数 refreshToken:刷新令牌
  • 参数 expiredTime:令牌过期时间
  • 参数 clockSkew:允许同一刷新令牌重复提交的兼容容差(秒);默认 0,禁止重放。
  • 返回:表示异步使用过期 Token 和刷新 Token 换取新的 Token 的任务,任务结果为使用过期 Token 和刷新 Token 换取新的 Token

Fast.JwtBearer.JwtBearerUtil.SetExpiredToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static void SetExpiredToken(HttpContext httpContext, string expiredToken)

标记过期 Token

  • 参数 httpContext:当前请求上下文
  • 参数 expiredToken:已过期但签名仍需验证的访问令牌

Fast.JwtBearer.JwtBearerUtil.SetExpiredTokenAsync ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static async Task SetExpiredTokenAsync(HttpContext httpContext, string expiredToken)

异步标记失效 Token

  • 参数 httpContext:当前请求上下文
  • 参数 expiredToken:已过期但签名仍需验证的访问令牌
  • 返回:黑名单写入完成的任务;无有效令牌或无缓存时不写入。

Fast.JwtBearer.JwtBearerUtil.AutoRefreshToken ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static bool AutoRefreshToken(AuthorizationHandlerContext context, HttpContext httpContext, long? expiredTime = null,
        string tokenPrefix = "Bearer ", long? clockSkew = null)

自动刷新 Token 信息

  • 参数 context:当前授权处理上下文
  • 参数 httpContext:当前请求上下文
  • 参数 expiredTime:令牌过期时间
  • 参数 tokenPrefix:请求头中位于令牌之前的前缀
  • 参数 clockSkew:允许同一刷新 Token 重复提交的兼容容差(秒),默认 0(禁止重放)
  • 返回:当前身份有效、允许匿名或刷新成功时返回 true,表示可以继续后续授权;身份校验或刷新失败时返回 false

Fast.JwtBearer.JwtBearerUtil.AutoRefreshTokenAsync ​

源码 · 目标:net8.0、net9.0、net10.0

csharp
public static async Task<bool> AutoRefreshTokenAsync(AuthorizationHandlerContext context, HttpContext httpContext,
        long? expiredTime = null, string tokenPrefix = "Bearer ", long? clockSkew = null)

异步自动刷新 Token 信息

  • 参数 context:当前授权处理上下文
  • 参数 httpContext:当前请求上下文
  • 参数 expiredTime:令牌过期时间
  • 参数 tokenPrefix:请求头中位于令牌之前的前缀
  • 参数 clockSkew:允许同一刷新令牌重复提交的兼容容差(秒);默认 0,禁止重放。
  • 返回:当前身份有效、允许匿名或刷新成功时返回 true,表示可以继续后续授权;身份校验或刷新失败时返回 false