SSO Identity Provider Integration for AI Coding Platforms

This document is intended for enterprise customers and platform integrators. It explains how to integrate an existing enterprise OAuth 2.0 identity provider (such as Google or WeCom) with an AI Coding platform via CloudBase Authentication, enabling unified single sign-on (SSO) across multiple applications.

---

Use Cases

• The enterprise already has an OAuth 2.0 identity provider (Google Workspace, WeCom, etc.) and wants employees to sign in to the AI Coding platform with their existing accounts.
• Multiple sub-applications (such as an MCP toolbox or admin console) are deployed under the platform and require sign in once, access everything.
• Unified account lifecycle: when an account is disabled in the identity provider, access on the platform side is invalidated synchronously.

---

Solution Overview

Core Principle

This solution uses the CloudBase Hosted Login Page as the SSO hub. All applications redirect unauthenticated users to the same hosted login page, which handles the OAuth 2.0 interaction with the identity provider. Once authentication succeeds, CloudBase issues a unified session, and the user is signed in across all applications.

App A ──┐
        │  Redirect when unauthenticated     OAuth 2.0
App B ──┼──────────────► CloudBase Hosted Login Page ◄──► Enterprise IdP
        │                     │                       (Google / WeCom, etc.)
App C ──┘                     │ Issue CloudBase Session
                              ▼
                    User returns to the original app, signed in ✅

Why Choose the Hosted Login Page

Comparison Item	Hosted Login Page	Custom Login Page
SSO session sharing	✅ Automatic; all applications share one CloudBase session	❌ Cross-application session sync must be built
OAuth 2.0 setup	✅ Configure in the console; no code required	⚠️ Requires SDK calls to handle the OAuth flow
Integration cost	Low	High

Conclusion: For multi-application SSO, the hosted login page is recommended.

---

Supported Identity Provider Types

Identity Provider	Protocol	Integration Method
Google Workspace	OAuth 2.0	Console configuration, ready out of the box
WeCom	OAuth 2.0	Console configuration, ready out of the box
GitHub	OAuth 2.0	Console configuration, ready out of the box
Custom OAuth 2.0 provider	OAuth 2.0	Console — Enterprise IdP configuration
More enterprise IdPs	e.g. SAML	Console — Enterprise IdP configuration

---

Overall Architecture

┌─────────────────────────────────────────────────────────────┐
│                       User Browser                          │
│                                                             │
│   App A / App B / App C                                     │
│       │ Unauthenticated; calls auth.toDefaultLoginPage()    │
│       ▼                                                     │
│   CloudBase Hosted Login Page (unified entry)               │
│       │ User picks a sign-in method                         │
│       ▼                                                     │
│   OAuth 2.0 Identity Provider                               │
│       │ Auth succeeds; redirects with code                  │
│       ▼                                                     │
│   CloudBase Authentication Service                          │
│       │ Issues a session token, stored in the browser       │
│       ▼                                                     │
│   Redirects back to the original app; session is ready      │
└─────────────────────────────────────────────────────────────┘

---

Integration Flow Overview

The integration consists of 4 phases, with an estimated total effort of half a day to one working day:

Phase 1: Configure the IdP in console     Phase 2: Application integration (choose one)
  ↓ In the CloudBase Console                ↓ Option A: Generate via AI Agent (Codex)
  ↓ Add an OAuth 2.0 identity provider      ↓ Option B: Integrate the SDK manually
  ↓ Enable display on the hosted login page

Phase 3: Multi-application SSO setup      Phase 4: Joint debugging and verification
  ↓ Register callback URLs per app          ↓ Verify single-app sign-in flow
  ↓ Point all apps to the same CloudBase    ↓ Verify multi-app SSO (no re-login)
    environment

---

Detailed Integration Steps

Phase 1: Configure the Identity Provider in the Console

