国内与海外 JWT/JWKS 冻结契约

双轨边界

国内现有链路

登录、刷新、退出和代登录接口保持原契约，不修改 TokenResponse。
签名算法保持 HS256，继续使用 JWT_SECRET。
Access Token 默认有效期保持 24 分钟，Refresh Token 默认有效期保持 7 天。
业务服务继续使用国内 HMAC 验签与 Redis 会话校验，账号停用、退出和 Token 版本失效规则不变。
国内 Token 保持现有 snake_case 声明，不增加海外 aud，也不要求配置 RSA/JWK。

海外尾程链路

海外能力默认关闭：OVERSEAS_JWT_ENABLED=false。
已通过国内 HS256 与 Redis 校验的登录用户调用 POST /api/auth/overseas/token，兑换独立的海外短时 Token。
海外 Token 使用 RS256，默认有效期 15 分钟，不签发 Refresh Token。
尾程必须配置 baiyue.security.jwt-mode=jwks 和 baiyue.security.session-mode=claims，只做 JWKS 验签和本地安全投影校验，不创建或访问国内 Redis 会话校验器。
海外功能未启用时，兑换接口返回“海外认证未启用”；JWKS Controller、海外签发服务和 overseasJwtEncoder 均不创建，Auth 仍可正常启动并签发国内 HS256 Token。

海外签发契约

issuer：auth-service
audience：lastleg-api
算法白名单：仅 RS256
Access Token 默认有效期：15 分钟
兑换接口：POST /api/auth/overseas/token
JWKS 路径：/api/auth/.well-known/jwks.json
Auth 直连地址：http://{auth-host}:9100/api/auth/.well-known/jwks.json
JWKS HTTP 缓存：5 分钟，响应 Cache-Control: public, max-age=300

海外 Token 的 JSON 声明名称和类型固定如下：

声明	JSON 类型	说明
`sub`	string	用户 ID 的字符串形式
`jti`	string	Token 唯一标识
`iat`	number	签发时间
`exp`	number	过期时间
`aud`	string array	固定包含 `lastleg-api`
`userId`	number	认证用户 ID
`tenantId`	number	当前客户 ID；平台账号为平台作用域值
`appCode`	string	`PLATFORM` 或 `MERCHANT`
`roles`	string array	当前角色编码快照
`authorities`	string array	当前权限编码快照
`permissionVersion`	number	IAM 单调权限版本

海外 Token 从 V1 起只使用上述 camelCase 自定义声明，不读取国内 snake_case 声明。

海外配置

baiyue:
  security:
    overseas-jwt:
      enabled: ${OVERSEAS_JWT_ENABLED:false}
      issuer: ${OVERSEAS_JWT_ISSUER:auth-service}
      audience: ${OVERSEAS_JWT_AUDIENCE:lastleg-api}
      rsa-jwk-set: ${OVERSEAS_JWT_RSA_JWK_SET:}
      current-kid: ${OVERSEAS_JWT_CURRENT_KID:}
      access-token-ttl: ${OVERSEAS_ACCESS_TOKEN_TTL:15m}

只有显式启用海外能力时才校验 OVERSEAS_JWT_RSA_JWK_SET 和 OVERSEAS_JWT_CURRENT_KID。启用后配置不合法必须启动失败，避免错误密钥签发。

密钥轮换

JWK Set 只允许 RSA 密钥。
OVERSEAS_JWT_CURRENT_KID 必须指向唯一的当前签名私钥，JWT Header 写入该 kid。
非当前密钥只能保留公钥；JWKS 只发布公钥，不得输出私钥参数。
轮换时同时发布当前公钥和上一公钥，上一公钥至少保留 20 分钟，即 15 分钟最大 Token 生命周期加 5 分钟 JWKS 缓存。
重叠期结束后移除上一公钥，禁止复用历史 kid。

IAM 安全事件

安全事件的 eventType、版本、状态枚举和 payload 以 iam/SECURITY-EVENT-AUDIT.md 为唯一契约。尾程维护用户状态、客户状态和权限版本的本地投影，请求期间不反向同步访问国内 IAM。

3.6 KiB Raw Permalink Blame History Unescape Escape