.NET 10 API 鉴权体系：从原理到实践

一、什么是 API 鉴权

1.1 问题的起点：HTTP 是无状态的

HTTP 协议本身对"请求者是谁"毫无记忆。每一个请求到达服务器时，服务器看到的都是一个陌生的连接。这意味着：

没有鉴权： 任何人 → GET /api/salary/records → 200 OK 有鉴权： 陌生请求 → GET /api/salary/records → 401 Unauthorized 持证请求 → GET /api/salary/records + Token → 200 OK

API 鉴权的本质，是在无状态协议上建立一套可信凭证的颁发与验证机制，回答两个根本问题：

• 你是谁？（Authentication，认证）
• 你能做什么？（Authorization，授权）

这两个问题在 .NET 中由两个独立的中间件（Middleware）处理，顺序固定，协同工作。

1.2 认证与授权的分工

┌─────────────────────────────────────────────────┐ │ 请求处理管道（Pipeline） │ │ │ │ 请求进入 │ │ │ │ │ ▼ │ │ Authentication 中间件 │ │ · 解析 Token / Cookie │ │ · 填充 HttpContext.User（ClaimsPrincipal） │ │ · 回答：你是谁 │ │ │ │ │ ▼ │ │ Authorization 中间件 │ │ · 检查端点是否需要授权 │ │ · 验证 Role / Policy / Claims │ │ · 回答：你能做什么 │ │ │ │ │ ▼ │ │ Controller / Minimal API Handler │ └─────────────────────────────────────────────────┘

两个中间件的顺序不能颠倒。认证在先，授权在后——只有先知道你是谁，才能判断你能做什么。

1.3 核心数据结构：ClaimsPrincipal 与 Claim

认证成功后，用户身份被表达为一个ClaimsPrincipal对象，挂载在HttpContext.User上。它包含一组Claim（声明）——本质是键值对：

// Claim 示例newClaim(ClaimTypes.NameIdentifier,"user-123")// 用户 IDnewClaim(ClaimTypes.Role,"admin")// 角色newClaim("department","engineering")// 自定义属性newClaim("exp","1716000000")// 过期时间

整个鉴权体系都围绕 Claims 运转：Token 里打包 Claims，服务器解析 Claims，授权策略检查 Claims。

二、常见凭证方案对比

在现代 API 开发中，JWT Bearer是最主流的选择，原因在于其无状态特性天然适合分布式系统——服务器不需要集中存储 Session，每个节点独立验证 Token 即可。

三、JWT 验签原理

理解 JWT 验签，是理解整个鉴权体系的基础。

3.1 JWT 的物理结构

JWT 是由.分隔的三段 Base64URL 编码字符串：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 . eyJzdWIiOiJ1c2VyLTEyMyIsInJvbGUiOiJhZG1pbiIsImV4cCI6MTcxNjAwMDAwMH0 . SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ────────────────── ────────────────────────────────────── ──────────────────────── Header Payload Signature

解码后：

// Header：描述算法{"alg":"HS256","typ":"JWT"}// Payload：实际 Claims 数据{"sub":"user-123","role":"admin","exp":1716000000}// Signature：二进制数据，是 Header+Payload 的数字指纹

Payload 明文可读，绝不能存放密码等敏感信息。Base64 编码不是加密。

3.2 签名生成（颁发时）

签名公式： Signature = HMAC_SHA256( Base64URL(Header) + "." + Base64URL(Payload), SecretKey ) 最终 Token： Base64URL(Header) + "." + Base64URL(Payload) + "." + Base64URL(Signature)

Signature 是 Header 与 Payload 合并内容的"数字指纹"，且只有持有 SecretKey 的人才能生成。

3.3 验签过程（每次请求时）

验签不是解密，而是重新计算后比对：

收到 Token：A . B . C └── 客户端携带的签名 服务器： Step 1：C' = HMAC_SHA256(A + "." + B, SecretKey) // 用同一 Key 重新计算 Step 2：C' == C → 签名一致，Token 未被篡改，可信 C' != C → 签名不一致，Token 已被篡改，拒绝

3.4 为什么篡改一定会被发现

