Bearer Token验证失败时常见错误信息
收到
401 Unauthorized却没报具体原因，大概率是
TokenValidationParameters配置不匹配。典型表现包括：
SecurityTokenExpiredException（时间偏移未处理）、
SecurityTokenInvalidSignatureException（密钥类型或长度不对）、
SecurityTokenInvalidIssuerException（
ValidIssuer多了个斜杠或大小写不一致）。JWT 本身是 Base64Url 编码，但 .NET 的
JsonWebTokenHandler不会自动补全填充字符，若 token 来自某些前端库（如 axios + auth0-spa-js），末尾缺少
=会导致解析直接抛
ArgumentException。
手动验证 JWT 的最小可行代码（.NET 6+）
不用依赖
AddJwtBearer中间件，纯代码校验只需三步：加载 token、构造参数、调用验证。关键点在于密钥必须与签发方完全一致——RSA 公钥要从
RSAParameters正确导入，HMAC 则要求字节数组长度 ≥ 256 bit（即
new byte[32]起步）。
var handler = new JsonWebTokenHandler();
var validationParams = new TokenValidationParameters
{
ValidateAudience = true,
ValidAudience = "https://api.example.com",
ValidateIssuer = true,
ValidIssuer = "https://auth.example.com",
ValidateLifetime = true,
ClockSkew = TimeSpan.FromMinutes(5), // 必须设，避免服务器时间微差导致误判
ValidateIssuerSigningKey = true,
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("your-32-byte-secret-key-here"))
};
try
{
var result = handler.ValidateToken(tokenString, validationParams);
if (result.IsValid)
{
var claims = result.Claims;
// 可取 user_id、scope 等做后续授权判断
}
}
catch (SecurityTokenException ex)
{
// 不要直接返回 ex.Message 给前端，仅记录日志
}
ValidateToken 和 ValidateTokenAsync 的区别
ValidateToken是同步方法，适用于大多数 Web API 场景；
ValidateTokenAsync仅在需要异步加载密钥（比如从 Azure Key Vault 动态拉取 RSA 公钥）时才用。注意：即使用了
ValidateTokenAsync，.NET 默认仍走同步路径，除非你重写
ISecurityTokenValidator并显式 await 密钥获取逻辑。多数项目里硬编码密钥或从配置读取，根本不需要异步版本。 同步验证快，无额外线程开销，推荐默认使用
ValidateToken异步验证需自己管理密钥生命周期，且
ValidateTokenAsync在 .NET 7+ 才真正支持完整异步链路 别被名字误导——
ValidateTokenAsync不等于“更安全”或“更标准”
自定义验证逻辑绕过标准流程的场景
当你要检查
scope是否包含特定权限、或验证
client_id是否在白名单、或结合数据库查用户状态是否被禁用时，不能只靠
TokenValidationParameters。此时应在
ValidateToken成功后立刻对
result.Claims做二次判断： 用
result.Claims.FirstOrDefault(c => c.Type == "scope")?.Value提取 scope 字符串，再
.Split(' ') 检查权限项
避免直接用 result.Claims["user_id"]，应始终用
FirstOrDefault防止 key 不存在时抛
KeyNotFoundException数据库查询必须加缓存（如
MemoryCache），否则每次请求都查库，token 验证就变成性能瓶颈
JWT 本身不可撤销，所谓“手动验证”只是确认签名和时效有效；真正的业务级权限控制，永远在验证通过之后那几行代码里——那里才是容易被忽略、却最常出问题的地方。
