Mini-HBUT OIDC 接入指南

1. 协议入口与 canonical issuer

OIDC 的 issuer 必须按字符串精确比较。中文域名只适合人类展示；协议配置、Discovery、iss 校验和 SDK 配置统一使用下面的 ASCII / Punycode canonical issuer。

https://id.xn--vhq74jc2fzpchter27a.com

首选做法是让 OIDC SDK读取 Discovery，而不是在业务代码里长期硬编码各端点。V1 只开放 Authorization Code； 不提供 implicit/hybrid，也不宣告未实现的 PAR 动态入口。

2. 先在 Developer Portal 注册应用

前往 Mini-HBUT Developer Portal 创建应用。 V1 对外提供两种应用类型：

应用生命周期为 Draft → Pending Review → Approved → Active。只有 Active Client 可以进入授权流程。 Suspended / Revoked Client 会立即失去授权能力；Revoked 为终态。

3. Redirect URI 规则

• 授权请求中的 redirect_uri 必须与已审核注册值精确匹配，不支持通配符、前缀、后缀或正则匹配。
• 禁止 fragment（#...）、userinfo（user@host）和控制字符。
• Web / Confidential 生产地址只能使用 HTTPS；本地开发例外仅用于明确的 localhost 环境。
• Native custom scheme 不能使用 http/https；示例：my-app:/oauth/callback。
• Native loopback 仅允许 http://127.0.0.1 或 http://[::1]，可使用运行时动态端口。
• 不要把授权码、token、handoff secret 或其它凭据放进自己定义的 Redirect URI 静态参数。

4. Web 服务端接入

推荐使用成熟 OIDC SDK。下面以 openid-client 的典型服务端流程表示关键约束；示例中的所有 Client 值均为占位符。

import * as oidc from 'openid-client'

const issuer = new URL(process.env.MINI_HBUT_ISSUER!)
const clientSecret = process.env.MINI_HBUT_CLIENT_SECRET!
const config = await oidc.discovery(
  issuer,
  process.env.MINI_HBUT_CLIENT_ID!,
  {
    client_secret: clientSecret,
    redirect_uris: ['https://your-app.example.com/oauth/callback'],
    token_endpoint_auth_method: 'client_secret_basic',
  },
  oidc.ClientSecretBasic(clientSecret),
)

// 每次登录生成新的 verifier / state / nonce，并绑定到当前服务端会话。
const verifier = oidc.randomPKCECodeVerifier()
const challenge = await oidc.calculatePKCECodeChallenge(verifier)
const state = oidc.randomState()
const nonce = oidc.randomNonce()

const authorizationUrl = oidc.buildAuthorizationUrl(config, {
  redirect_uri: 'https://your-app.example.com/oauth/callback',
  response_type: 'code',
  scope: 'openid profile',
  code_challenge: challenge,
  code_challenge_method: 'S256',
  state,
  nonce,
})

// 回调收到 code 后，在服务端完成授权码交换。
const tokens = await oidc.authorizationCodeGrant(config, currentUrl, {
  pkceCodeVerifier: verifier,
  expectedState: state,
  expectedNonce: nonce,
})

5. Native / 桌面 / 移动端接入

// Native/Public Client：没有 client_secret，仍然使用 Authorization Code + PKCE S256。
// 1. 生成 verifier / challenge / state / nonce
// 2. 使用系统浏览器打开 authorization_endpoint
// 3. 通过已经注册的 custom URI scheme 或 127.0.0.1 loopback 接收 code
// 4. 使用同一个 verifier 调 token_endpoint 兑换 token

GET https://id.xn--vhq74jc2fzpchter27a.com/oauth/authorize
  ?client_id=YOUR_NATIVE_CLIENT_ID
  &redirect_uri=my-app:/oauth/callback
  &response_type=code
  &scope=openid%20profile
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256

• Native App 是 Public Client：二进制中不能安全保存一个所有用户共用的 Client Secret。
• 外部系统浏览器负责展示授权页；不要用内嵌 WebView 收集身份认证凭据。
• 每次请求独立生成 code_verifier、state、nonce。
• 回调后同时校验 state、ID Token nonce、issuer、audience、有效期与签名。
• 自定义 scheme 可能被其它 App 抢占；能使用平台验证过的 App Link / Universal Link 时应优先使用。

6. Scope 与 Claims

sub 是 pairwise subject，不是学号，也不保证跨不同第三方 Client 相同。第三方自己的账号关联应以当前 Client 下稳定的 sub 为主键，不要用姓名、学号快照或昵称代替 OIDC subject。

GET https://id.xn--vhq74jc2fzpchter27a.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

// 申请并获批 student.identity 后，UserInfo 可能包含：
{
  "sub": "PAIRWISE_SUBJECT",
  "name": "显示姓名",
  "preferred_username": "显示姓名",
  "hbut_student_id": "学校身份快照",
  "hbut_student_name": "学校姓名快照",
  "hbut_verification_method": "mini_hbut_app",
  "hbut_verified_at": "2026-08-15T00:00:00.000Z"
}

学校身份类字段只在申请并获批 student.identity 后通过 UserInfo 获取，平台刻意不把这些敏感字段塞进 ID Token， 以减少前端日志、Cookie 或第三方中间件无意长期保存的概率。

7. Mini-HBUT App Approval 实际发生什么

1. 第三方应用把用户重定向到标准 /oauth/authorize。
2. Identity Core 校验 Client、Redirect URI、Scope、PKCE 后创建短期 AuthRequest。
3. 浏览器进入 auth.* 接力页，只展示应用、域名、Scope 并尝试唤起 Mini-HBUT；也可以展示跨设备二维码。
4. Mini-HBUT 从服务端重新读取 AuthRequest，不相信 Deep Link/QR 中携带的应用名称、Scope 或身份字段。
5. 用户在 App 内确认允许/拒绝；App 使用本机设备 Ed25519 私钥对 request/challenge/client/scope/nonce 等上下文签名。
6. Core 验证设备绑定、签名、nonce、时间窗、请求状态与一次性约束后推进授权状态。
7. 浏览器接力页观察到批准后恢复 OIDC Interaction，最终由 OIDC Provider 把一次性 Authorization Code 返回已注册的第三方 callback。

Deep Link / QR 只是“把短期请求带到 App”的唤起通道，本身不是认证凭据；学校密码、学校 Cookie 和 CAS 会话不会发送给第三方应用。

8. Token、刷新与撤销

• Authorization Code 一次性使用；兑换失败或过期后重新发起登录，不重复使用旧 code。
• Access Token / ID Token 都必须按 Discovery/JWKS 验证 issuer、audience、签名与有效期。
• 需要 Refresh Token 时显式申请 offline_access；平台启用 Refresh Token rotation，旧 refresh token 不应重复使用。
• 令牌撤销使用 POST /oauth/revoke；退出 OIDC 会话使用 RP-Initiated Logout 端点。
• Client Secret 泄露后在 Developer Portal 立即轮换；旧 secret 失效后同步吊销相关会话/令牌并检查审计日志。

9. 常见错误

10. 上线前安全检查

11. 规范与更多入口

• OAuth 2.0 Security Best Current Practice (RFC 9700)
• OAuth 2.0 for Native Apps (RFC 8252)
• OpenID Connect Core 1.0
• Developer Portal：创建应用、审核、Redirect URI、Scope 与 Credentials