79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
|
# iOS 认证流程
|
|||
|
|
|
|||
|
|
> 版本：0.1.0 | 更新：2026-05-24
|
|||
|
|
|
|||
|
|
## 流程图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
iOS App API Server Apple
|
|||
|
|
|
|||
|
|
1. 用户点击"使用 Apple 登录"
|
|||
|
|
Sign in with Apple 弹窗
|
|||
|
|
─────────────────────────────────────────────────────────► 验证用户身份
|
|||
|
|
◄───────────────────────────────────────────────────────── 返回 identityToken
|
|||
|
|
|
|||
|
|
2. POST /api/auth/apple
|
|||
|
|
{ identityToken, fullName?, email? }
|
|||
|
|
──────────────────────────► 验证 identityToken
|
|||
|
|
通过 Apple JWKS 验签
|
|||
|
|
验证 issuer + audience
|
|||
|
|
查找或创建用户
|
|||
|
|
生成 JWT + RefreshToken
|
|||
|
|
◄────────────────────────── { accessToken, refreshToken, user }
|
|||
|
|
|
|||
|
|
3. 存储 Token
|
|||
|
|
Keychain: accessToken + refreshToken
|
|||
|
|
|
|||
|
|
4. 后续请求携带 accessToken
|
|||
|
|
GET /api/users/me
|
|||
|
|
Authorization: Bearer <accessToken>
|
|||
|
|
──────────────────────────► JwtAuthGuard 验证
|
|||
|
|
- 解码 JWT
|
|||
|
|
- 检查 type=user
|
|||
|
|
- 查询用户状态 (active/deleted)
|
|||
|
|
◄────────────────────────── 用户数据
|
|||
|
|
|
|||
|
|
5. Token 过期时刷新 (401)
|
|||
|
|
POST /api/auth/refresh
|
|||
|
|
{ refreshToken }
|
|||
|
|
──────────────────────────► 验证 refresh token hash
|
|||
|
|
检查用户状态
|
|||
|
|
撤销旧 token → 签发新对
|
|||
|
|
◄────────────────────────── { accessToken, refreshToken, user }
|
|||
|
|
|
|||
|
|
6. 登出
|
|||
|
|
POST /api/auth/logout
|
|||
|
|
{ refreshToken }
|
|||
|
|
──────────────────────────► 撤销 refresh token
|
|||
|
|
◄────────────────────────── 200 OK
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Token 存储建议
|
|||
|
|
|
|||
|
|
| Token | 存储位置 | 说明 |
|
|||
|
|
|-------|----------|------|
|
|||
|
|
| accessToken | Keychain / Secure Enclave | 短期（1h），频繁使用 |
|
|||
|
|
| refreshToken | Keychain | 长期（7d），仅在刷新时使用 |
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
| HTTP | message | iOS 处理 |
|
|||
|
|
|------|---------|----------|
|
|||
|
|
| 401 | "请先登录" | 跳转登录页 |
|
|||
|
|
| 401 | "登录已过期，请重新登录" | 尝试刷新 token，失败则跳转登录 |
|
|||
|
|
| 401 | "账号已被禁用" | 显示禁用提示，退出 |
|
|||
|
|
| 401 | "账号不存在或已注销" | 跳转登录页 |
|
|||
|
|
| 401 | "Apple 登录未配置" | 显示维护提示 |
|
|||
|
|
|
|||
|
|
## 自动刷新策略
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
请求 → 401?
|
|||
|
|
├── 是 → 尝试 POST /api/auth/refresh
|
|||
|
|
│ ├── 成功 → 更新 Keychain，重试原请求
|
|||
|
|
│ └── 失败 → 清除 Token，跳转登录
|
|||
|
|
└── 否 → 正常处理
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
建议在 HTTP 拦截器/中间件层实现，避免每个 API 调用都要处理。
|