42 lines
1.5 KiB
Markdown
42 lines
1.5 KiB
Markdown
# 认证与鉴权
|
||
|
||
## 会话认证（默认）
|
||
|
||
1) 登录 `POST /api/auth/login` 成功后返回：
|
||
- `token`：会话 token
|
||
- `expiresAt`
|
||
- `user`
|
||
|
||
2) 客户端后续请求携带：
|
||
- `Authorization: Bearer <session-token>` 或
|
||
- Cookie `xc_session=<session-token>`
|
||
|
||
## 邮件验证
|
||
|
||
- 发送验证码：`POST /api/auth/register/send`
|
||
- 验证并注册：`POST /api/auth/register/verify`
|
||
|
||
当 SMTP 未配置或使用示例域名时，邮箱验证会自动关闭。
|
||
|
||
## MFA（TOTP）
|
||
|
||
- 申请 secret：`POST /api/auth/mfa/totp/provision`
|
||
- 验证并启用：`POST /api/auth/mfa/totp/verify`
|
||
- 关闭 MFA：`POST /api/auth/mfa/disable`
|
||
|
||
登录接口在部分场景会返回 `mfaToken`，用于后续验证。
|
||
|
||
## JWT 令牌服务（可选）
|
||
|
||
启用 `auth.enable: true` 后提供：
|
||
- `POST /api/auth/token/exchange`：使用 OAuth 回调签发的一次性 `exchange_code` 换取真实会话 token
|
||
- `POST /api/auth/token/refresh`：刷新 access token
|
||
|
||
注意事项：
|
||
- `token/exchange` 只接受后端签发的一次性 `exchange_code`，不再接受调用方自报 `user_id/email/roles`
|
||
- `token/exchange` 返回的 `token`/`access_token` 是同一个真实会话 token，供前端 BFF 写入 `xc_session`
|
||
- 当前版本多数保护路由仍使用会话 token，JWT refresh 仅保留给 `token/refresh`
|
||
- 若开启 JWT 中间件，业务逻辑仍可能需要会话 token；因此控制面应优先走会话模型
|
||
|
||
建议：若主要使用会话认证，请将 `auth.enable` 设为 `false`。
|