应用登录与用户字段映射

把认证中心作为登录提供方时，管理员在「应用接入」、开发者在「我的应用」创建应用，再把配置填入接入方的 OAuth2 / OpenID Connect 设置。最先查看接入方要求的字段格式：字段名、JSONPath 和模板表达式不是同一种语法。

最常用的字段映射

用户信息地址是本站 /oauth/userinfo，请求携带 Authorization: Bearer <access_token>。申请 openid profile email，且在应用允许范围里勾选这三项，重新授权后才能取得以下字段。application_creator 随 openid 始终返回，用于判断当前用户是否为当前应用的创建人。

字段位于 JSON 根对象，没有 data 或 user 包装。若对方要求字段名，填 sub；若要求 JSONPath，填 $.sub。只有对方明确要求其他模板语法时，才使用其模板。

平台内部个人资料的 id、nickname、avatar 不是 OIDC 用户信息字段。当前不返回 picture、avatar、username、preferred_username、手机号或角色。头像映射留空；如接入方要求唯一用户名且允许 UUID，可使用 sub，不要把可重复昵称当作唯一账号。

应用可以在首次登录时把 application_creator=true 的用户设为应用管理员。该声明只回答“此人是否创建了当前 aud 对应的应用”，不会泄露创建人 ID、认证中心管理员身份或其他应用权限。ID Token 中的值必须先通过 JWKS 验签，并校验 iss、aud、exp 和 nonce；不能信任浏览器提交的字段或只解码未验签的 JWT。调用 UserInfo 时必须使用服务端取得的 access token，并核对 sub 与 ID Token 一致。

用户唯一关联应使用发行方 iss 与 sub。邮箱和昵称可以变化；不能仅凭未验证邮箱合并已有账号。

响应示例

以下由接口契约生成，全部为虚构数据，实际字段取决于令牌 scope。

{
  "sub": "00000000-0000-4000-8000-000000000001",
  "name": "示例用户",
  "email": "person@example.test",
  "email_verified": false,
  "application_creator": true
}

email_verified 是布尔值，可能为 false，不是字符串 "true"。没有申请对应 scope 时字段直接省略。管理员修改应用允许范围不会给旧令牌追加权限，需要重新发起授权。

接入配置

生产与非回环地址必须使用 HTTPS；仅 localhost、127.0.0.1、[::1] 允许登记 HTTP 回调。APP_ORIGIN 是统一对外地址，不要混用前端、后端端口或不同域名。

授权流程

1. 每次登录生成随机 state（16–1024 字符）、nonce（16–512 字符）与 code_verifier（43–128 字符）。默认所有客户端都要求 PKCE S256。
2. challenge 为 verifier 的 SHA256 经无填充 Base64URL 编码。浏览器访问授权地址，传 response_type=code、client_id、redirect_uri、scope、state、nonce、code_challenge、code_challenge_method=S256。
3. 用户同意后，验证回调 state、iss；若回调含 error，按错误处理，不继续交换。
4. 60 秒内用 code、同一 redirect_uri 和 verifier POST 表单到 token 地址。机密客户端使用 Basic 或表单 client_secret，公开客户端仅使用 client_id，不能打包 secret。
5. ID Token 是 RS256 JWT，必须用 JWKS 验签并校验 iss、aud、exp、nonce。access_token 是不透明字符串，用它请求 UserInfo；UserInfo 的 sub 必须和验签后的 ID Token sub 一致。
6. 仅 offline_access 返回 refresh_token。刷新需串行执行并原子替换返回值；旧值重放将撤销令牌族。会话撤销或账号停用后令牌也失效。

授权页快捷登录

需要用户交互时，授权页默认显示快捷登录：认证中心小程序二维码位于左侧；浏览器已有有效会话时，右侧同时显示当前账号并可直接继续。浏览器没有有效会话时，快捷登录区只显示二维码。用户也可以切换到账号密码或管理员已启用的 GitHub、微信、QQ、微博等第三方登录，完成后会回到同一条授权请求，不会丢失 state、PKCE、redirect_uri 或待确认的 scope。

二维码是两分钟有效的一次性服务端挑战，不是静态登录链接。它同时绑定原浏览器持有的轮询密钥和完整 OAuth 请求；扫码会先绑定当前小程序会话，必须在手机上核对应用、账号和权限并明确确认，原浏览器才会建立 Web 会话。过期后在电脑端刷新二维码；取消、切换登录方式或成功消费都会使旧挑战失效。prompt=login 要求重新验证，不能由已有会话或扫码快捷登录代替；prompt=none 仍按 OIDC 语义直接返回 login_required 或 consent_required。

ID Token 始终提供 application_creator；profile 只提供 name，email 提供 email/email_verified；没有 picture。完整声明结构、表单参数和错误结构见登录与授权接口参考。

复制调用示例

下面是 POSIX shell 示例，变量由你的服务端安全注入；不要把真实令牌提交或发给 AI。

curl --fail-with-body "$ISSUER/oauth/userinfo" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl --fail-with-body "$ISSUER/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code_verifier=$CODE_VERIFIER"

常见问题

下载 OpenAPI JSON · AI 文档索引 · 软件授权与绑定