OAuth 对外授权 · 接入指引
新手引导与接入文档，帮助开发者快速接入 OAuth2.0 授权码流程
概述
本服务支持作为 OAuth2.0 身份提供者（IdP），对外提供授权码（Authorization Code）流程。第三方应用可引导用户到本平台完成登录与授权，并使用返回的授权码换取 access_token，从而安全地访问用户身份信息（如 /api/auth/me）。
适用场景： 你的网站/应用需要「使用本平台账号登录」、获取用户昵称/邮箱等基础信息，或在此基础上扩展单点登录（SSO）、开放平台等能力。
快速开始（三步）
- 注册 OAuth 应用：登录控制台 →「OAuth 应用管理」→ 新建应用，填写应用名称与回调地址（redirect_uri）。
- 引导用户授权：在你的站点构造授权链接，让用户点击后跳转到本服务的授权端点；用户登录并同意后，将带着授权码（code）重定向回你的回调地址。
- 用授权码换 Token：在你的后端用 code、client_id、client_secret、redirect_uri 请求 Token 端点，获得 access_token；之后即可携带该 token 调用用户信息等接口。
下方将按步骤详细说明参数、示例与注意事项。
第一步：注册 OAuth 应用
使用本平台账号登录后，进入 控制台 → OAuth 应用管理，点击「新建应用」。
- 应用名称：便于你识别的名称，如「我的网站」。
- 回调地址（redirect_uri）：用户授权完成后跳转的 URL，必须与你在代码里使用的地址完全一致（含协议、域名、路径、端口）。可配置多个，每行一个或逗号分隔。
- Scope：默认
openid profile email，表示可请求用户身份、昵称、邮箱等。 - 公开客户端：若为纯前端 SPA、无法安全保管 client_secret，可勾选「公开客户端」；否则请妥善保管创建后仅显示一次的 Client Secret。
创建成功后，你将获得 Client ID（必用）和 Client Secret（机密客户端必用，仅展示一次，请立即保存）。
第二步：引导用户授权
在你的网站放置「使用 XXX 登录」等按钮，点击后跳转到本服务的授权端点。若用户未登录，会先进入登录页，登录后再完成授权并重定向回你的 redirect_uri。
授权端点
GET https://auth.ncvic.com/api/oauth/authorize
必填与常用参数
| 参数 | 必填 | 说明 |
|---|---|---|
| client_id | 是 | 应用 Client ID |
| redirect_uri | 是 | 授权后跳转地址，须与注册时完全一致 |
| response_type | 是 | 固定为 code |
| scope | 否 | 权限范围，默认 openid profile email |
| state | 建议 | 防 CSRF，回调时原样带回，请校验 |
| code_challenge | 否 | PKCE 用，可选；当前服务端仅存储，换 Token 时暂不校验 code_verifier |
| code_challenge_method | 否 | PKCE 用，如 S256 |
若参数错误、客户端无效或 redirect_uri 不在白名单，将重定向到本站错误页（/auth/error），展示友好提示，而非返回 JSON。
示例：构造授权链接
const authUrl = new URL('https://auth.ncvic.com/api/oauth/authorize');
authUrl.searchParams.set('client_id', '你的_client_id');
authUrl.searchParams.set('redirect_uri', 'https://你的站点.com/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('state', randomState); // 建议生成随机字符串并存入 session
window.location.href = authUrl.toString();用户同意后，将重定向到：redirect_uri?code=授权码&state=你传入的state
授权码一次性有效，约 10 分钟内使用，且只能使用一次。
第三步：用授权码换取 access_token
在你的后端服务从回调 URL 中取出 code 和 state，校验 state 后，用 code 向 Token 端点发起 POST 请求（不要在前端暴露 client_secret）。
Token 端点
POST https://auth.ncvic.com/api/oauth/token
Content-Type: application/x-www-form-urlencoded
请求体参数
| 参数 | 必填 | 说明 |
|---|---|---|
| grant_type | 是 | 固定为 authorization_code |
| code | 是 | 回调中的授权码 |
| client_id | 是 | 应用 Client ID |
| client_secret | 机密客户端必填 | 应用 Client Secret（公开客户端不传） |
| redirect_uri | 是 | 须与授权请求时使用的 redirect_uri 一致 |
示例：curl 换取 Token
curl -X POST 'https://auth.ncvic.com/api/oauth/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code' \ -d 'code=回调中的授权码' \ -d 'client_id=你的_client_id' \ -d 'client_secret=你的_client_secret' \ -d 'redirect_uri=https://你的站点.com/callback'
成功响应示例
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 2592000,
"scope": "openid profile email"
}expires_in 单位为秒，具体值由服务端配置（SESSION_MAX_AGE）决定。
之后在请求用户信息等接口时，在 Header 中携带：Authorization: Bearer <access_token>
例如获取当前用户信息：GET https://auth.ncvic.com/api/auth/me。
Scope 说明
本服务默认支持以下 scope（可空格分隔组合）：
openid：用户唯一标识（sub）profile：昵称、头像等资料email：邮箱地址
创建应用时可配置该应用允许的 scope；授权与换 Token 时请求的 scope 不应超出应用配置范围。
注意事项
- redirect_uri：授权请求与 Token 请求中的 redirect_uri 必须与注册应用时填写的某一项完全一致（包括协议、域名、路径、端口、大小写）。
- 授权码一次性：每个 code 只能使用一次，且有效期为约 10 分钟，请及时换取 token。
- client_secret 保密：仅在后端使用，不要写入前端代码或公开仓库。若泄露，请在应用管理中重置（若支持）或禁用该应用。
- state 防 CSRF：建议生成随机 state 并存入 session/cookie，回调时校验与发起时一致。
- 应用状态：若应用被禁用，授权与换 Token 将失败，请在控制台确认应用为「启用」状态。
常见问题
- Q：回调时报 redirect_uri 不在白名单？
- A：会跳转到本站错误页并提示「该应用的回调地址未通过安全校验」。请确认授权链接与 Token 请求中的 redirect_uri 与在「OAuth 应用管理」中配置的回调地址完全一致（含 https/http、末尾斜杠等）。
- Q：换 Token 时提示授权码无效或已使用？
- A：授权码只能使用一次，且约 10 分钟有效。请确认未重复使用、未超时，且换 Token 时的 redirect_uri 与授权时一致。
- Q：纯前端 SPA 如何安全接入？
- A：创建应用时勾选「公开客户端」，不传 client_secret。换 Token 必须通过你的后端代理请求（不可在前端暴露 client_secret）。授权时可传 code_challenge/code_challenge_method，当前服务端仅做存储，换 Token 时暂不校验 code_verifier，后续版本将支持完整 PKCE。
- Q：如何管理已授权用户？
- A：在「OAuth 应用管理」中进入对应应用，点击「已授权账户」可查看曾授权的用户列表，并支持撤销单个或全部授权。