OIDC 登录:端点与三步流程

授权码模式完整流程:端点清单、跳转授权、回调换令牌、获取用户信息、续期与单点登出。

更新于 2026-10-10

OIDC 登录:端点与三步流程

本文描述接入通行证统一登录的完整流程:端点清单、授权码三步、令牌续期与单点登出。

一、端点清单

标准 OpenID Connect 授权码模式(Confidential Client)。发现文档:

https://account.cheesesynx.cn/.well-known/openid-configuration

推荐直接用标准 OIDC 库自动发现配置;也可以按下表硬编码:

端点 地址
issuer https://account.cheesesynx.cn
authorization_endpoint https://account.cheesesynx.cn/oauth2/authorize
token_endpoint https://account.cheesesynx.cn/oauth2/token
userinfo_endpoint https://account.cheesesynx.cn/oauth2/userinfo
jwks_uri https://account.cheesesynx.cn/oauth2/jwks
end_session_endpoint https://account.cheesesynx.cn/oauth2/logout

能力约束:response_type 仅支持 code;grant 支持 authorization_code / refresh_token; client 认证支持 client_secret_basic 与 client_secret_post;不支持 PKCE;id_token 签名算法 RS256。

二、第一步:跳转授权页

https://account.cheesesynx.cn/oauth2/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=<回调地址,URL 编码>
  &scope="openid profile email realname"
  &state=<随机串>
  &nonce=<可选,防重放>
  • state 用于防 CSRF:建议存 HMAC 签名的随机串(10 分钟有效),回调时校验;
  • 已有通行证登录态的用户免密直接 302 跳回你的回调地址,带 code 与 state;
  • 无登录态会显示通行证登录页(账密 / 短信验证码 / 两步验证 / 第三方登录)。

三、第二步:回调换令牌

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

grant_type=authorization_code
&code=<回调带回来的 code>
&redirect_uri=<回调地址>
&client_id=<client_id>
&client_secret=<client_secret>

响应示例:

{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "<需 offline_access scope>",
  "scope": "openid profile",
  "id_token": "<JWT>"
}

access_token 为 RS256 JWT,2 小时有效;id_token 可用 JWKS 公钥本地验签。

四、第三步:获取用户信息

GET /oauth2/userinfo
Authorization: Bearer <access_token>

按 scope 返回对应字段(字段清单见《scope 与用户字段》)。

账号关联规则:以 sub(通行证 UID,字符串,全局唯一且永不变)作为本平台的 passport_uid; 首次登录创建账号,之后按 UID 匹配,资料以 userinfo 为准。

五、续期与单点登出

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

grant_type=refresh_token
&refresh_token=<refresh_token>
&client_id=<client_id>
&client_secret=<client_secret>

单点登出(跳转即可):

https://account.cheesesynx.cn/oauth2/logout?post_logout_redirect_uri=<登录后返回地址>