使用统一认证登录你的应用 · 接入指引

在自有产品中接入「使用统一认证账号登录」：授权页、换票与获取用户信息的步骤说明（OAuth 2.0 授权码模式）。

文档中心返回首页
打开原始 .md

使用统一认证登录你的应用 · 接入指引

本文适用于将统一认证作为 OAuth 2.0 授权服务器（IdP） 的外部应用。

如果你是要在统一认证站内接入 GitHub/Google 等第三方登录，请改看 社交账号登录与绑定 · 配置说明。

一、接入流程

  1. 在统一认证控制台创建 OAuth 应用，拿到 client_id（机密客户端还需 client_secret）。
  2. 你的前端把用户引导到授权端点 GET /api/oauth/authorize。
  3. 用户登录并授权后，浏览器回跳到你的 redirect_uri，携带 code（和可选 state）。
  4. 你的服务端调用 POST /api/oauth/token 以授权码换取 access_token。
  5. 你的服务端携带 Authorization: Bearer <access_token> 调用 GET /api/auth/me 获取用户信息。

二、创建应用

在 OAuth 应用管理中登记以下信息：

字段说明
回调地址（redirect_uri）必须与授权请求、换票请求中的 redirect_uri 完全一致（协议、域名、路径、端口、尾斜杠都要一致）
Scope 白名单应用允许请求的 scope，默认一般为 openid profile email
客户端类型机密客户端（有 client_secret）或公开客户端（无 client_secret）

三、发起授权请求

GET https://auth.ncvic.com/api/oauth/authorize

常用查询参数：

参数必填说明
client_id是应用标识
redirect_uri是必须在该应用白名单里
response_type是固定 code
scope否默认使用应用允许范围；请求超出白名单会失败
state建议防 CSRF，回调时原样返回
code_challenge否PKCE challenge
code_challenge_method否S256 或 plain

当前实现支持 PKCE 校验：当授权请求携带 code_challenge 时，换票必须提供匹配的 code_verifier。

四、授权成功/取消后的回调

  • 授权成功后回跳：
    • redirect_uri?code=<code>&state=<state>
  • 用户取消授权后回跳：
    • redirect_uri?error=access_denied&state=<state>

其中 state 仅在你发起授权时传入才会回传。

五、换取 access_token

POST https://auth.ncvic.com/api/oauth/token

推荐 application/x-www-form-urlencoded，也支持 JSON。最小字段：

  • grant_type=authorization_code
  • code
  • redirect_uri
  • client_id（可通过 body/query/header/basic 传递）
  • client_secret（机密客户端必填）
  • code_verifier（若本次授权启用 PKCE）

成功返回 OAuth token 扁平结构：

{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 2592000,
  "scope": "openid profile email"
}

六、获取用户信息

GET https://auth.ncvic.com/api/auth/me
Authorization: Bearer <access_token>

成功返回：

{
  "data": {
    "id": "...",
    "email": "...",
    "name": "...",
    "avatar": "..."
  }
}

七、兼容与治理约定

  • 外部契约主文件：/openapi-full.yaml
  • IdP 子集：/openapi-idp-oauth2.yaml
  • 文档入口：/docs/idp-oauth2-integration 与 /docs/idp-oauth2-api
  • 版本策略：仅在主版本升级时引入破坏性变更
  • 错误体统一：{ "error": { "code", "message", "details?" } }