Fast.JwtBearer 公开 API

目标 net8.0;net9.0;net10.0。本页为语法声明与 XML 注释参考，运行示例和边界见模块用法。

源码提交：43554c07f6c216f80b509bd535c0a5b66ae7f2e8。维护流程：scripts/export-dotnet-api.ps1；普通站点构建直接消费此文件。

Fast.JwtBearer.AllowForbiddenAttribute

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

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

允许无权限访问(403)

Fast.JwtBearer.AllowForbiddenAttribute.ToString

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

public override string ToString()

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

Microsoft.AspNetCore.Authorization.PermissionAttribute

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

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

权限

Microsoft.AspNetCore.Authorization.PermissionAttribute.TagList

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

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

权限标识集合

Microsoft.AspNetCore.Authorization.PermissionAttribute.PermissionAttribute

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

public PermissionAttribute()

权限

Microsoft.AspNetCore.Authorization.PermissionAttribute.PermissionAttribute

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

public PermissionAttribute(params string[] tagList)

权限

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

Fast.JwtBearer.JwtBearerAlgorithmEnum

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

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

JwtBearer 加密算法

Fast.JwtBearer.JwtBearerAlgorithmEnum.HS256

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

[Description("HS256")]
    HS256 = 0

HS256 默认的

Fast.JwtBearer.JwtBearerAlgorithmEnum.HS384

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

[Description("HS384")]
    HS384 = 1

HS384

Fast.JwtBearer.JwtBearerAlgorithmEnum.HS512

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

[Description("HS512")]
    HS512 = 2

HS512

Fast.JwtBearer.JwtBearerAlgorithmEnum.PS256

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

[Description("PS256")]
    PS256 = 3

PS256

Fast.JwtBearer.JwtBearerAlgorithmEnum.PS384

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

[Description("PS384")]
    PS384 = 4

PS384

Fast.JwtBearer.JwtBearerAlgorithmEnum.PS512

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

[Description("PS512")]
    PS512 = 5

PS512

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES256

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

[Description("ES256")]
    ES256 = 6

ES256

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES256K

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

[Description("ES256K")]
    ES256K = 7

ES256K

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES384

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

[Description("ES384")]
    ES384 = 8

ES384

Fast.JwtBearer.JwtBearerAlgorithmEnum.ES512

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

[Description("ES512")]
    ES512 = 9

ES512

Fast.JwtBearer.JwtBearerAlgorithmEnum.EdDSA

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

[Description("EdDSA")]
    EdDSA = 10

EdDSA

Fast.JwtBearer.IServiceCollectionExtension

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

[SuppressSniffer]
public static class IServiceCollectionExtension

为 IServiceCollection 提供动态 API 扩展方法

Fast.JwtBearer.IServiceCollectionExtension.AddJwtBearerSetting

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

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

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

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

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

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

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

添加 JwtBearer 服务

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

Fast.JwtBearer.IJwtBearerHandle

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

[SuppressSniffer]
public interface IJwtBearerHandle

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

Fast.JwtBearer.IJwtBearerHandle.AuthorizeHandle

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

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

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

说明：调用此方法前，框架已完成令牌验证和自动刷新。返回 false 或抛出异常时 框架将调用 AuthorizeFailHandle；该方法未提供响应时调用 AuthorizationHandlerContext.Fail()

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

Fast.JwtBearer.IJwtBearerHandle.AuthorizeFailHandle

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

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

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

说明：返回非 null 数据时，框架以 HTTP 401 状态码写入该数据；返回 null 时调用 AuthorizationHandlerContext.Fail()

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

Fast.JwtBearer.IJwtBearerHandle.PermissionHandle

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

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

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

说明：返回 false 或抛出异常时，框架将调用 PermissionFailHandle

• 参数 context：当前授权处理上下文
• 参数 requirement：当前待验证的授权要求
• 参数 httpContext：当前请求上下文
• 返回：权限检查通过时返回 true；返回 false 或抛出异常时进入失败处理

Fast.JwtBearer.IJwtBearerHandle.PermissionFailHandle

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

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

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

说明：返回非 null 数据时，框架以 HTTP 403 状态码写入该数据；返回 null 时调用 AuthorizationHandlerContext.Fail()

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

Fast.JwtBearer.JWTSettingsOptions

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

[SuppressSniffer]
public sealed class JWTSettingsOptions : IPostConfigure

JWT 配置

Fast.JwtBearer.JWTSettingsOptions.ValidateIssuerSigningKey

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

public bool? ValidateIssuerSigningKey { get; set; }

验证签发方密钥

说明：默认 true

Fast.JwtBearer.JWTSettingsOptions.IssuerSigningKey

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

public string IssuerSigningKey { get; set; }

签发方密钥

Fast.JwtBearer.JWTSettingsOptions.ValidateIssuer

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

public bool? ValidateIssuer { get; set; }

验证签发方

说明：默认 true

Fast.JwtBearer.JWTSettingsOptions.ValidIssuer

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

public string ValidIssuer { get; set; }

签发方

