API 安全认证机制：OAuth 2.0 与 JWT 实践

API 安全认证机制：OAuth 2.0 与 JWT 实践

API 安全认证是现代 Web 应用和微服务架构的基石。OAuth 2.0 和 JWT（JSON Web Token）是目前最主流的两大认证与授权技术栈，但开发者常常混淆二者各自的职责边界。OAuth 2.0 定义的是授权框架，解决的是"谁可以访问什么资源"的问题；而 JWT 是一种Token 格式，常用于在 OAuth 2.0 流程中传递身份和授权信息。本文将从原理到实战，系统梳理这两项技术的选型与集成方案。

OAuth 2.0 授权框架详解

核心角色与流程

OAuth 2.0 定义了四种核心角色：

四种授权模式对比

推荐方案：2026 年的最佳实践是统一采用 Authorization Code + PKCE（Proof Key for Code Exchange）模式。PKCE 通过在授权请求中附加 code_challenge 参数，防止授权码被拦截后的重放攻击，即使在不使用 Client Secret 的纯前端应用中也足够安全。

Authorization Code + PKCE 完整流程

用户 → 客户端：点击"使用 Google 登录"
客户端 → Google：生成 code_verifier 和 code_challenge，发起授权请求
Google → 浏览器：显示登录页面
用户 → Google：输入凭证
Google → 客户端：回调 URL 返回授权码
客户端 → Google：发送授权码 + code_verifier
Google → 客户端：验证 code_verifier 与 code_challenge 匹配，返回 Access Token + Refresh Token
客户端 → API：在请求头携带 Access Token
API → 客户端：验证 Token 后返回资源

JWT 结构与签名机制

Token 组成

JWT 由三个 Base64URL 编码的部分组成，以点号（.）分隔：

header.payload.signature

Header（头部）：声明 Token 类型和签名算法

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-2026"
}

Payload（载荷）：携带声明（Claims）信息

{
  "sub": "user_12345",
  "iss": "https://auth.16idc.com",
  "aud": ["api-prod", "api-staging"],
  "exp": 1777888800,
  "iat": 1777802400,
  "scope": "read:orders write:orders",
  "roles": ["admin", "operator"]
}

Signature（签名）：防止篡改的核心机制

RSASHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  privateKey
)

签名算法选择

生产建议：使用非对称算法（RS256 或 ES256）。授权服务器持有私钥签名，资源服务器仅需公钥验证。公钥可通过 /.well-known/jwks.json 端点动态获取，支持密钥轮换。

实战代码示例

Spring Boot 资源服务器配置

// build.gradle 依赖
// implementation 'org.springframework.boot:spring-boot-starter-oauth2-resource-server'

@Configuration
@EnableWebSecurity
public class ResourceServerConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
                .requestMatchers("/api/orders/**").hasAuthority("SCOPE_read:orders")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwkSetUri("https://auth.16idc.com/.well-known/jwks.json")
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            );
        return http.build();
    }

    // 自定义角色映射
    private JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
        converter.setAuthorityPrefix("ROLE_");
        converter.setAuthoritiesClaimName("roles");
        JwtAuthenticationConverter jwtConverter = new JwtAuthenticationConverter();
        jwtConverter.setJwtGrantedAuthoritiesConverter(converter);
        return jwtConverter;
    }
}

FastAPI + PyJWT 示例

from fastapi import FastAPI, Depends, HTTPException, Security
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import jwt
from datetime import datetime, timedelta

app = FastAPI()
security = HTTPBearer()

# 配置（生产环境应从环境变量读取）
SECRET_KEY = "your-rs256-private-key"
ALGORITHM = "RS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

def create_access_token(data: dict):
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire, "iat": datetime.utcnow()})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

def verify_token(credentials: HTTPAuthorizationCredentials = Security(security)):
    token = credentials.credentials
    try:
        payload = jwt.decode(
            token, SECRET_KEY, algorithms=[ALGORITHM],
            audience="api-prod"
        )
        return payload
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token 已过期")
    except jwt.InvalidAudienceError:
        raise HTTPException(status_code=401, detail="Token Audience 不匹配")
    except jwt.PyJWTError:
        raise HTTPException(status_code=401, detail="Token 验证失败")

@app.get("/api/orders")
async def get_orders(payload: dict = Depends(verify_token)):
    # 从 payload 中提取用户信息查询订单
    user_id = payload.get("sub")
    # 查询订单逻辑...
    return {"user_id": user_id, "orders": [...]}

常见安全攻击与防范

Refresh Token 与 Token 生命周期管理

生产环境中不能仅依赖单个 Access Token。合理的 Token 生命周期策略可以平衡安全性和用户体验：

Access Token 有效期：15 ~ 30 分钟
Refresh Token 有效期：7 ~ 30 天
Refresh Token 轮换：每次刷新后发放新的 Refresh Token，旧 Refresh Token 立即失效

Token 刷新流程

@app.post("/auth/refresh")
async def refresh_token(refresh_token: str):
    try:
        payload = jwt.decode(
            refresh_token, SECRET_KEY, algorithms=[ALGORITHM],
            options={"verify_exp": True}
        )
        # 检查 Refresh Token 是否已被撤销
        if is_token_revoked(payload["jti"]):
            raise HTTPException(status_code=401, detail="Token 已被撤销")

        # 发放新的 Token
        new_access = create_access_token({"sub": payload["sub"]})
        new_refresh = create_refresh_token({"sub": payload["sub"]})

        # 撤销旧的 Refresh Token
        revoke_token(payload["jti"])

        return {
            "access_token": new_access,
            "refresh_token": new_refresh,
            "token_type": "Bearer",
            "expires_in": 1800
        }
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Refresh Token 已过期，请重新登录")

OAuth 2.1 新变化

2026 年，OAuth 2.1 规范已逐步成为行业推荐标准。相对于 OAuth 2.0，主要变化包括：

总结

OAuth 2.0 + JWT 的组合已成为 API 安全认证的事实标准。在 2026 年的技术栈选型中，推荐以下生产级方案配置：

1. 授权协议：采用 OAuth 2.1 思想，统一使用 Authorization Code + PKCE 模式
2. Token 格式：JWT 配合 RS256 或 ES256 非对称签名算法
3. 密钥管理：通过 JWKS Endpoint 动态管理公钥，支持密钥轮换
4. 生命周期：Access Token 15~30 分钟，Refresh Token 配合轮换机制
5. 安全加固：强制 HTTPS、使用 aud/iss 声明验证、监控异常 Token 使用模式

无论你是构建微服务 API、SPA 前端应用还是移动端 App，以上方案都能为你的 API 提供企业级的安全保障。