OIDC 详细接入 · 星钥认证中心

01

服务发现与端点

推荐只配置 Issuer，由 SDK 自动读取 Discovery。

Issuer URL: https://xsxx.us.to
Discovery: https://xsxx.us.to/.well-known/openid-configuration
Authorization: https://xsxx.us.to/oauth2/authorize
Token: https://xsxx.us.to/oauth2/token
UserInfo: https://xsxx.us.to/oauth2/userinfo
JWKS: https://xsxx.us.to/jwks.json

02

客户端类型

根据应用是否能安全保存 Secret 选择。

Confidential

服务端 Web、后端应用。默认且推荐，Secret 仅保存在服务端。

client_secret_basic（推荐）client_secret_post（兼容）

Public

SPA、桌面端、移动端等无法安全保存 Secret 的应用。

token_endpoint_auth_method=none必须使用 PKCE S256

Client Secret 不得写入浏览器 JavaScript、移动端安装包或公开仓库；泄露后应在客户端详情页立即重置。

03

发起授权请求

浏览器跳转到 Authorization Endpoint。

GET https://xsxx.us.to/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REGISTERED_URI&
  response_type=code&
  scope=openid%20profile%20email&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256&
  state=RANDOM_STATE&
  nonce=RANDOM_NONCE

redirect_uri 必须与客户端后台登记值完全一致，不支持通配符。
scope 必须包含 openid，且不能超出客户端允许范围。
code_verifier 长度为 43–128 个安全随机字符；这里只发送其 S256 challenge。
state 和 nonce 每次请求重新生成，并与当前登录事务绑定。

04

处理授权回调

先校验 state，再处理 code 或 error。

成功：YOUR_CALLBACK?code=AUTHORIZATION_CODE&state=RANDOM_STATE
拒绝：YOUR_CALLBACK?error=access_denied&state=RANDOM_STATE

Authorization Code 有效期短且只能使用一次。不要把 code 当作登录凭据直接交给前端业务。

05

交换 Token

Token Endpoint 仅接受 application/x-www-form-urlencoded。

Confidential：HTTP Basic

POST https://xsxx.us.to/oauth2/token
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REGISTERED_URI&
code_verifier=ORIGINAL_CODE_VERIFIER

Public：不发送 Secret

POST https://xsxx.us.to/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REGISTERED_URI&
code_verifier=ORIGINAL_CODE_VERIFIER

不要同时使用 HTTP Basic 和 Body Client Credentials。当前不返回 refresh_token。

06

UserInfo

使用 Access Token 获取用户信息。

GET https://xsxx.us.to/oauth2/userinfo
Authorization: Bearer ACCESS_TOKEN

返回字段受授权 scope 限制。

07

ID Token 校验

使用 JWKS 验证 ES256 签名。

签名与算法 ES256
iss 等于 Issuer URL
aud 包含 Client ID
exp 尚未过期
nonce 与本次请求一致

08

常见错误

优先检查回调地址、PKCE 和客户端认证方式。

invalid_request: 参数缺失、格式错误、重复使用认证方式或授权会话已失效。
invalid_client: Client ID、Client Secret 或 token_endpoint_auth_method 不正确。
invalid_grant: code 已过期/已使用、redirect_uri 不一致或 code_verifier 不匹配。
access_denied: 用户拒绝授权，应用应给出可重试提示，不要无限自动重试。

09

当前能力边界

接入前确认应用不依赖以下能力。

当前支持：Authorization Code、PKCE S256、openid/profile/email、ES256 ID Token、JWT Access Token、UserInfo。

当前不支持：Refresh Token、Implicit/Hybrid Flow、Client Credentials、Password Grant、Token Introspection 和 Token Revocation Endpoint。

返回快速接入创建客户端