---
url: /docs/auth/social-providers.md
---
# 第三方登录

## 凭据决定可用性

当前支持 Google 和 GitHub。`apps/api/lib/auth.ts` 的 `socialProviders()` 同时用于认证插件和公开能力列表，前端通过 `config.socialProviders` 显示入口。

| 服务 | 必须同时填写的变量 | 回调路径 |
| --- | --- | --- |
| Google | `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET` | `/api/auth/callback/google` |
| GitHub | `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET` | `/api/auth/callback/github` |

两项都空时不启用；只填一项时配置诊断和服务端解析报错。密钥仅保存在服务端，能力查询只返回服务名称。

## 配置步骤

1. 在对应服务创建应用，并选择正确的应用类型。
2. 将完整回调地址设置为 `APP_ORIGIN` 加上表中的路径。
3. 在本地或目标 Worker 环境写入凭据，运行配置诊断并重启接口。
4. 打开登录页，实际授权，检查回调后会话及账号邮箱。

本地 GitHub 回调示例为 `http://localhost:4400/api/auth/callback/github`。不同环境使用各自凭据和回调。GitHub OAuth 应用与 GitHub App 设置不同，后者还需要账号邮箱读取权限。

## 客户端调用

```ts
const result = await auth.signIn.social({
  provider: "github",
  callbackURL: "/dashboard",
});
if (result.error) {
  // 显示可重试的授权错误
}
```

示例中的 `auth` 来自统一认证客户端。实际回跳地址应先通过站内地址校验，不能接受任意外站链接。

## 排查

入口不显示：检查能力查询及完整凭据。回调失败：检查域名、端口、协议和回调路径是否完全相同。邮箱缺失：检查授权范围与账号隐私设置。授权取消应回到可继续操作的登录页，不算登录成功。

新增其他服务时同步服务端凭据解析、能力查询、客户端入口及环境文档。当前 Google、GitHub 的真实外部授权仍需要使用自己的应用验收。