# 社交账号登录与绑定 · API 参考

本文描述：用户在**统一认证站**使用 **GitHub、Google 等第三方账号**完成**登录**或**绑定**时，浏览器会访问的 HTTP 接口。适用于前端联调、移动端 WebView 或自建登录页对接。

**根地址**：路径均相对于认证服务根 URL。生产环境示例为 `https://auth.ncvic.com`；文中以 `{{BASE_URL}}` 表示根地址（无末尾斜杠）。

---

## GET /api/oauth/providers

**作用**：返回**当前已配置好凭据**的第三方提供方 ID 列表，供登录页、设置页决定展示哪些按钮。

**认证**：不需要。

### 响应

- **200**：JSON，`data` 为字符串数组，例如 `["github","google"]`（以实际为准）。

---

## GET /api/oauth/{provider}

**作用**：为**未登录用户**发起第三方登录：将浏览器 **302** 到对应平台授权页。

**路径参数**

- `provider`：小写，如 `github`、`google`、`gitee`。须出现在 `GET /api/oauth/providers` 返回的列表中（或等价地，已在服务端完成配置）。

### 响应

- **302**：前往第三方授权页
- **400**：不支持的 `provider`
- **503**：该提供方未配置

### 行为说明

- 实际回调 URL 为 `{{BASE_URL}}/api/oauth/callback/{provider}`（由服务根据访问域名生成，与你在各平台控制台登记的地址一致即可）。
- 防重放使用的 `state` 由服务写入 **HttpOnly** Cookie（如 `oauth_state_{provider}`），由浏览器自动携带，**无需你的前端手工拼接 state**（除非产品与实现另有约定）。

---

## GET /api/oauth/callback/{provider}

**作用**：第三方授权完成后，**由平台重定向**到本地址；服务用授权码换取令牌、获取用户标识、创建或关联本站账号，再 **302** 到站内业务页面（或补绑邮箱等页面）。

**认证**：不需要；依赖第三方回调 URL 上的 `code`、`state` 等参数。

### 响应

- **302**：进入站内目标页或错误提示页
- 成功时可能下发本站会话 Cookie（如 `auth_token`）

**注意**：此 URL 应只填写在 **GitHub/Google 等平台的「回调地址」配置**中，作为**统一认证站**对外的回调；它**不是**你在做「应用接统一认证 OAuth」时给业务应用填的 `redirect_uri`（后者见 **[使用统一认证登录你的应用 · API 参考](/docs/idp-oauth2-api)**）。

---

## GET /api/oauth/bind/{provider}

**作用**：**已登录用户**将第三方账号绑定到当前账号；浏览器 **302** 到第三方授权页。

**认证**：需要本站登录会话（Cookie 或 Bearer）。未登录时通常会 **302** 到登录页，并在参数中带回跳地址。

### 路径参数

- `provider`：同登录接口。

### 响应

- **302**：前往第三方授权页
- **400** / **503**：含义与登录接口类似

授权完成后仍回到 `GET /api/oauth/callback/{provider}`，由服务端根据绑定会话将第三方身份关联到当前用户。

---

## POST /api/oauth/email/send

**作用**：在站内**补绑邮箱**流程中，向用户邮箱发送 6 位验证码。

**调用方**：用户浏览器（站内页面）。

**前提**：请求需携带统一认证站在该流程中下发的临时 Cookie（`mfa_pending`，类型为绑定邮箱）。

### 请求

`Content-Type: application/json`

```json
{ "email": "user@example.com" }
```

### 响应

- **200**：已发送
- **401**：流程已过期等
- **429**：频控

---

## POST /api/oauth/email/verify

**作用**：校验验证码，完成邮箱绑定并建立会话。

**前提**：同上。

### 请求

`Content-Type: application/json`

```json
{ "code": "123456", "deviceFingerprint": "可选" }
```

### 响应

- **200**：成功
- **401**：验证码错误或过期

参数与语义与 **[使用统一认证登录你的应用 · API 参考](/docs/idp-oauth2-api)** 中同名接口一致；在本文场景下由**站内页面**调用，**独立业务应用的后端通常不需要对接**。