AI Coding 平台 SSO 身份源接入方案
本文档面向企业客户及平台集成方，介绍如何基于 CloudBase 身份认证，将企业现有 OAuth 2.0 身份源（如 Google、企业微信等）接入 AI Coding 平台，实现多应用统一登录（SSO）。
适用场景
- 企业已有 OAuth 2.0 身份源（Google Workspace、企业微信等），希望员工使用已有账号直接登录 AI Coding 平台；
- 平台下部署了多个子应用（如MCP 工具台、管理后台），需要 登录一次、全部应用免登；
- 希望统一账号生命周期：身份源停用账号后，平台侧同步失效。
方案概述
核心原理
本方案以 CloudBase 托管登录页 作为 SSO 中枢。所有应用统一将未登录用户重定向到同一个托管登录页，由该页面完成与 OAuth 2.0 身份源的交互；身份认证通过后，CloudBase 颁发统一 Session，用户回到任意应用均已登录。
App A ──┐
│ 未登录时重定向 OAuth 2.0
App B ──┼──────────────► CloudBase 托管登录页 ◄──► 企业身份源
│ │ （Google / 企业微信等）
App C ──┘ │ 颁发 CloudBase Session
▼
用户回到原应用，已登录 ✅
为什么选择托管登录页
| 对比项 | 托管登录页 | 自建登录页 |
|---|---|---|
| SSO Session 共享 | ✅ 自动，所有应用共用一个 CloudBase Session | ❌ 需自行实现跨应用 Session 同步 |
| OAuth 2.0 接入 | ✅ 控制台配置即可，无需写代码 | ⚠️ 需调用 SDK 手动处理 OAuth 流程 |
| 接入成本 | 低 | 高 |
结论： 如需实现多应用 SSO，推荐使用托管登录页。
支持的身份源类型
| 身份源 | 协议 | 接入方式 |
|---|---|---|
| Google Workspace | OAuth 2.0 | 控制台配置，开箱即用 |
| 企业微信 | OAuth 2.0 | 控制台配置，开箱即用 |
| GitHub | OAuth 2.0 | 控制台配置，开箱即用 |
| 自定义 OAuth 2.0 身份源 | OAuth 2.0 | 控制台-企业身份源配置 |
| 更多企业身份源 | 如SAML | 控制台-企业身份源配置 |
整体架构
┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
│ │
│ App A / App B / App C │
│ │ 未登录，调用 auth.toDefaultLoginPage() │
│ ▼ │
│ CloudBase 托管登录页（统一入口） │
│ │ 用户选择登录方式 │
│ ▼ │
│ OAuth 2.0 身份源 │
│ │ 认证通过，携带 code 回调 │
│ ▼ │
│ CloudBase 身份认证服务 │
│ │ 颁发 Session Token，写入浏览器 │
│ ▼ │
│ 重定向回原应用，Session 已就绪 │
└─────────────────────────────────────────────────────────────┘
接入流程总览
整体接入分为以下 4 个阶段，预计总耗时 半天至 1 个工作日：
阶段一：控制台配置身份源 阶段二：应用集成
↓ 在 CloudBase 控制台 ↓ 集成 CloudBase JS SDK
↓ 添加 OAuth 2.0 身份源 ↓ 实现登录跳转与回调处理
↓ 启用托管登录页展示
阶段三：多应用 SSO 配置 阶段四：联调与验证
↓ 各应用注册回调地址 ↓ 验证单应用登录流程
↓ 统一指向同一 CloudBase 环境 ↓ 验证多应用 SSO 免登
详细接入步骤
阶段一：控制台配置身份源
- 登录 CloudBase 控制台，进入目标环境；
- 左侧菜单进入 「身份认证」→「登录方式」；
- 选择需要接入的身份源（以 Google 为例），点击「启用」；
- 前往 Google Cloud Console 创建 OAuth 2.0 客户端：
- 应用类型选「Web 应用」
- 将控制台提供的「授权回调地址」填入「已获授权的重定向 URI」
- 将 Google 生成的 Client ID 和 Client Secret 填回 CloudBase 控制台；
- 保存并开启该身份源；
- 进入 「身份认证」→「托管登录页」，在「登录方式」列表中找到刚配置的身份源，勾选「展示在登录页」并保存。
⚠️ 注意： 第 7 步是必须操作。身份源保存后不会自动出现在托管登录页，需手动勾选后用户才能在登录页看到对应的登录按钮。
更多身份源（企业微信、GitHub 等）配置步骤类似，均在控制台完成，无需写代码。
阶段二：应用集成
在每个需要接入 SSO 的应用中集成 CloudBase JS SDK，按以下步骤完成集成。
安装 SDK
npm install @cloudbase/js-sdk
或直接在 HTML 中引用（建议使用本地打包版本）：
<script type="module">
import cloudbase from './sdk.js'
</script>
初始化与登录跳转
import cloudbase from '@cloudbase/js-sdk'
const app = cloudbase.init({
env: 'your-env-id', // CloudBase 环境 ID
region: 'ap-shanghai', // 环境所在地域
accessKey: 'your-publishable-key', // 可公开的 Publishable Key
auth: { detectSessionInUrl: true } // 自动处理 OAuth 回调
})
const auth = app.auth()
// 检查登录态，未登录则跳转到托管登录页
const session = await auth.getSession()
if (!session) {
auth.toDefaultLoginPage({ redirect_uri: window.location.href })
}
获取用户信息
const session = await auth.getSession()
if (session) {
const user = await auth.getUser()
console.log(user.nickname, user.email)
}
登出
await auth.signOut()
阶段三：多应用 SSO 配置
实现多应用 SSO 的关键：所有应用使用同一个 CloudBase 环境（同一个 env ID）。
CloudBase Session 以 env ID 为维度存储在用户浏览器中，只要多个应用指向同一环境，用户在 App A 登录后，App B 调用 auth.getSession() 即可直接拿到已有 Session，无需再次跳转登录页。
App A ──┐
├── 同一 env ID ──► 共享 CloudBase Session ✅
App B ──┘
各应用只需额外配置： 在 CloudBase 控制台的身份源「授权回调地址」中，将 App B 的域名/路径也加入白名单。
阶段四：联调与验证
验证单应用登录
- 浏览器无痕模式，访问应用；
- 触发登录跳转 → 托管登录页显示已配置的身份源；
- 选择身份源完成认证；
- 确认以下检查项：
- 正确跳回应用的
redirect_uri -
auth.getSession()返回有效 Session -
auth.getUser()返回正确的用户信息（姓名、邮箱等） - 登出后 Session 清除，再次访问需重新登录
- 正确跳回应用的
验证多应用 SSO
- 在 App A 完成登录；
- 新标签页打开 App B（同一 CloudBase 环境）；
- App B 调用
auth.getSession()，应直接返回 Session，不触发登录跳转； - 如 App B 仍触发跳转，到托管登录页后也应无需再次输入密码（OAuth 身份源侧有已有 Session，自动回调）。
- App B 调用
登录时序图
用户 App A / App B CloudBase OAuth 身份源
│ │ │ │
│── 访问应用 ─────►│ │ │
│ │ │ │
│ │ getSession() → 无 │ │
│ │── toDefaultLoginPage() ───────────────► │
│ │ │ │
│◄──── 重定向到 CloudBase 托管登录页 ───│ │
│ │ │ │
│── 选择登录方式 ─────────────────────►│── 重定向到身份源 ──►│
│ │ │ │
│◄──────────────────────── 身份源携带 code 回调 ────────────│
│ │ │ │
│ │ │ 用 code 换 token │
│ │ │ 创建/更新用户 │
│ │ │ 颁发 CloudBase Session
│◄──── 携带 Session 重定向回 App ──────│ │
│ │ │ │
│── 访问 App B ──►│ │ │
│ │ getSession() → 有 │ │
│◄── 直接进入，无需再次登录 ───────────│ │
账号生命周期管理
| 事件 | 触发方式 | 平台行为 |
|---|---|---|
| 新用户首次登录 | 通过身份源完成 OAuth 认证 | 自动在 CloudBase 创建用户账号 |
| 用户信息变更 | 下次登录时 OAuth 返回新信息 | 自动同步昵称、头像、邮箱 |
| 员工离职 | 在 OAuth 身份源侧禁用账号 | 下次登录时认证失败，无法获取新 Session |
| 已有 Session 失效 | Session 到期或主动登出 | 需重新走登录流程 |
常见问题（FAQ）
Q：多个应用必须部署在同一个域名下吗？ A：不需要。只要多个应用使用同一个 CloudBase 环境 ID，Session 就会共享。不同域名的应用均可实现 SSO。
Q：托管登录页的样式可以自定义吗？ A：支持在控制台对托管登录页进行基础样式配置（Logo、品牌色等）。如需完全自定义 UI，需使用自建登录页（注意：SDK不支持 企业OAuth 2.0 / SAML 身份源）。
Q：支持同时配置多个身份源吗？ A：支持。可在控制台同时开启多个身份源（如同时开启 Google 和企业微信），托管登录页会展示所有已启用的登录方式，用户自行选择。
Q：SDK 初始化时 accessKey 和 SecretKey 有什么区别？
A：accessKey（Publishable Key）是可公开的客户端密钥，用于前端 SDK 初始化，泄露无安全风险。SecretKey 是服务端密钥，仅用于服务端，不可暴露在前端代码中。