1. Sign in to the CloudBase Console and enter the target environment.
2. In the left-hand menu, go to Authentication → Sign-in Methods.
3. Choose the identity provider to integrate (using Google as an example) and click Enable.
4. Go to the Google Cloud Console and create an OAuth 2.0 client:
   • Application type: Web application
   • Paste the Authorized redirect URI provided by the CloudBase Console into Authorized redirect URIs.
5. Paste the Client ID and Client Secret generated by Google back into the CloudBase Console.
6. Save and enable the identity provider.
7. Go to Authentication → Hosted Login Page, find the identity provider you just configured in the Sign-in Methods list, check Show on login page, and save.

⚠️ Note: Step 7 is required. After saving, an identity provider does not automatically appear on the hosted login page; you must explicitly enable it before the corresponding sign-in button becomes visible to end users.

Other identity providers (WeCom, GitHub, etc.) follow a similar process — fully console-driven, no code required.

---

Phase 2: Application Integration

Each application that needs SSO must integrate the CloudBase JS SDK. You can choose one of the following two options:

Option A: Generate via AI Agent (Codex)

Recommended when you build applications with Codex or similar AI coding assistants. The CloudBase SSO integration flow is encapsulated as a custom Skill, and Codex automatically generates compliant integration code.

Integration flow

[Development - Codex]                    [Runtime - User Browser]
        │                                          │
        │ Customer: "Add SSO sign-in to this app"  │
        │──► Calls the add_cloudbase_auth Skill     │
        │◄── Generates SDK init + login redirect    │
        │    Deploys the application to CloudBase   │
        │                                  User opens the app
        │                                  Unauthenticated → SDK detects → Redirect to hosted login page
        │                                  User completes SSO authentication
        │                                  Provider redirects back with code → SDK handles automatically
        │                                  Session is ready; the app works normally

Skill definition (OpenAI Tool Calling format)

{
  "type": "function",
  "function": {
    "name": "add_cloudbase_auth",
    "description": "Add CloudBase SSO sign-in to the current Web application. Generates a complete code snippet for SDK initialization, session checking, redirection to the hosted login page, and callback handling.",
    "parameters": {
      "type": "object",
      "properties": {
        "env_id": {
          "type": "string",
          "description": "CloudBase environment ID; available in the console"
        },
        "region": {
          "type": "string",
          "description": "Region of the environment, defaults to ap-shanghai",
          "default": "ap-shanghai"
        },
        "publishable_key": {
          "type": "string",
          "description": "Publishable Key, available in the console under Authentication → Application Management"
        },
        "redirect_uri": {
          "type": "string",
          "description": "Application URL to redirect back to after SSO sign-in completes"
        }
      },
      "required": ["env_id", "publishable_key", "redirect_uri"]
    }
  }
}

Skill implementation (reference logic for generated integration code)

