# 社交账号登录与绑定 · 配置说明

本文面向：**基于统一认证服务搭建登录体验** 的产品、前端与运营同学——在统一认证站（或嵌入其登录能力的产品）中，为用户提供 **GitHub、Google、Gitee** 等第三方账号的**登录**与**账号绑定**。

若你要做的是让**外部独立应用**使用「统一认证账号」登录，请改用 **[使用统一认证登录你的应用 · 接入指引](/docs/idp-oauth2-integration)**（OAuth 授权码流程），与本文不是同一套接口。

---

## 你需要完成的两类配置

### 1. 在各第三方开放平台登记应用

在 GitHub、Google 等平台创建 OAuth 应用，并把**授权回调地址**配置为（将根地址换成实际认证服务地址，`{provider}` 为小写提供商标识）：

```text
{{BASE_URL}}/api/oauth/callback/{provider}
```

示例：

- GitHub：`{{BASE_URL}}/api/oauth/callback/github`
- Google：`{{BASE_URL}}/api/oauth/callback/google`
- Gitee：`{{BASE_URL}}/api/oauth/callback/gitee`

回调地址须与各平台控制台要求一致（协议、域名、路径）。

### 2. 在统一认证服务侧填写平台下发的凭据

在运行统一认证服务的环境或配置中心，按下面**命名规则**填写各平台提供的 Client ID / Client Secret（名称可能因部署方式不同而对应为环境变量、密钥管理或配置项）。

**通用规则**（多数平台）：

```text
{PROVIDER}_CLIENT_ID=...
{PROVIDER}_CLIENT_SECRET=...
```

其中 `{PROVIDER}` 为提供方 ID 的**大写**，例如 `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`。

**例外（常见）**：

| 平台 | 说明 |
|------|------|
| 支付宝 | 通常使用应用 ID 及平台要求的密钥格式，请按支付宝开放平台「网页/移动应用」创建与授权文档填写 |
| 抖音 | 常使用 `DOUYIN_CLIENT_KEY` 与 `DOUYIN_CLIENT_SECRET` 对应平台下发的 client_key / secret |

未正确配置凭据的提供方不会在登录界面可用；**当前已启用的列表以接口为准**，见下文「如何知道可以展示哪些登录方式」。

---

## 登录与绑定在行为上的区别

| 场景 | 建议引导用户访问 |
|------|------------------|
| 用户尚未登录，要用第三方账号登录 | `GET {{BASE_URL}}/api/oauth/{provider}` |
| 用户已登录，要把第三方账号绑到现有账号 | `GET {{BASE_URL}}/api/oauth/bind/{provider}` |

未登录用户访问绑定地址时，一般会先被引导去登录，再返回继续绑定。具体跳转与 Cookie 行为见 **[API 参考](/docs/upstream-idp-api)**。

---

## 如何知道可以展示哪些登录方式

在构建登录页或账户设置页时，可先请求：

```http
GET {{BASE_URL}}/api/oauth/providers
```

成功时，响应 JSON 中的 `data` 为**当前已配置好凭据**的提供方 ID 数组（小写字符串，如 `github`、`google`）。**仅应对用户展示列表中出现的提供方**，避免展示未配置的按钮。

---

## 用户没有邮箱时的处理

部分第三方账号可能没有可用邮箱。统一认证站可能进入**补绑邮箱**流程，由站内页面引导用户完成验证。实现上可能使用 `POST /api/oauth/email/send` 与 `POST /api/oauth/email/verify`（浏览器侧、带站内临时会话），细节见 **[API 参考](/docs/upstream-idp-api)** 与 **[使用统一认证登录你的应用 · API 参考](/docs/idp-oauth2-api)** 中同名接口说明。

---

## 提供方能力与文档

实际支持的第三方、授权范围与各平台注册入口，以 **GitHub/Google 等平台最新文档** 为准；统一认证服务侧会按已配置的提供方返回 `providers` 列表。若某提供方未在列表中出现，请检查凭据是否已填写、平台回调 URL 是否与上文一致。