Token 与错误码

返回 README

---

JWT Access Token Claims

Header 携带 typ: at+jwt（RFC 9068 access token 类型标记）；claims：

{
  "sub": "用户UUID",
  "id": 12345,
  "email": "邮箱",
  "name": "用户名",
  "roles": ["admin", "ren"],
  "site_roles": ["moderator"],
  "scope": "openid profile",
  "site_id": 2,
  "client_id": "签发给的 OAuth client",
  "iss": "https://oauth.kungal.com",
  "aud": ["www.moyu.moe"],
  "jti": "随机 token id",
  "exp": 1700000000,
  "iat": 1699999100,
  "nbf": 1699999100
}

• iss 固定为 OP issuer（{issuer}/.well-known/openid-configuration 的 issuer）。
• aud 是资源方标识 = 该 client 绑定站点的域名（RFC 9068 audience 限制）；client 未绑定站点时省略。下游现有的站点校验仍以 site_id 为准，aud 供标准校验器使用。
• scope / site_id / client_id / site_roles 在对应值为空时省略。

签名算法：HS256（现状）。OIDC 切换（KUN_OIDC_SIGN_ASYMMETRIC）后改为 ES256（header 带 kid，公钥见 {issuer}/oauth/jwks）；切换窗口内两种签名都会被各服务接受，下游把 access_token 当不透明字符串用即可，不要对签名算法做硬编码假设。

roles 是角色名的集合,普通用户为空数组 []（user 是隐式默认,不会出现在 claim 里)。角色及其能力语义的权威定义、以及下游必须遵守的规则,见 11-roles.md。 site_roles(可选)是站点域角色——只含用户在本 client 所属站点的未过期授予,与 roles 取并集后喂给你既有的能力判定;权威定义见 12-site-roles.md。

---

错误码速查

所有错误的响应体格式都是：

{ "code": <int>, "message": "<中文消息>" }

code = 0 表示成功；其余按下面分类查阅。

OAuth 错误 (15xxx)

标准 wire 格式下的错误（RFC 6749）

OP 切换 KUN_OIDC_STANDARD_WIRE 后，/oauth/token、/oauth/userinfo、/oauth/revoke 的错误改为标准 OAuth 错误对象 {"error": "...", "error_description": "..."}（不再有 code 字段）。错误字符串与上表错误码的对应：

一方 RP 的宽容读取器必须把 invalid_grant / unauthorized_client / invalid_client 分类为「refresh 已死」（清会话、要求重新登录），未知字符串才当瞬态错误重试 —— 否则死会话会无限重试。

认证错误 (10xxx)

通用错误