攻击者想把 role 从 user 改成 admin： 原始 Token： Header . Payload{"role":"user"} . Signature_原始 篡改 Token： Header . Payload{"role":"admin"} . Signature_原始 ← Signature 没变 服务器验证： C' = HMAC_SHA256(Header + "." + Payload_篡改, SecretKey) C' ≠ Signature_原始 ← Payload 变了，指纹必然不同 要伪造签名必须知道 SecretKey → SecretKey 从未在网络传输 → 无法伪造

3.5 两种签名算法

HS256（对称）：签名与验证用同一个密钥。

颁发服务器 资源服务器（API） SecretKey ──────────── SecretKey （签名） （验证）

缺点：所有服务都必须持有 SecretKey，任一节点泄漏即全线失守。

RS256（非对称）：私钥签名，公钥验证，推荐用于生产环境。

授权服务器 资源服务器（API） PrivateKey（签名） PublicKey（验证） 只有我有 可以公开分发 通过 /.well-known/jwks.json 获取

数学保证：用私钥加密的数据只有对应公钥能解开，API 节点即使被攻破，攻击者拿到公钥也无法伪造 Token。

3.6 验签之外：完整校验链

验签只证明"Token 未被篡改"，完整验证还需要：

① 验签名 → Token 是否由可信方颁发、内容是否完整 ② 验 exp → Token 是否已过期（防重放过期 Token） ③ 验 iss → 是否来自我信任的授权服务器（防其他系统的 Token） ④ 验 aud → Token 是否颁发给我这个 API（防 Token 跨服务复用） ⑤ 提取 Claims → 填充 HttpContext.User，供后续授权使用

其中aud（受众，Audience）校验尤为重要：

系统中存在 Service-A 和 Service-B 攻击者合法登录 Service-A，获得 access_token（aud = service-a） Service-B 不校验 aud → 攻击者用 service-a 的 Token 访问 B → 成功入侵 Service-B 校验 aud → aud != service-b → 直接拒绝

四、鉴权决策机制：如何判断是否需要登录

4.1 三层决策模型

┌──────────────────────────────┐ 请求进入 │ Authorization 中间件 │ ──────────────────▶ │ │ │ Layer 1：端点是否受保护？ │ │ 无 [Authorize] → 直接放行 │ │ 有 [AllowAnonymous] → 放行 │ │ 有 [Authorize] → 继续 ↓ │ │ │ │ Layer 2：身份是否已认证？ │ │ IsAuthenticated = false │ │ → 401 Unauthorized │ ← "请先登录" │ IsAuthenticated = true → ↓ │ │ │ │ Layer 3：是否满足权限要求？ │ │ Policy/Role 不满足 │ │ → 403 Forbidden │ ← "无权访问" │ 满足 → 放行 │ └──────────────────────────────┘

4.2 401 与 403 的精确语义

4.3 Authentication 中间件的执行时机

一个常见误解：Authentication 中间件只在受保护接口上运行。实际上：

Authentication 中间件对【所有请求】都执行，总是尝试解析 Token。 公开接口（无 [Authorize]）： 携带有效 Token → User.IsAuthenticated = true（但不做检查） 未携带 Token → User.IsAuthenticated = false（但不做检查） → Authorization 中间件判断端点未受保护，直接放行 受保护接口（有 [Authorize]）： 携带有效 Token → 放行 未携带 Token → 401

五、.NET 10 中的完整实现

5.1 Token 颁发（登录接口）

