集成文档

密码登录

支持邮箱或用户名 + 密码登录。密码使用 Argon2id 算法哈希存储，连续 5 次失败将锁定账号 15 分钟。勾选“记住我”可保持登录 90 天。

Passkey（无密码登录）

基于 WebAuthn 标准，支持指纹、面部识别、安全密钥等生物识别方式。用户可在安全设置中注册多个 Passkey，登录时无需输入密码。

SSO 第三方登录

管理员可在后台配置多种 SSO 提供商（GitHub、Google、微信、钉钉、飞书等），配置后登录页面会自动显示对应的登录按钮。支持的协议包括 OpenID Connect、OAuth 2.0、SAML 2.0 和 CAS。

二次验证 (2FA)

支持 TOTP（基于时间的一次性密码）二次验证，兼容 Google Authenticator、Microsoft Authenticator 等应用。启用后登录时需额外输入 6 位验证码，同时提供备用恢复码。

注册应用

在 OAuth 应用 页面注册您的应用，获取 Client ID 和 Client Secret。注册时需配置回调地址（Redirect URI）和权限范围（Scopes）。

授权码流程

完整的 OAuth2 授权码流程分为四步：

第一步：引导用户到授权页面

http://localhost:3002/oidc/auth?client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&response_type=code
&scope=openid profile email
&code_challenge=BASE64URL_SHA256(code_verifier)
&code_challenge_method=S256
&state=RANDOM_STRING

第二步：用户授权后回调

用户点击“允许”后，浏览器重定向到您的 redirect_uri：

https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STRING

第三步：用授权码换取 Access Token

curl -X POST http://localhost:3002/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=ORIGINAL_CODE_VERIFIER" \
  -d "client_secret=YOUR_CLIENT_SECRET"

成功响应：

{
  "access_token": "xxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xxx",
  "scope": "openid profile email"
}

第四步：获取用户信息

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  http://localhost:3002/oidc/me

• sub — 用户唯一 ID（openid 必含）
• name、picture — 昵称和头像（profile）
• email、email_verified — 邮箱和验证状态（email）

PKCE 支持

新建 OAuth 应用默认启用 PKCE（Proof Key for Code Exchange）。客户端需在授权请求中携带 code_challenge（S256 方法）和 code_challenge_method=S256，换取令牌时提交原始 code_verifier。对于不安全的客户端（如 SPA、移动应用），PKCE 是必需的。

权限范围 (Scopes)

应用注册时可设置“必需权限”（始终请求）和“可选权限”（用户可勾选）。

令牌管理

刷新 Token

curl -X POST http://localhost:3002/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

SP 配置

在您的 SP 中需要配置以下信息：

• IdP Metadata URL：http://localhost:3002/saml/metadata
• Entity ID：http://localhost:3002/saml/metadata
• ACS URL：您的 SP 接收 SAML Response 的地址
• Audience：您的 SP 的 Entity ID

SSO 流程

# 1. SP 引导用户到 IdP 登录
GET http://localhost:3002/saml/sso?SAMLRequest=BASE64_DEFLATED_AUTHNREQUEST

# 2. 用户在本平台完成登录
# 3. IdP 通过 POST 绑定返回 SAML Response 到 SP 的 ACS
POST https://your-app.com/saml/acs
  SAMLResponse=BASE64_SIGNED_RESPONSE
  RelayState=OPTIONAL_STATE

断言属性

• uid — 用户唯一 ID
• email — 用户邮箱
• displayName — 用户昵称

NameID 格式：urn:oasis:names:tc:SAML:2.0:nameid-format:persistent，值为用户 UUID。

单点登出 (SLO)

GET http://localhost:3002/saml/slo

服务端点

验证流程

# 1. 引导用户到 CAS 登录页
GET http://localhost:3002/cas/login?service=https://your-app.com/callback

# 2. 用户登录后，CAS 生成 Service Ticket 并重定向
GET https://your-app.com/callback?ticket=ST-xxxxxxxxxxxxxxxx

# 3. 后端验证 ticket
GET http://localhost:3002/cas/serviceValidate?service=https://your-app.com/callback&ticket=ST-xxxxxxxxxxxxxxxx

响应示例

<cas:serviceResponse xmlns:cas="http://www.yale.edu/tp/cas">
  <cas:authenticationSuccess>
    <cas:user>username</cas:user>
    <cas:attributes>
      <cas:uid>user-uuid</cas:uid>
      <cas:email>user@example.com</cas:email>
      <cas:displayName>用户昵称</cas:displayName>
    </cas:attributes>
  </cas:authenticationSuccess>
</cas:serviceResponse>

参数说明

• service — 客户端回调地址
• gateway=true — 网关模式，未登录直接回跳
• renew=true — 强制重新认证

支持的协议

管理员配置

管理员可在 管理面板 → SSO / OAuth 页面添加和配置 SSO 提供商。每个提供商可独立控制：

• 启用/禁用 — 控制该提供商是否生效
• 允许登录 — 是否在登录页显示
• 允许注册 — 是否允许通过 SSO 创建新账号
• 允许绑定 — 已登录用户是否可以关联该 SSO 账号

SSO 回调地址格式：http://localhost:3002/api/v1/sso/{providerId}/callback

提供商配置使用 AES-256-GCM 加密存储，敏感信息（如 Client Secret、证书私钥）不会以明文形式保存。

认证方式

API 支持两种认证方式：

• Session Cookie — 浏览器登录后自动携带，httpOnly Cookie
• API Token — 在 API 令牌 页面创建，格式为 ltree_xxx，通过 Authorization: Bearer ltree_xxx 传递

常用端点

{
  "displayName": "新昵称",
  "bio": "个人简介"
}

{
  "currentPassword": "旧密码",
  "newPassword": "新密码"
}

响应格式

{
  "success": true,
  "data": { ... },
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述"
  }
}

success 为 false 时 data 字段不存在。