// add-cloudbase-auth.skill.ts
// After Codex calls this Skill, it injects CloudBase SSO integration code into the target file.

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 }
`
}

Tip: The Skill above is a reference scaffold. Customers can adjust the generated code structure for their tech stack (React, Vue, plain JS, etc.), for example by wrapping it as a Hook, Store, or Service module.

Option B: Integrate the SDK manually

Recommended when you have an existing codebase and want precise control over where the integration is placed.

Install the SDK

npm install @cloudbase/js-sdk

Or reference it directly from HTML (a locally bundled build is recommended):

<script type="module">
  import cloudbase from './sdk.js'
</script>

Initialize and redirect to sign-in

import cloudbase from '@cloudbase/js-sdk'

const app = cloudbase.init({
  env: 'your-env-id',                // CloudBase environment ID
  region: 'ap-shanghai',             // Region of the environment
  accessKey: 'your-publishable-key', // Publishable Key (safe to expose)
  auth: { detectSessionInUrl: true } // Automatically handle the OAuth callback
})

const auth = app.auth()

// Check the session; redirect to the hosted login page if not signed in
const session = await auth.getSession()
if (!session) {
  auth.toDefaultLoginPage({ redirect_uri: window.location.href })
}

Get the user info

const session = await auth.getSession()
if (session) {
  const user = await auth.getUser()
  console.log(user.nickname, user.email)
}

Sign out

await auth.signOut()

---

Phase 3: Multi-application SSO Setup

The key to multi-application SSO: all applications use the same CloudBase environment (the same env ID).

CloudBase stores the session in the user's browser keyed by env ID. As long as multiple applications point to the same environment, after a user signs in to App A, App B can call auth.getSession() and obtain the existing session directly — without redirecting to the login page again.

App A  ──┐
          ├── Same env ID ──► Shared CloudBase Session ✅
App B  ──┘

The only extra setup per application: in the CloudBase Console, add the domains/paths of App B (and any other apps) to the Authorized redirect URIs allowlist of the identity provider.

---

Phase 4: Joint Debugging and Verification

Verify Single-Application Sign-in

1. Open the application in a browser incognito window.
2. Trigger the sign-in redirect → the hosted login page should display the configured identity providers.
3. Pick an identity provider and complete authentication.
4. Confirm the following checks:
   • You are correctly redirected back to the application's redirect_uri.
   • auth.getSession() returns a valid session.
   • auth.getUser() returns the correct user info (name, email, etc.).
   • After signing out, the session is cleared and the next visit requires re-authentication.

Verify Multi-Application SSO

1. Sign in to App A.
2. Open App B (in the same CloudBase environment) in a new tab:
   1. App B calls auth.getSession() and should obtain a session directly, without triggering a sign-in redirect.
   2. If App B still triggers a redirect, the hosted login page should not require re-entering the password (because the OAuth identity provider already has an active session and will auto-callback).

---

Sign-in Sequence Diagram

User          App A / App B         CloudBase          OAuth IdP
 │                 │                    │                    │
 │── Open app ────►│                    │                    │
 │                 │                    │                    │
 │                 │ getSession() → none │                    │
 │                 │── toDefaultLoginPage() ───────────────► │
 │                 │                    │                    │
 │◄──── Redirect to CloudBase Hosted Login Page ─────────────│
 │                 │                    │                    │
 │── Pick a sign-in method ────────────►│── Redirect to IdP ►│
 │                 │                    │                    │
 │◄──────────────────────── IdP redirects with code ─────────│
 │                 │                    │                    │
 │                 │                    │ Exchange code for token
 │                 │                    │ Create/update user
 │                 │                    │ Issue CloudBase Session
 │◄──── Redirect back to app with session ──────────────────│
 │                 │                    │                    │
 │── Open App B ──►│                    │                    │
 │                 │ getSession() → yes  │                    │
 │◄── Enter directly; no re-sign-in ────│                    │

---

Account Lifecycle Management

Event	Trigger	Platform Behavior
First-time user sign-in	Completes OAuth authentication via the IdP	A user account is automatically created in CloudBase
User profile change	OAuth returns updated info on the next sign-in	Nickname, avatar, and email are synced automatically
Employee offboarding	Disable the account in the OAuth IdP	Next sign-in fails; no new session can be issued
Existing session expires	Session times out or the user signs out manually	The user must go through the sign-in flow again

---

FAQ

Q: Do all applications have to be deployed under the same domain? A: No. As long as the applications use the same CloudBase environment ID, the session is shared. Applications on different domains can all participate in the same SSO flow.

Q: Can the hosted login page UI be customized? A: Basic styling (logo, brand color, etc.) can be configured for the hosted login page in the console. If you need full UI customization, you must build a custom login page (note: the SDK does not support enterprise OAuth 2.0 / SAML providers in custom login pages).

Q: Can multiple identity providers be configured at the same time? A: Yes. You can enable multiple identity providers simultaneously in the console (for example, both Google and WeCom). The hosted login page lists all enabled sign-in methods, and the user picks one.

Q: What's the difference between accessKey and SecretKey in SDK initialization? A: accessKey (Publishable Key) is a client-side key safe to expose in front-end code; leaking it does not pose a security risk. SecretKey is a server-side key used only on the server side and must never be exposed in front-end code.