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=<登录后返回地址>