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

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

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

你需要完成的两类配置

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

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

https://auth.ncvic.com/api/oauth/callback/{provider}

示例：

GitHub：https://auth.ncvic.com/api/oauth/callback/github
Google：https://auth.ncvic.com/api/oauth/callback/google
Gitee：https://auth.ncvic.com/api/oauth/callback/gitee

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

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

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

通用规则（多数平台）：

{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 https://auth.ncvic.com/api/oauth/{provider}`
用户已登录，要把第三方账号绑到现有账号	`GET https://auth.ncvic.com/api/oauth/bind/{provider}`

未登录用户访问绑定地址时，一般会先被引导去登录，再返回继续绑定。具体跳转与 Cookie 行为见 API 参考。

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

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

GET https://auth.ncvic.com/api/oauth/providers

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

用户没有邮箱时的处理

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

提供方能力与文档

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