huachuang/OAuth2-Token接口使用文档.md

# OAuth2 Token 接口使用文档

## 接口地址

```
POST http://{域名}/system/oauth2/token
Content-Type: application/x-www-form-urlencoded
```

## 通用规则

- 所有请求**必须**携带 HTTP Basic Auth 请求头：`Authorization: Basic base64(client_id:secret)`
- 响应格式：`{"code":0,"msg":"...","data":{...}}`
- `code=0` 表示成功
- 默认客户端：`client_id=default`、`secret=admin123`

---

## 支持的授权模式

### 1. 客户端模式 `client_credentials`（外部系统调用推荐）

**适用场景**：机器对机器调用，无需用户登录。

```bash
curl -X POST "http://localhost:48080/system/oauth2/token" \
  -u "default:admin123" \
  -d "grant_type=client_credentials"
```

参数：

| 参数 | 必填 | 说明 |
|------|------|------|
| `grant_type` | 是 | 固定值 `client_credentials` |
| `scope` | 否 | 授权范围，多个用空格分隔，如 `read write` |

成功响应：

```json
{
  "code": 0,
  "data": {
    "access_token": "a1b2c3d4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "refresh_token": "r1r2r3r4-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "expires_in": 7200,
    "token_type": "bearer",
    "scope": "read write",
    "user_id": 0
  }
}
```

---

### 2. 密码模式 `password`

**适用场景**：用户直接用账号密码换取 token（如移动端 App 登录）。

```bash
curl -X POST "http://localhost:48080/system/oauth2/token" \
  -u "default:admin123" \
  -d "grant_type=password" \
  -d "username=admin" \
  -d "password=admin123"
```

参数：

| 参数 | 必填 | 说明 |
|------|------|------|
| `grant_type` | 是 | 固定值 `password` |
| `username` | 是 | 用户账号 |
| `password` | 是 | 用户密码 |
| `scope` | 否 | 授权范围，多个用空格分隔 |

---

### 3. 授权码模式 `authorization_code`

**适用场景**：第三方应用需要用户授权后才能访问用户数据（如 SSO 单点登录）。

分两步走：

**第一步**：用户浏览器访问授权页，拿到 `code`

```bash
浏览器访问：
http://localhost:48080/system/oauth2/authorize?clientId=default
```

用户确认授权后，回调地址会带上 `code` 参数。

**第二步**：用 `code` 换 token

```bash
curl -X POST "http://localhost:48080/system/oauth2/token" \
  -u "default:admin123" \
  -d "grant_type=authorization_code" \
  -d "code=xxxx" \
  -d "redirect_uri=https://回调地址" \
  -d "state=1"
```

参数：

| 参数 | 必填 | 说明 |
|------|------|------|
| `grant_type` | 是 | 固定值 `authorization_code` |
| `code` | 是 | 第一步获取的授权码 |
| `redirect_uri` | 是 | 必须与第一步的回调地址一致 |
| `state` | 否 | 透传的状态值，用于防 CSRF |

---

### 4. 刷新令牌 `refresh_token`

**适用场景**：token 快过期时，用 `refresh_token` 换新 token，无需重新登录。

```bash
curl -X POST "http://localhost:48080/system/oauth2/token" \
  -u "default:admin123" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=r1r2r3r4-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

参数：

| 参数 | 必填 | 说明 |
|------|------|------|
| `grant_type` | 是 | 固定值 `refresh_token` |
| `refresh_token` | 是 | 之前获取的 refresh_token |

---

## 其他接口

### 校验 Token

```bash
curl -X POST "http://localhost:48080/system/oauth2/check-token" \
  -u "default:admin123" \
  -d "token=要校验的access_token"
```

### 撤销 Token（登出）

```bash
curl -X DELETE "http://localhost:48080/system/oauth2/token?token=要撤销的access_token" \
  -u "default:admin123"
```

---

## 四种模式对比

| 模式 | grant_type 值 | 是否需用户参与 | 适用场景 |
|------|-------------|-------------|---------|
| 客户端模式 | `client_credentials` | 否 | 外部系统调用、定时任务、机器间通信 |
| 密码模式 | `password` | 是（提供账号密码） | 移动端 App 登录、信任的客户端 |
| 授权码模式 | `authorization_code` | 是（浏览器确认授权） | 第三方应用 SSO、开放平台 |
| 刷新令牌 | `refresh_token` | 否 | Token 续期，配合以上任意模式使用 |

---

## 外部系统完整调用流程

```
① 你在后台创建 OAuth2 客户端，拿到 client_id + secret
         │
② 外部系统用 client_credentials 模式换 token
   curl -u "client_id:secret" -d "grant_type=client_credentials"
         │
③ 拿到 access_token，之后每个请求带上
   curl -H "Authorization: Bearer <access_token>" /admin-api/xxx
         │
④ token 过期前，用 refresh_token 续期
   curl -u "client_id:secret" -d "grant_type=refresh_token" -d "refresh_token=xxx"
```