社交连接器

部分实现 -- 基础设施已完成，暂无内置社交 Provider 实现。连接器的 CRUD 管理和测试功能可正常使用，但需要开发具体的社交 Provider 后才能实际接入社交平台登录。

概述

社交连接器用于集成第三方社交平台的 OAuth 登录能力，使 Code Bird Cloud 的用户能够使用已有的社交账号（如微信、GitHub、Google 等）快速登录，无需单独注册账户。

使用场景

社交连接器为用户提供便捷的一键登录体验：

场景	说明
社交账号登录	用户点击社交登录按钮，跳转到第三方平台授权，授权后自动登录或注册
账号绑定	已有用户可以绑定社交账号，后续可通过社交账号直接登录

常见社交 Provider

以下是可以集成的常见社交登录平台：

Provider	说明
微信	微信扫码登录（适用于 PC 端）和微信内网页授权（适用于 H5）
GitHub	GitHub OAuth 登录，适合开发者用户群体
Google	Google OAuth 2.0 登录，全球化覆盖
Apple	Apple Sign In，适合 iOS 应用
支付宝	支付宝账号登录
钉钉	钉钉扫码登录，适合企业用户
飞书	飞书账号登录，适合使用飞书的企业

社交登录流程

社交登录基于 OAuth 2.0 协议，典型流程如下：

用户                   Code Bird Cloud              社交平台（如 GitHub）
 |                          |                              |
 | 1. 点击社交登录按钮       |                              |
 |------------------------->|                              |
 |                          |                              |
 | 2. 302 重定向到社交平台   |                              |
 |<-------------------------|                              |
 |                          |                              |
 | 3. 跳转到社交平台授权页   |                              |
 |-------------------------------------------------------->|
 |                          |                              |
 | 4. 用户在社交平台授权     |                              |
 |<--------------------------------------------------------|
 |                          |                              |
 | 5. 携带授权码回调         |                              |
 |------------------------->|                              |
 |                          | 6. 用授权码换取用户信息       |
 |                          |----------------------------->|
 |                          |<-----------------------------|
 |                          |                              |
 |                          | 7. 匹配/创建用户             |
 |                          |                              |
 | 8. 登录成功，返回令牌     |                              |
 |<-------------------------|                              |

流程说明

发起社交登录：用户在 Code Bird Cloud 的登录页面点击社交登录按钮
重定向到社交平台：系统根据连接器配置生成社交平台的 OAuth 授权 URL，将用户重定向过去
用户授权：用户在社交平台的授权页面确认授权
授权码回调：社交平台将用户重定向回 Code Bird Cloud 的回调地址，携带授权码
获取用户信息：Code Bird Cloud 使用授权码向社交平台换取 Access Token，再获取用户资料
用户匹配/创建：系统根据社交平台返回的用户标识匹配已有用户，如果是新用户则自动创建账户
完成登录：完成 OIDC 授权流程，返回令牌

配置示例

以下是创建社交连接器的配置示例（以微信为例）：

json

{
  "connector_id": "wechat-native",
  "type": "Social",
  "config": {
    "app_id": "your_wechat_app_id",
    "app_secret": "your_wechat_app_secret"
  },
  "enabled": true
}

以下是 GitHub 社交连接器的配置示例：

json

{
  "connector_id": "github",
  "type": "Social",
  "config": {
    "client_id": "Iv1.abcdef123456",
    "client_secret": "your_github_client_secret"
  },
  "enabled": true
}

配置字段说明

不同的社交 Provider 所需的配置字段不同。通常需要在社交平台的开放平台中创建应用，获取 Client ID 和 Client Secret。

以微信为例：

字段	类型	必填	说明
`app_id`	string	是	微信开放平台应用的 AppID
`app_secret`	string	是	微信开放平台应用的 AppSecret

以 GitHub 为例：

字段	类型	必填	说明
`client_id`	string	是	GitHub OAuth App 的 Client ID
`client_secret`	string	是	GitHub OAuth App 的 Client Secret

API 参考

创建社交连接器

POST /api/v1/connectors
Content-Type: application/json

{
  "connector_id": "github",
  "type": "Social",
  "config": {
    "client_id": "Iv1.abcdef123456",
    "client_secret": "your-github-client-secret"
  },
  "enabled": true
}

更新社交连接器

PATCH /api/v1/connectors/:id
Content-Type: application/json

{
  "config": {
    "client_id": "Iv1.newclientid",
    "client_secret": "new-client-secret"
  }
}

测试社交连接器

配置完成后，建议通过测试端点验证 OAuth 配置的有效性。

POST /api/v1/connectors/:id/test

删除社交连接器

DELETE /api/v1/connectors/:id

删除正在使用的社交连接器会导致对应的社交登录按钮从登录页面消失。已通过该社交账号绑定的用户不受影响，但无法再通过该社交账号登录。

与登录体验的集成

与邮件和短信连接器不同，社交连接器配置并启用后，对应的社交登录按钮会自动出现在登录页面上，无需在登录体验中额外配置登录方式。

登录页面会根据已启用的社交连接器自动展示对应的图标和名称。

社交连接器 ​

概述 ​

使用场景 ​

常见社交 Provider ​

社交登录流程 ​

流程说明 ​

配置示例 ​

配置字段说明 ​

API 参考 ​

创建社交连接器 ​

更新社交连接器 ​

测试社交连接器 ​

删除社交连接器 ​

与登录体验的集成 ​

相关文档 ​