Fast.JwtBearer.JWTSettingsOptions.ValidateAudience

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

public bool? ValidateAudience { get; set; }

验证签收方

说明：默认 true

Fast.JwtBearer.JWTSettingsOptions.ValidAudience

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

public string ValidAudience { get; set; }

签收方

Fast.JwtBearer.JWTSettingsOptions.ValidateLifetime

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

public bool? ValidateLifetime { get; set; }

验证生存期

说明：默认 true

Fast.JwtBearer.JWTSettingsOptions.ValidateAccessToken

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

public bool? ValidateAccessToken { get; set; }

验证 AccessToken

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

Fast.JwtBearer.JWTSettingsOptions.ClockSkew

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

public long? ClockSkew { get; set; }

过期时间容错值，解决服务器端时间不同步问题（秒）

说明：默认 5 秒

Fast.JwtBearer.JWTSettingsOptions.TokenExpiredTime

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

public long? TokenExpiredTime { get; set; }

Token 过期时间（分钟）

说明：默认 20 分钟

Fast.JwtBearer.JWTSettingsOptions.RefreshTokenExpireTime

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

public long? RefreshTokenExpireTime { get; set; }

刷新 Token 过期时间（分钟）

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

Fast.JwtBearer.JWTSettingsOptions.RequireRefreshTokenCache

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

public bool? RequireRefreshTokenCache { get; set; }

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

说明：默认 true；标准注册流程未配置共享缓存时会自动使用进程内缓存如果应用绕过标准注册且没有提供 IDistributedCache，则拒绝刷新以避免 RefreshToken 被重复使用多实例部署应使用 Redis 等共享缓存，而不是进程内缓存

Fast.JwtBearer.JWTSettingsOptions.Algorithm

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

public JwtBearerAlgorithmEnum? Algorithm { get; set; }

加密算法

说明：默认 HS256

Fast.JwtBearer.JWTSettingsOptions.Enable

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

public bool? Enable { get; set; }

启用

说明：默认true

Fast.JwtBearer.JWTSettingsOptions.PostConfigure

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

public void PostConfigure()

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

Fast.JwtBearer.AppAuthorizeRequirement

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

[SuppressSniffer]
public sealed class AppAuthorizeRequirement : IAuthorizationRequirement

策略对应的需求

Fast.JwtBearer.AppAuthorizeRequirement.AppAuthorizeRequirement

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

public AppAuthorizeRequirement(params string[] policies)

初始化类的新实例

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

Fast.JwtBearer.AppAuthorizeRequirement.Policies

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

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

策略

Fast.JwtBearer.JwtBearerUtil

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

public static class JwtBearerUtil

JwtBearer 工具类

`Fast.JwtBearer.JwtBearerUtil.DateTypeClaimTypes =

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

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

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

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

刷新 Token 身份标识

Fast.JwtBearer.JwtBearerUtil.CreateTokenValidationParameters

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

public static TokenValidationParameters CreateTokenValidationParameters(JWTSettingsOptions jwtSettings)

生成 Token 验证参数

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

Fast.JwtBearer.JwtBearerUtil.GenerateToken

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

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

public static string GenerateRefreshToken(string accessToken)

生成刷新 Token

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

Fast.JwtBearer.JwtBearerUtil.GetJwtBearerToken

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

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

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

验证 Token

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

Fast.JwtBearer.JwtBearerUtil.ValidateAsync

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

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

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

public static JsonWebToken ReadJwtToken(string accessToken)

读取 Token，不含验证

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

Fast.JwtBearer.JwtBearerUtil.SecurityReadJwtToken

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

public static JwtSecurityToken SecurityReadJwtToken(string accessToken)

读取 Token

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

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

Fast.JwtBearer.JwtBearerUtil.Exchange

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

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

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

• 参数 httpContext：当前请求上下文
• 参数 expiredToken：已过期但签名仍需验证的访问令牌
• 参数 refreshToken：刷新令牌
• 参数 expiredTime：令牌过期时间
• 参数 clockSkew：令牌验证允许的时钟偏差
• 返回：通过过期 Token 和 刷新 Token 换取新的 Token

Fast.JwtBearer.JwtBearerUtil.ExchangeAsync

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

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：令牌验证允许的时钟偏差
• 返回：表示异步使用过期 Token 和刷新 Token 换取新的 Token 的任务，任务结果为使用过期 Token 和刷新 Token 换取新的 Token

Fast.JwtBearer.JwtBearerUtil.SetExpiredToken

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

public static void SetExpiredToken(HttpContext httpContext, string expiredToken)

标记过期 Token

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

Fast.JwtBearer.JwtBearerUtil.SetExpiredTokenAsync

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

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

异步标记失效 Token

• 参数 httpContext：当前请求上下文
• 参数 expiredToken：已过期但签名仍需验证的访问令牌
• 返回：表示异步“异步标记失效 Token”操作的任务

Fast.JwtBearer.JwtBearerUtil.AutoRefreshToken

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

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

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：令牌验证允许的时钟偏差
• 返回：成功签发并写入新令牌时返回 true；无需刷新或刷新失败时返回 false