Common AuthCommon AuthAPI 文档
OAuth 2.0 · OIDCOpenAPI v1.0.0

指南

快速开始

授权码 + PKCE 最小接入流程

快速开始

本文介绍第三方应用接入 Common Auth 的最小流程：使用授权码 + PKCE 换取访问令牌，并读取用户信息。

前提

  1. 在控制台注册一个 OAuth 客户端，获得 client_id 与 redirect_uri（非本机须为 https）。
  2. 生成 PKCE 校验码与挑战值（必须使用 S256）。
  3. 授权请求必须携带 state；包含 openid 时还必须携带 nonce。

所有客户端必须使用 PKCE，code_challenge_method 固定为 S256，不接受明文。

生成 PKCE

code_verifier 为 43–128 位的随机字符串，code_challenge 为其 SHA-256 的 Base64URL 编码：

const verifier = crypto.randomBytes(32).toString("base64url");
const challenge = crypto
  .createHash("sha256")
  .update(verifier)
  .digest("base64url");

第一步：跳转授权端点

GET /api/oauth/authorize?response_type=code&client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=openid%20profile%20email
    &state=abc123
    &nonce=n-0S6_WzA2Mj
    &code_challenge=CHALLENGE
    &code_challenge_method=S256

state 必填；请求含 openid 时 nonce 必填。 用户登录并同意后，浏览器会跳转到你的回调地址并携带 code 与 state：

GET /callback?code=AUTH_CODE&state=abc123

第二步：换取令牌

校验 state 与回调地址后，在服务端用授权码交换令牌：

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&client_id=CLIENT_ID
&code_verifier=VERIFIER

成功响应：

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "refresh_token": "RT-...",
  "id_token": "eyJ..."
}

expires_in 为访问令牌有效期（默认 3600 秒）。响应始终包含 refresh_token。请在服务端保存刷新令牌，并在访问令牌过期前调用令牌端点续期；不要把 1 小时的访问令牌当作网站登录时长。续期见 令牌管理。

第三步：读取用户信息

GET /api/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

下一步