549 lines
17 KiB
Markdown
549 lines
17 KiB
Markdown
# Login And Registration Technical Design
|
||
|
||
本文档定义 v1 登录、三方注册登录、密码设置和 token 生命周期。它只描述当前架构事实和接口边界，不记录实现流水账。
|
||
|
||
## Scope
|
||
|
||
v1 只有一个用户创建入口：
|
||
|
||
- 三方身份登录即注册。`provider + provider_subject` 不存在时创建用户、生成 `default_display_user_id`、设置当前 `display_user_id`、绑定三方身份并签发 token。
|
||
|
||
v1 的密码能力只有一个前置条件：
|
||
|
||
- 用户必须已经通过三方登录拿到 access token，之后才能设置密码。
|
||
|
||
v1 不支持：
|
||
|
||
- 账号密码注册。
|
||
- 用户名、邮箱、手机号作为独立登录账号。
|
||
- 未登录状态设置密码。
|
||
- 手机验证码登录。
|
||
- 匿名游客登录。
|
||
- 多账号主动合并。
|
||
- 客户端直接访问 `user-service`。
|
||
- gateway 保存密码、三方凭证或 refresh token。
|
||
|
||
## Ownership
|
||
|
||
登录注册归属 `user-service`，gateway 只做外部 HTTP JSON 入口和 gRPC 协议转换。
|
||
|
||
| Capability | Owner | Rule |
|
||
| --- | --- | --- |
|
||
| HTTP JSON API | `gateway-service` | 只暴露 `/api/v1/auth/*`，统一返回 envelope |
|
||
| 用户创建 | `user-service` | 只能由三方身份首次登录触发 |
|
||
| 展示短号 | `user-service` | 新用户创建时生成默认短号，后续登录用当前有效短号；临时靓号有效期内会覆盖默认短号 |
|
||
| 密码身份 | `user-service` | 已登录用户手动设置后才存在 |
|
||
| 三方身份绑定 | `user-service` | `provider + subject` 唯一绑定用户 |
|
||
| access token 签发 | `user-service` | 登录成功后签发 |
|
||
| access token 校验 | `gateway-service` | 业务 API 和设置密码入口校验 |
|
||
| refresh token | `user-service` | 只保存 hash，支持轮换和失效 |
|
||
| 房间身份态 | `room-service` | 只消费已鉴权 `actor_user_id`，不处理登录 |
|
||
| WebSocket 身份态 | `im-service` | 校验 access token，不处理注册 |
|
||
|
||
`gateway-service` 不读取用户表，不校验密码 hash，不调用三方平台做最终身份判断。
|
||
|
||
## External HTTP API
|
||
|
||
所有接口使用 gateway 业务响应 envelope：
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_xxx",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
`request_id` 来自 `X-Request-ID` 或由 gateway 生成，并透传到内部 gRPC meta。
|
||
|
||
### Third Party Login Or Register
|
||
|
||
```text
|
||
POST /api/v1/auth/third-party/login
|
||
```
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"provider": "wechat",
|
||
"credential": "provider_code_or_token",
|
||
"device_id": "device_xxx"
|
||
}
|
||
```
|
||
|
||
Response `data`:
|
||
|
||
```json
|
||
{
|
||
"user_id": 10001,
|
||
"display_user_id": "100001",
|
||
"default_display_user_id": "100001",
|
||
"display_user_id_kind": "default",
|
||
"display_user_id_expires_at_ms": 0,
|
||
"session_id": "sess_xxx",
|
||
"access_token": "jwt_xxx",
|
||
"refresh_token": "refresh_xxx",
|
||
"expires_in_sec": 1800,
|
||
"token_type": "Bearer",
|
||
"is_new_user": true
|
||
}
|
||
```
|
||
|
||
三方接口不拆注册和登录。新用户不会默认生成密码；只有 `users`、`user_display_user_ids`、`third_party_identities` 和首个 `auth_sessions` 会在同一事务中创建。
|
||
|
||
`display_user_id` 永远表示当前有效展示号。用户没有临时靓号时，它等于 `default_display_user_id`；用户有 active 靓号时，它等于靓号。
|
||
|
||
### Set Password
|
||
|
||
```text
|
||
POST /api/v1/auth/password/set
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"password": "plain_password"
|
||
}
|
||
```
|
||
|
||
Response `data`:
|
||
|
||
```json
|
||
{
|
||
"password_set": true
|
||
}
|
||
```
|
||
|
||
设置密码只接受已登录用户的 access token。客户端不能在 body 中自报 `user_id` 或 `display_user_id`。重复设置密码返回 `PASSWORD_ALREADY_SET`，后续如果要支持改密，必须新增独立改密接口和旧密码校验规则。
|
||
|
||
### Password Login
|
||
|
||
```text
|
||
POST /api/v1/auth/password/login
|
||
```
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"display_user_id": "100001",
|
||
"password": "plain_password",
|
||
"device_id": "device_xxx"
|
||
}
|
||
```
|
||
|
||
Response `data`:
|
||
|
||
```json
|
||
{
|
||
"user_id": 10001,
|
||
"display_user_id": "100001",
|
||
"default_display_user_id": "100001",
|
||
"display_user_id_kind": "default",
|
||
"display_user_id_expires_at_ms": 0,
|
||
"session_id": "sess_xxx",
|
||
"access_token": "jwt_xxx",
|
||
"refresh_token": "refresh_xxx",
|
||
"expires_in_sec": 1800,
|
||
"token_type": "Bearer"
|
||
}
|
||
```
|
||
|
||
短号不存在、用户未设置密码和密码错误都返回 `AUTH_FAILED`。这三个分支不能给客户端更细错误，避免登录入口变成用户枚举接口。
|
||
|
||
密码登录只接受当前有效 `display_user_id`。如果用户申请了临时靓号，默认短号在靓号有效期内不能用于密码登录；靓号过期后，默认短号恢复登录能力。
|
||
|
||
### Refresh Token
|
||
|
||
```text
|
||
POST /api/v1/auth/token/refresh
|
||
```
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"refresh_token": "refresh_xxx",
|
||
"device_id": "device_xxx"
|
||
}
|
||
```
|
||
|
||
Response `data`:
|
||
|
||
```json
|
||
{
|
||
"user_id": 10001,
|
||
"display_user_id": "100001",
|
||
"default_display_user_id": "100001",
|
||
"display_user_id_kind": "default",
|
||
"display_user_id_expires_at_ms": 0,
|
||
"session_id": "sess_xxx",
|
||
"access_token": "jwt_xxx",
|
||
"refresh_token": "refresh_new_xxx",
|
||
"expires_in_sec": 1800,
|
||
"token_type": "Bearer"
|
||
}
|
||
```
|
||
|
||
refresh token 必须轮换。旧 refresh token 使用成功后立即失效。
|
||
|
||
### Logout
|
||
|
||
```text
|
||
POST /api/v1/auth/logout
|
||
```
|
||
|
||
Request:
|
||
|
||
```json
|
||
{
|
||
"refresh_token": "refresh_xxx",
|
||
"session_id": "sess_xxx"
|
||
}
|
||
```
|
||
|
||
Response `data`:
|
||
|
||
```json
|
||
{
|
||
"revoked": true
|
||
}
|
||
```
|
||
|
||
## Internal gRPC Contract
|
||
|
||
`api/proto/user/v1/auth.proto` 承载 auth RPC：
|
||
|
||
```protobuf
|
||
service AuthService {
|
||
rpc LoginPassword(LoginPasswordRequest) returns (AuthResponse);
|
||
rpc LoginThirdParty(LoginThirdPartyRequest) returns (AuthResponse);
|
||
rpc SetPassword(SetPasswordRequest) returns (SetPasswordResponse);
|
||
rpc RefreshToken(RefreshTokenRequest) returns (RefreshTokenResponse);
|
||
rpc Logout(LogoutRequest) returns (LogoutResponse);
|
||
}
|
||
```
|
||
|
||
关键消息：
|
||
|
||
```protobuf
|
||
message LoginPasswordRequest {
|
||
RequestMeta meta = 1;
|
||
string display_user_id = 2;
|
||
string password = 3;
|
||
}
|
||
|
||
message SetPasswordRequest {
|
||
RequestMeta meta = 1;
|
||
int64 user_id = 2;
|
||
string password = 3;
|
||
}
|
||
|
||
message AuthToken {
|
||
int64 user_id = 1;
|
||
string session_id = 2;
|
||
string access_token = 3;
|
||
string refresh_token = 4;
|
||
int64 expires_in_sec = 5;
|
||
string token_type = 6;
|
||
string display_user_id = 7;
|
||
string default_display_user_id = 8;
|
||
string display_user_id_kind = 9;
|
||
int64 display_user_id_expires_at_ms = 10;
|
||
}
|
||
```
|
||
|
||
`SetPasswordRequest.user_id` 必须来自 gateway 已校验 access token 后的上下文，不能来自客户端 JSON body。
|
||
|
||
## Data Model
|
||
|
||
### `users`
|
||
|
||
用户主记录，只保存用户全局身份和状态。
|
||
|
||
| Column | Type | Rule |
|
||
| --- | --- | --- |
|
||
| `user_id` | bigint | primary key |
|
||
| `default_display_user_id` | varchar | user's permanent fallback short id |
|
||
| `current_display_user_id` | varchar | current effective short id; pretty id can cover default id |
|
||
| `current_display_user_id_kind` | varchar | default or pretty |
|
||
| `current_display_user_id_expires_at_ms` | bigint | null for default id |
|
||
| `status` | varchar | active, disabled, banned |
|
||
| `created_at_ms` | bigint | creation time |
|
||
| `updated_at_ms` | bigint | update time |
|
||
|
||
### `password_accounts`
|
||
|
||
密码身份表。它表达“该用户已经设置过密码”，不表达独立账号体系。
|
||
|
||
| Column | Type | Rule |
|
||
| --- | --- | --- |
|
||
| `user_id` | bigint | primary key |
|
||
| `password_hash` | varchar | never store plain password |
|
||
| `hash_alg` | varchar | e.g. bcrypt |
|
||
| `created_at_ms` | bigint | creation time |
|
||
| `updated_at_ms` | bigint | update time |
|
||
|
||
密码登录时先用 `users.current_display_user_id` 解析当前用户，再按 `user_id` 读取 `password_accounts`。这样用户修改默认短号或申请临时靓号后，密码登录自动跟随当前有效短号，不需要同步更新密码表。
|
||
|
||
如果 `current_display_user_id_kind=pretty` 且 `current_display_user_id_expires_at_ms <= now`，登录前必须先触发 user-service 的靓号懒过期流程，把当前短号恢复为默认短号后再继续解析。
|
||
|
||
### `third_party_identities`
|
||
|
||
三方身份绑定表。
|
||
|
||
| Column | Type | Rule |
|
||
| --- | --- | --- |
|
||
| `id` | bigint | primary key |
|
||
| `user_id` | bigint | owner user |
|
||
| `provider` | varchar | provider name |
|
||
| `provider_subject` | varchar | provider user id, required |
|
||
| `provider_union_id` | varchar | optional |
|
||
| `created_at_ms` | bigint | creation time |
|
||
| `updated_at_ms` | bigint | update time |
|
||
|
||
唯一约束：
|
||
|
||
```text
|
||
unique(provider, provider_subject)
|
||
```
|
||
|
||
如果 provider 支持 union id，也不能只依赖 union id。`provider_subject` 是登录身份的稳定主键。
|
||
|
||
### `auth_sessions`
|
||
|
||
refresh token 和会话状态表。
|
||
|
||
| Column | Type | Rule |
|
||
| --- | --- | --- |
|
||
| `session_id` | varchar | primary key |
|
||
| `user_id` | bigint | session owner |
|
||
| `refresh_token_hash` | varchar | unique |
|
||
| `device_id` | varchar | client device |
|
||
| `expires_at_ms` | bigint | refresh expiry |
|
||
| `revoked_at_ms` | bigint | null means active |
|
||
| `created_at_ms` | bigint | creation time |
|
||
| `updated_at_ms` | bigint | update time |
|
||
|
||
refresh token 原文只返回给客户端一次，服务端只保存 hash。
|
||
|
||
### `login_audit`
|
||
|
||
登录审计表，不参与主链路判断。
|
||
|
||
| Column | Type | Rule |
|
||
| --- | --- | --- |
|
||
| `id` | bigint | primary key |
|
||
| `request_id` | varchar | trace id |
|
||
| `user_id` | bigint | nullable on failed login |
|
||
| `login_type` | varchar | password, third_party, refresh, set_password |
|
||
| `provider` | varchar | nullable |
|
||
| `result` | varchar | success, failed |
|
||
| `failure_code` | varchar | nullable |
|
||
| `client_ip` | varchar | gateway observed ip |
|
||
| `user_agent` | varchar | gateway observed ua |
|
||
| `created_at_ms` | bigint | event time |
|
||
|
||
审计失败不能影响登录主链路，但不能记录明文密码、三方 credential 或 refresh token 原文。
|
||
|
||
## Core Flows
|
||
|
||
### Third Party Login Or Register
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
participant P as Provider
|
||
|
||
C->>G: POST /api/v1/auth/third-party/login
|
||
G->>U: LoginThirdParty(provider, credential)
|
||
U->>P: verify credential
|
||
P-->>U: provider_subject
|
||
U->>U: find identity
|
||
alt identity exists
|
||
U->>U: check user status
|
||
U->>U: create session
|
||
else identity missing
|
||
U->>U: create user + default_display_user_id + third_party identity + session
|
||
end
|
||
U-->>G: AuthToken + is_new_user
|
||
G-->>C: envelope(data=AuthToken)
|
||
```
|
||
|
||
三方 credential 校验必须在 `user-service` 内完成。gateway 不保存 provider app secret。
|
||
|
||
### Set Password
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
|
||
C->>G: POST /api/v1/auth/password/set + access token
|
||
G->>G: verify access token
|
||
G->>U: SetPassword(user_id from token, password)
|
||
U->>U: check user status
|
||
U->>U: hash password
|
||
U->>U: insert password_accounts by user_id
|
||
U-->>G: password_set=true
|
||
G-->>C: envelope(data={password_set:true})
|
||
```
|
||
|
||
`password_accounts.user_id` 是主键。重复设置说明用户已经有密码身份，返回 `PASSWORD_ALREADY_SET`。
|
||
|
||
### Password Login
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
|
||
C->>G: POST /api/v1/auth/password/login
|
||
G->>U: LoginPassword(display_user_id, password)
|
||
U->>U: expire pretty display_user_id if needed
|
||
U->>U: resolve current display_user_id
|
||
U->>U: lookup password by user_id
|
||
U->>U: verify password hash
|
||
U->>U: check user status
|
||
U->>U: create session
|
||
U-->>G: AuthToken
|
||
G-->>C: envelope(data=AuthToken)
|
||
```
|
||
|
||
`display_user_id` 是登录名，不是另一个账号体系。默认短号变更后旧短号不能继续登录；临时靓号有效期内默认短号不能登录；临时靓号过期后旧靓号不能继续登录。
|
||
|
||
### Refresh Token
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as Client
|
||
participant G as gateway-service
|
||
participant U as user-service
|
||
|
||
C->>G: POST /api/v1/auth/token/refresh
|
||
G->>U: RefreshToken
|
||
U->>U: hash refresh token
|
||
U->>U: find active session
|
||
U->>U: revoke old refresh token
|
||
U->>U: create replacement refresh token
|
||
U->>U: expire pretty display_user_id if needed
|
||
U->>U: reload user current display_user_id
|
||
U-->>G: new AuthToken
|
||
G-->>C: envelope(data=AuthToken)
|
||
```
|
||
|
||
Refresh 返回当前 `display_user_id`，避免客户端持有旧短号。临时靓号已经过期时，Refresh 必须返回默认短号。
|
||
|
||
## Token Strategy
|
||
|
||
v1 使用：
|
||
|
||
- `access_token`: JWT，短有效期，默认 30 分钟。
|
||
- `refresh_token`: opaque random token，默认 30 天，只保存 hash。
|
||
- `session_id`: 服务端会话 ID，用于 logout、审计和多端管理。
|
||
|
||
JWT claims：
|
||
|
||
```json
|
||
{
|
||
"sub": "10001",
|
||
"user_id": 10001,
|
||
"display_user_id": "100001",
|
||
"default_display_user_id": "100001",
|
||
"display_user_id_kind": "default",
|
||
"display_user_id_expires_at_ms": 0,
|
||
"sid": "sess_xxx",
|
||
"iat": 1777000000,
|
||
"exp": 1777001800,
|
||
"typ": "access"
|
||
}
|
||
```
|
||
|
||
JWT 内的短号字段只是签发时的展示快照，不是身份判断依据。业务鉴权只能用 `user_id`。如果临时靓号在 access token 有效期内过期，客户端需要通过 Refresh 或用户身份接口拿到恢复后的默认短号。
|
||
|
||
首版继续沿用本地 HS256 配置。中长期建议迁移到非对称签名：
|
||
|
||
- `user-service` 持私钥签发。
|
||
- `gateway-service` 和 `im-service` 持公钥校验。
|
||
- 公钥通过配置或 JWKS 缓存分发。
|
||
|
||
## Error Codes
|
||
|
||
gateway HTTP envelope 的 `code` 不使用数字。
|
||
|
||
| Code | HTTP | Meaning |
|
||
| --- | ---: | --- |
|
||
| `OK` | 200 | success |
|
||
| `INVALID_JSON` | 400 | request body is invalid JSON |
|
||
| `INVALID_ARGUMENT` | 400 | field format or required field invalid |
|
||
| `AUTH_FAILED` | 401 | display_user_id missing, password wrong, no password set, or provider rejected |
|
||
| `UNAUTHORIZED` | 401 | missing or invalid access token |
|
||
| `PASSWORD_ALREADY_SET` | 409 | user already has password identity |
|
||
| `USER_DISABLED` | 403 | user is disabled or banned |
|
||
| `SESSION_EXPIRED` | 401 | refresh token expired |
|
||
| `SESSION_REVOKED` | 401 | refresh token revoked |
|
||
| `UPSTREAM_ERROR` | 502 | user-service unavailable or returned unexpected error |
|
||
| `INTERNAL_ERROR` | 500 | gateway internal failure |
|
||
|
||
密码登录时，短号不存在、未设置密码和密码错误都映射为 `AUTH_FAILED`。
|
||
|
||
## Security Rules
|
||
|
||
- 明文密码只允许存在于 gateway 入参对象和 user-service hash 前的内存短路径中，不能写日志。
|
||
- `password_hash` 必须使用强 hash，不能使用 SHA、MD5 或可逆加密。
|
||
- refresh token 原文不能入库，只能入库 hash。
|
||
- 三方 provider secret 只属于 `user-service` 配置。
|
||
- 登录失败日志不能包含明文密码、三方 credential、refresh token 原文。
|
||
- gateway 统一过滤内部错误，客户端只拿稳定错误码和 `request_id`。
|
||
- access token 校验失败不访问 `user-service`，避免每个业务请求都打用户服务。
|
||
- 设置密码必须从 access token 取 `user_id`，不接受客户端 body 指定用户。
|
||
- access token 中的 `display_user_id` 不能作为权限、账务、房间或 IM 身份依据。
|
||
|
||
## Compatibility Rules
|
||
|
||
当前项目仍在架构阶段，没有外部调用方，本次契约直接删除了旧账号注册接口。后续一旦进入联调或灰度，必须恢复兼容演进纪律：
|
||
|
||
- HTTP JSON 字段只能兼容扩展，不能重命名或删除已发布字段。
|
||
- protobuf 字段只能追加，不能复用字段编号。
|
||
- 新增 provider 必须通过配置 allowlist 控制，不能让客户端任意传 provider 后触发未知逻辑。
|
||
- 三方登录创建用户必须使用事务，保证 `users`、`user_display_user_ids` 和 `third_party_identities` 不出现半绑定。
|
||
- 设置密码必须使用 `user_id` 主键幂等判断，不能引入独立账号唯一键。
|
||
- 登录响应可以追加默认短号、当前短号来源和靓号过期时间；已发布后不能改变 `display_user_id` 表示当前有效短号的语义。
|
||
|
||
## Test Matrix
|
||
|
||
必须覆盖：
|
||
|
||
- 三方身份首次登录创建用户、生成 `default_display_user_id`，并返回当前 `display_user_id` 和 `is_new_user=true`。
|
||
- 三方身份再次登录返回同一个 `user_id` 和 `is_new_user=false`。
|
||
- 三方新用户未设置密码前，短号密码登录返回 `AUTH_FAILED`。
|
||
- 已登录用户设置密码成功。
|
||
- 重复设置密码返回 `PASSWORD_ALREADY_SET`。
|
||
- 设置密码后可使用当前 `display_user_id + password` 登录。
|
||
- 短号不存在和密码错误都返回 `AUTH_FAILED`。
|
||
- 用户有 active 靓号时，密码登录必须使用靓号，默认短号返回 `AUTH_FAILED`。
|
||
- 靓号过期后，密码登录必须恢复使用默认短号，旧靓号返回 `AUTH_FAILED`。
|
||
- Refresh 在靓号过期后返回默认短号和 `display_user_id_kind=default`。
|
||
- 被禁用用户密码登录返回 `USER_DISABLED`。
|
||
- refresh token 成功轮换，旧 token 再次使用失败。
|
||
- logout 后 refresh token 失败。
|
||
- gateway auth API 响应始终使用 `{code,message,request_id,data}`。
|
||
- gateway 在 `SetPassword` 中只从 access token 传递 `user_id`。
|
||
|
||
## Open Decisions
|
||
|
||
这些点需要在实现前定死，不能靠代码猜：
|
||
|
||
- 首批三方 provider 名单。
|
||
- 密码复杂度策略。
|
||
- access token 有效期和 refresh token 有效期。
|
||
- HS256 继续使用多久，以及迁移非对称签名的时间点。
|