OAuth 集成文档

本文说明第三方应用如何接入 Brain OAuth 2.0 授权服务器：注册客户端、引导用户授权、用授权码换取访问令牌并调用用户信息接口。

概览

本服务实现标准 OAuth 2.0 授权码模式（RFC 6749），支持机密客户端与公共客户端（须使用 PKCE）。访问令牌由 Brain 签发，本服务作为中间层完成授权、换票与 userinfo 代理。

授权码流程

在开发者控制台创建应用，配置 redirect_uri（须 HTTPS，localhost 除外）。
将用户重定向到 GET /oauth/authorize，携带 client_id、redirect_uri、response_type=code，公共客户端须附带 PKCE 参数。
用户登录并同意后，浏览器携带 ?code=...&state=... 回到 redirect_uri。
服务端用授权码调用 POST /oauth/token，获得 access_token（及可选 refresh_token）。
使用 Bearer access_token 调用 GET /userinfo 获取用户标识与资料。

端点一览

Method	Path	Role	Notes
GET	/oauth/authorize	授权（浏览器）	展示同意页；未登录会跳转登录后再回到本 URL。
POST	/oauth/token	令牌（服务端）	grant_type=authorization_code 或 refresh_token；支持 Basic 或表单客户端认证。
GET	/userinfo	用户信息（服务端）	需要 Authorization: Bearer；返回 sub、email、name 等声明。

授权请求

必填：response_type=code、client_id、redirect_uri（须在应用白名单内）。可选：scope、state；公共客户端必填 code_challenge 与 code_challenge_method=S256。

GET /oauth/authorize?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example%2Fcallback
  &scope=openid%20profile
  &state=RANDOM_STATE
  &code_challenge=CHALLENGE
  &code_challenge_method=S256

令牌交换

授权码换票

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

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

刷新令牌

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

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

// 200 OK { "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "...", "scope": "openid profile" }

PKCE（公共客户端）

授权前生成 code_verifier，将 S256 摘要作为 code_challenge 传给授权端点；换票时在 POST /oauth/token 中提交 code_verifier。机密客户端可省略 PKCE。

用户信息

成功时返回 JSON：sub（用户 ID）、email、name，以及可选 roles。无效或过期令牌返回 401 与 error=invalid_token。

GET /userinfo
Authorization: Bearer ACCESS_TOKEN

错误响应

授权错误通过 redirect_uri 查询参数 error、error_description 返回；令牌与用户信息的错误为 JSON（如 invalid_request、invalid_grant、invalid_client、invalid_token）。