app.MapPost("/api/auth/login",async(LoginRequestreq,UserServiceuserService)=>{// 1. 验证身份凭据varuser=awaituserService.VerifyAsync(req.Username,req.Password);if(userisnull)returnResults.Unauthorized();// 2. 构造 Claimsvarclaims=new[]{newClaim(ClaimTypes.NameIdentifier,user.Id.ToString()),newClaim(ClaimTypes.Name,user.Username),newClaim(ClaimTypes.Role,user.Role),newClaim("department",user.Department)};// 3. 签名并生成 Tokenvarkey=newSymmetricSecurityKey(Encoding.UTF8.GetBytes(config["Jwt:Secret"]!));vartoken=newJwtSecurityToken(issuer:config["Jwt:Issuer"],audience:config["Jwt:Audience"],claims:claims,expires:DateTime.UtcNow.AddHours(1),signingCredentials:newSigningCredentials(key,SecurityAlgorithms.HmacSha256));returnResults.Ok(new{access_token=newJwtSecurityTokenHandler().WriteToken(token),expires_in=3600});});

5.2 注册认证与授权服务

// Program.csbuilder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(options=>{options.TokenValidationParameters=newTokenValidationParameters{ValidateIssuerSigningKey=true,IssuerSigningKey=newSymmetricSecurityKey(Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Secret"]!)),ValidateIssuer=true,ValidIssuer=builder.Configuration["Jwt:Issuer"],ValidateAudience=true,ValidAudience=builder.Configuration["Jwt:Audience"],ValidateLifetime=true,ClockSkew=TimeSpan.Zero// 不允许时间偏差容忍};});builder.Services.AddAuthorization(options=>{// 基于策略（Policy-based）授权options.AddPolicy("SeniorEngineer",policy=>policy.RequireAuthenticatedUser().RequireClaim("department","engineering").RequireRole("senior"));});// 中间件顺序固定，不能交换app.UseAuthentication();app.UseAuthorization();

5.3 保护接口

// 需要登录app.MapGet("/api/profile",(HttpContextctx)=>{varuserId=ctx.User.FindFirst(ClaimTypes.NameIdentifier)?.Value;returnResults.Ok(new{userId});}).RequireAuthorization();// 需要特定角色app.MapDelete("/api/users/{id}",(intid)=>Results.NoContent()).RequireAuthorization(p=>p.RequireRole("admin"));// 需要满足自定义策略app.MapGet("/api/engineering/report",()=>Results.Ok()).RequireAuthorization("SeniorEngineer");// 公开接口，显式声明app.MapGet("/api/health",()=>Results.Ok("healthy")).AllowAnonymous();

六、OAuth 2.0 / OIDC 规范：access_token 与 id_token

在接入第三方身份提供者（IdP，Identity Provider）的场景中，需要理解 OAuth 2.0 与 OIDC 的规范分工。

6.1 两个规范的关系

┌─────────────────────────────────────────────────┐ │ OpenID Connect（OIDC） │ │ 解决：你是谁（Identity / Authentication） │ │ ┌─────────────────────────────────────────────┐│ │ │ OAuth 2.0 ││ │ │ 解决：你能访问什么（Authorization） ││ │ │ 颁发：access_token ││ │ └─────────────────────────────────────────────┘│ │ 新增：id_token（必须是 JWT 格式） │ └─────────────────────────────────────────────────┘

• OAuth 2.0（RFC 6749）：授权框架，规定如何颁发 access_token，但不规定其格式（对客户端透明）
• OIDC：在 OAuth 2.0 之上的身份层，新增 id_token，规定格式必须为 JWT

6.2 access_token：规范定义与使用约束

RFC 6749 的核心定义：access_token 代表一份"授权许可"，客户端持它访问受保护资源，其内容对客户端不透明（Opaque）。

access_token 回答的问题： "这个客户端被授权访问哪些资源、执行哪些操作（scope）？" access_token 的受众（aud）： 资源服务器（Resource Server），即你的 API 典型 JWT 载荷： { "iss": "https://auth-server.com", "sub": "user-123", "aud": "https://your-api.com", // 目标是 API "exp": 1716000000, "scope": "read:data write:data", // 被授权的操作范围 "client_id": "my-client-app" }

规范约束：

• 客户端拿到后不应解析其内容（格式是实现细节）
• 只应发送给aud指定的资源服务器
• 有效期应短（通常 15 分钟 ~ 1 小时）

6.3 id_token：规范定义与使用约束

OIDC Core 1.0 的核心定义：id_token 包含关于用户认证的断言（Assertion），由授权服务器颁发给客户端，必须是 JWT 格式。

id_token 回答的问题： "用户是谁？什么时候登录的？用哪种方式认证的？" id_token 的受众（aud）： 客户端 App，不是 API 标准 Claims： { "iss": "https://auth-server.com", "sub": "user-123", "aud": "my-client-app-id", // 目标是客户端 "exp": 1716000000, "auth_time": 1715996000, // 用户实际认证的时间 "nonce": "abc123", // 防重放攻击 "name": "张三", "email": "zhang@example.com" }

规范明确禁止（OIDC Core 1.0 Section 2）：

• 将 id_token 发送给资源服务器（API）
• 用 id_token 访问 API

6.4 两者的核心区别

6.5 Authorization Code + PKCE（Proof Key for Code Exchange）完整流程

PKCE 是当前最安全的授权模式，防止授权码拦截攻击，适用于 SPA（Single Page Application）和移动端。

用户浏览器 客户端 App 授权服务器 资源服务器（API） │ │ │ │ │ 点击登录 │ │ │ │─────────────────▶│ │ │ │ │ ① 生成 code_verifier + code_challenge │ │ │ 重定向至授权端点 │ │◀─────────────────│──────────────────▶│ │ │ │ │ │ │ ② 用户在授权服务器完成登录（输入账号密码） │ │─────────────────────────────────────▶│ │ │ │ │ │ │ ③ 授权服务器重定向回 App，携带短期 code │ │◀────────────────────────────────────▶│ │ │─────────────────▶│ │ │ │ │ ④ 用 code + code_verifier 换 Token │ │ │ POST /token │ │ │──────────────────▶│ │ │ │ │ │ │ │ ⑤ 返回： │ │ │ │ access_token │ │ │ │ id_token ◀─────│ │ │ │ refresh_token │ │ │ │ │ │ │ │ ⑥ 客户端验证并解析 id_token（本地使用） │ │ │ 展示用户名、头像 │ │ │ │ │ │ │ ⑦ 携带 access_token 调用 API │ │ │ Authorization: Bearer <access_token> │ │ │──────────────────────────────────────────▶ │ │ │ ⑧ 验证 access_token │ │ │ │ 检查签名、aud、scope │ │ │◀────────────────────────────────────────── │ │ │ ⑨ 返回业务数据 │

6.6 Token 刷新机制

access_token（短期，1小时）过期 │ ▼ POST /token grant_type=refresh_token refresh_token=<长期 Token> │ ▼ 授权服务器返回新 access_token 旧 refresh_token 立即作废（Refresh Token Rotation） │ ▼ 客户端用新 access_token 继续请求

七、鉴权体系的安全边界

JWT 验签保证了 Token 未被篡改，但不能覆盖所有威胁：

生产环境最佳实践清单：

• 使用 RS256（非对称）替代 HS256（对称），API 节点只持有公钥
• access_token 有效期不超过 1 小时，通过 refresh_token 静默续期
• 强制 HTTPS，禁止 Token 出现在 URL 中
• aud和iss校验必须开启，ClockSkew设为TimeSpan.Zero
• 主动注销场景使用 Redis 维护jti黑名单
• 敏感端点配合内置 Rate Limiting（.NET 10）防暴力破解

八、总结

┌─────────────────────────────────────────────────────────┐ │ .NET 10 API 鉴权全景 │ │ │ │ 颁发层 │ │ 登录接口 → 验证密码 → 打包 Claims → 签名 → JWT │ │ │ │ 验证层（每次请求） │ │ 提取 Token → 验签名 → 验 iss/aud/exp → 填充 User │ │ │ │ 授权层 │ │ 端点有 [Authorize]? → IsAuthenticated? → Policy满足? │ │ → 放行 / 401 / 403 │ │ │ │ 企业级扩展（OAuth 2.0 + OIDC） │ │ 授权服务器颁发 access_token（访问 API） │ │ 颁发 id_token（客户端读取用户信息） │ │ refresh_token 静默续期 │ └─────────────────────────────────────────────────────────┘

鉴权不是单点技术，而是一条完整的信任链：从用户提交凭据，到 Token 被颁发、传递、验证、使用，每个环节的设计都影响整体安全性。理解每个环节背后的原理，才能在面对非标准场景时做出正确的架构决策。