OAuth 文档

当前能力

• 授权模式固定为 Authorization Code，response_type 只能使用 code。
• PKCE 是必填项，code_challenge_method 当前只支持 S256。
• 令牌交换成功后返回 access_token、id_token、expires_in 和 scope。
• 目前没有 refresh_token；access_token 有效期约 30 天（2592000 秒），过期后需要重新发起授权流程。

核心端点

完整流程

• 先登录 Open CRH Tracker 账号，在用户页的“开发”选项卡里创建一个 OAuth 客户端，登记回调地址并申请需要的 scope。
• 普通用户的 scope 需要等待管理员审核通过后才能授权；客户端创建者可以在自己的 scope 仍处于待审核状态时，先完成登录和授权测试。
• 用户在浏览器里完成登录与授权确认后，应用会在回调地址收到一个一次性 authorization code。
• 应用拿着 code 和当初的 PKCE verifier，调用 /oauth/token 换取 access_token 和 id_token，之后按 Bearer 方式访问 /oauth/userinfo。

创建时要准备的信息

用 v2 接口创建客户端

curl -X POST /api/v2/oauth/clients \
    -H 'Content-Type: application/json' \
    -H 'Cookie: token=<你的网页登录会话>' \
    --data '{
        "name": "My Transit App",
        "description": "Open CRH Tracker OAuth demo",
        "homepageUrl": "https://app.example.com",
        "redirectUris": [
            "https://app.example.com/oauth/callback"
        ],
        "requestedScopes": [
            "api.auth.me.read"
        ]
    }'

授权请求参数

授权 URL 示例

/oauth/authorize
    ?response_type=code
    &client_id=client_123
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
    &scope=api.auth.me.read
    &state=9f4f1c8c4d5a4f43
    &code_challenge=7w7Tt39Qn1m6M5Lx9c1xQ1kBrmR8J4t9wL4mUt5M2pU
    &code_challenge_method=S256
    &nonce=b2d0f7a1c81e41d7

回调处理要点

• 先检查回调里是否带有 error；常见拒绝值为 access_denied。
• 把回调里的 state 和你发起授权前保存的随机值逐字对比；只有完全一致，才能继续处理这次登录结果。
• 确保 token 交换时使用的 redirect_uri 与授权阶段完全一致。
• code 是一次性的，过期或已消费后再次提交会收到 invalid_grant。

成功回调 URL 示例

https://app.example.com/oauth/callback
    ?code=SplxlOBeZQQYbYS6WxSbIA
    &state=9f4f1c8c4d5a4f43

失败回调 URL 示例

https://app.example.com/oauth/callback
    ?error=access_denied
    &state=9f4f1c8c4d5a4f43

POST /oauth/token 请求体

服务端会从请求体读取这些字段。建议使用 application/x-www-form-urlencoded 提交，这是 OAuth 2.0 中 token 交换最常见的提交方式。

cURL 交换令牌示例

curl -X POST /oauth/token \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=authorization_code' \
    --data-urlencode 'client_id=client_123' \
    --data-urlencode 'code=<回调中的 code>' \
    --data-urlencode 'redirect_uri=https://app.example.com/oauth/callback' \
    --data-urlencode 'code_verifier=<浏览器里保存的 code_verifier>'

成功响应示例

{
    "access_token": "ocrh_u_xxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Im9jcmgta2V5LTEifQ...",
    "scope": "api.auth.me.read"
}

请求 userinfo

curl /oauth/userinfo \
    -H 'Authorization: Bearer <access_token>'

userinfo 响应示例

{
    "sub": "dGhpcy1pcy1hLXN0YWJsZS1vaWRjLXN1YmplY3Q"
}

{
    "sub": "dGhpcy1pcy1hLXN0YWJsZS1vaWRjLXN1YmplY3Q",
    "preferred_username": "demo-user"
}

id_token 说明

• id_token 由服务端使用 RS256 签名，包含 iss、sub、aud、azp、exp、iat、auth_time 和 at_hash。
• 如果授权请求里提供了 nonce，服务端会把它写回 id_token；第三方 App 收到后应把它和自己发起请求前保存的值做对比，确认这份身份结果确实属于当前这一次登录。
• preferred_username 只有在 scope 允许读取当前身份信息时才会出现。

当前限制

• 仅支持 Authorization Code，不支持 implicit、device code 或 client credentials。
• 仅支持 PKCE S256，不支持 plain。
• 没有 refresh_token，access_token 约 30 天过期，过期后需要重新授权。
• 请求里的所有 scope 必须全部审核通过，否则授权阶段直接失败。

常见失败原因

• invalid_request：缺失必填字段、response_type 不是 code，或 code_challenge_method 不是 S256。
• access_denied：用户拒绝授权，或者当前登录用户本身没有被请求的 scope。
• invalid_grant：authorization code 已过期、已被消费、redirect_uri 不一致，或 code_verifier 校验失败。
• 回调后直接失败：通常是 state 对比不一致，说明这次回调不是当前这次授权请求的结果，或者浏览器本地保存的值已经丢失。

安全建议

• 始终生成高熵 state 和 code_verifier，并把它们只保存在短期会话存储中。
• 只通过 HTTPS 传输 access_token，避免把令牌写进 URL、日志或前端埋点。
• 公共客户端不要尝试长期缓存 access_token；过期后直接重新走授权码流程。
• 如果你的应用只需要识别登录用户身份，优先申请最小 scope，避免过度请求接口权限。