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 控制台           ↓ 方式一：通过 AI Agent（Codex）生成
  ↓ 添加 OAuth 2.0 身份源         ↓ 方式二：手动集成 SDK
  ↓ 启用托管登录页展示

阶段三：多应用 SSO 配置          阶段四：联调与验证
  ↓ 各应用注册回调地址             ↓ 验证单应用登录流程
  ↓ 统一指向同一 CloudBase 环境    ↓ 验证多应用 SSO 免登

---

详细接入步骤

阶段一：控制台配置身份源

1. 登录 CloudBase 控制台，进入目标环境；
2. 左侧菜单进入 「身份认证」→「登录方式」；
3. 选择需要接入的身份源（以 Google 为例），点击「启用」；
4. 前往 Google Cloud Console 创建 OAuth 2.0 客户端：
   • 应用类型选「Web 应用」
   • 将控制台提供的「授权回调地址」填入「已获授权的重定向 URI」
5. 将 Google 生成的 Client ID 和 Client Secret 填回 CloudBase 控制台；
6. 保存并开启该身份源；
7. 进入 「身份认证」→「托管登录页」，在「登录方式」列表中找到刚配置的身份源，勾选「展示在登录页」并保存。

⚠️ 注意： 第 7 步是必须操作。身份源保存后不会自动出现在托管登录页，需手动勾选后用户才能在登录页看到对应的登录按钮。

更多身份源（企业微信、GitHub 等）配置步骤类似，均在控制台完成，无需写代码。

---

阶段二：应用集成

在每个需要接入 SSO 的应用中集成 CloudBase JS SDK，可以选择以下两种方式：

方式一：通过 AI Agent（Codex）生成

适合使用 Codex 等 AI 编码助手开发应用的场景。将云开发 SSO 接入流程封装为自定义 Skill，由 Codex 自动生成符合规范的集成代码。

集成流程

【开发阶段 - Codex】                  【运行时 - 用户浏览器】
        │                                      │
        │ 客户："给这个应用加上 SSO 登录"        │
        │──► 调用 add_cloudbase_auth Skill      │
        │◄── 生成 SDK 初始化 + 登录跳转代码      │
        │    部署应用到云开发                    │
        │                              用户访问应用
        │                              未登录 → SDK 检测 → 跳转托管登录页
        │                              用户完成 SSO 认证
        │                              携带 code 回调 → SDK 自动处理
        │                              Session 就绪，正常使用应用

Skill 定义（OpenAI Tool Calling 格式）

{
  "type": "function",
  "function": {
    "name": "add_cloudbase_auth",
    "description": "为当前 Web 应用添加云开发 SSO 登录能力。生成 SDK 初始化、登录态检查、托管登录页跳转及回调处理的完整代码。",
    "parameters": {
      "type": "object",
      "properties": {
        "env_id": {
          "type": "string",
          "description": "云开发环境 ID，从控制台获取"
        },
        "region": {
          "type": "string",
          "description": "环境所在地域，默认 ap-shanghai",
          "default": "ap-shanghai"
        },
        "publishable_key": {
          "type": "string",
          "description": "Publishable Key，从控制台「身份认证 → 应用管理」获取"
        },
        "redirect_uri": {
          "type": "string",
          "description": "SSO 登录完成后回调的应用页面地址"
        }
      },
      "required": ["env_id", "publishable_key", "redirect_uri"]
    }
  }
}

Skill 实现（生成集成代码的参考逻辑）

// add-cloudbase-auth.skill.ts
// Codex 调用此 Skill 后，生成云开发 SSO 集成代码注入到目标文件

interface SkillInput {
  env_id: string
  region?: string
  publishable_key: string
  redirect_uri: string
}

function addCloudbaseAuth(input: SkillInput): string {
  const { env_id, region = 'ap-shanghai', publishable_key, redirect_uri } = input

  return `
import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({
  env: '${env_id}',
  region: '${region}',
  accessKey: '${publishable_key}',
  auth: { detectSessionInUrl: true }
})

const auth = app.auth()

async function checkAuth() {
  const session = await auth.getSession()
  if (!session) {
    auth.toDefaultLoginPage({ redirect_uri: '${redirect_uri}' })
    return null
  }
  return await auth.getUser()
}

async function getCurrentUser() {
  return await auth.getUser()
}

async function logout() {
  await auth.signOut()
}

export { checkAuth, getCurrentUser, logout }
`
}

提示： 以上 Skill 仅为参考框架，客户可根据自身技术栈（React、Vue、原生 JS 等）调整生成的代码结构，例如封装为 Hook、Store 或 Service 模块。

方式二：手动集成 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 的域名/路径也加入白名单。

---

阶段四：联调与验证

验证单应用登录

1. 浏览器无痕模式，访问应用；
2. 触发登录跳转 → 托管登录页显示已配置的身份源；
3. 选择身份源完成认证；
4. 确认以下检查项：
   • 正确跳回应用的 redirect_uri
   • auth.getSession() 返回有效 Session
   • auth.getUser() 返回正确的用户信息（姓名、邮箱等）
   • 登出后 Session 清除，再次访问需重新登录

验证多应用 SSO

1. 在 App A 完成登录；
2. 新标签页打开 App B（同一 CloudBase 环境）；
   1. App B 调用 auth.getSession()，应直接返回 Session，不触发登录跳转；
   2. 如 App B 仍触发跳转，到托管登录页后也应无需再次输入密码（OAuth 身份源侧有已有 Session，自动回调）。

---

登录时序图

用户          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 是服务端密钥，仅用于服务端，不可暴露在前端代码中。

Q: What is the difference between accessKey and SecretKey during SDK initialization? A: accessKey (Publishable Key) is a client-side key that can be publicly exposed, used for front-end SDK initialization, and poses no security risk if leaked. SecretKey is a server-side key used exclusively for server-side operations, and must not be exposed in front-end code.