67 lines
2.0 KiB
Markdown
67 lines
2.0 KiB
Markdown
# 认证 HTTP 约定（Smart Go）
|
||
|
||
与 OAuth2 授权码 + PKCE 对齐，见仓库内 PKCE 校验实现：`internal/auth/oauth2`。
|
||
|
||
## 统一 JSON 信封（`/api/v1/auth/*`）
|
||
|
||
| HTTP | 说明 |
|
||
|------|------|
|
||
| `401` | 认证失败（如用户名或密码错误） |
|
||
| `403` | 已认证但无权限（如用户已禁用） |
|
||
| `200` | 其余：业务成功或 **OAuth 客户端/PKCE 元数据** 类错误（看 `code`） |
|
||
| `5xx` | 服务端异常 |
|
||
|
||
响应体：
|
||
|
||
```json
|
||
{ "code": 200, "msg": "操作成功", "data": { } }
|
||
```
|
||
|
||
- 业务成功时 `code` 为 `200`。
|
||
- 凭据错误以 **HTTP 401** 为准，可不依赖 `body.code` 做分支。
|
||
|
||
## `POST /api/v1/auth/login`
|
||
|
||
在校验 **用户名 + 密码** 通过后，签发与 `GET /oauth/authorize` **同一存储**的 **authorization_code**（绑定 PKCE），并 **Set-Cookie** 会话（便于浏览器再走 `/oauth/authorize`）。
|
||
|
||
### 请求体（JSON）
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `user_name` | 是 | 登录名 |
|
||
| `password` | 是 | 密码 |
|
||
| `tenant_id` | 否 | 缺省为平台租户 |
|
||
| `client_id` | 是 | 已注册的 OAuth 客户端 |
|
||
| `redirect_uri` | 是 | 须在该客户端允许列表内 |
|
||
| `code_challenge` | 是 | PKCE S256 |
|
||
| `code_challenge_method` | 是 | 须为 `S256`（大小写不敏感） |
|
||
| `state` | 否 | 成功时在 `data.state` 回显 |
|
||
| `scope` | 否 | 缺省 `openid` |
|
||
|
||
### 成功 `HTTP 200`
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"authorization_code": "<plain_code>",
|
||
"state": "<若请求携带>"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端用本地保存的 `code_verifier` 请求：
|
||
|
||
`POST /oauth/token`，`grant_type=authorization_code`，参数与标准授权码换 token 一致（`code`、`redirect_uri`、`client_id`、`code_verifier`）。
|
||
|
||
### 失败示例
|
||
|
||
- 用户名或密码错误：**HTTP 401**，`msg` 提示凭据错误。
|
||
- 用户禁用：**HTTP 403**。
|
||
- `client_id` / `redirect_uri` / PKCE 不合法：**HTTP 200**，`code`≠`200`，`msg` 说明原因。
|
||
|
||
## `POST /api/v1/auth/logout`
|
||
|
||
清除会话 Cookie；响应为信封 `code: 200`。
|