使用 Okta 为开发者门户配置 SCIM 自动配置

本指南说明了如何为你的 自定义开发者门户（Custom Developer Portal） 启用 SCIM（跨域身份管理系统）自动配置。通过集成 Okta，你可以自动将用户帐户同步到你的门户，确保访问控制的一致性。

由于开发者门户是基于 API7 开发者门户脚手架（Boilerplate）构建的，因此此配置涉及修改源代码以在身份验证系统（Better Auth）中启用 SCIM 插件。

前置条件

1. 基于脚手架的 apps/site 结构部署并配置了自定义开发者门户。请参阅使用提供方门户设置开发者门户和自定义开发者门户。
2. 具有管理权限的 Okta 帐户。

在 Okta 中创建 SCIM 应用程序

在修改门户代码之前，请在 Okta 中设置一个 SCIM 应用程序。

1. 登录到 Okta 管理控制台。

2. 导航到 Applications > Applications。

3. 点击 Browse App Catalog。

4. 搜索 SCIM 并选择 SCIM 2.0 Test App (Header Auth)。

   

5. 点击 Add Integration。

6. 在 General Settings 选项卡中，命名该应用程序（例如，"API7 Portal"）。

   

7. 在 Sign-On Options 选项卡中，选择 Secure Web Authentication (SWA)。

   • 如果你已单独配置了 SSO，也可以选择 SAML/OIDC。

   

8. 点击 Done 以完成应用程序的创建。

在开发者门户中启用 SCIM

更新门户的代码以安装和配置 SCIM 插件。

安装 SCIM 插件

在项目根目录（或 apps/site 目录）中，安装 SCIM 插件。请确保版本与你的 better-auth 版本匹配。

pnpm add @better-auth/scim@1.4.10

将插件添加到服务端和客户端

修改服务端和客户端文件以注册 SCIM 插件：

apps/site/src/lib/auth/server.ts

import {
  // ... existing imports
  organization,
  openAPI,
} from 'better-auth/plugins';
import { scim } from '@better-auth/scim';

export const auth = betterAuth({
  // ... existing config
  plugins: [
    nextCookies(),
    organization(),
    openAPI(),
    scim(),
    ...getTestingConfig(),
  ],
});

apps/site/src/lib/auth/client.ts

import {
  // ... existing imports
  genericOAuthClient,
} from 'better-auth/client/plugins';
import { scimClient } from '@better-auth/scim/client';

export const authClient = createAuthClient({
  basePath: AUTH_BASE_PATH,
  plugins: [
    organizationClient(),
    magicLinkClient(),
    genericOAuthClient(),
    scimClient(),
  ],
});

更新路由处理程序的 HTTP 方法

SCIM 需要使用特定的 HTTP 方法（PUT、PATCH、DELETE）进行用户管理。为这些方法更新你的路由处理程序：

apps/site/app/api/auth/[...all]/route.ts

// export const { GET, POST } = toNextJsHandler(auth.handler);
export const { GET, POST, PUT, PATCH, DELETE } = toNextJsHandler(auth.handler);

更新数据库 Schema

SCIM 插件需要额外的数据库表。生成 schema 并应用迁移：

cd apps/site
pnpm db:generate-schema
pnpm db:generate
pnpm db:migrate

你应该会看到类似以下的输出：

> @api7ee/site@0.5.6 db:migrate /path/to/your/project/apps/site
> drizzle-kit migrate

No config path provided, using default 'drizzle.config.ts'
Reading config file '/path/to/your/project/apps/site/drizzle.config.ts'
Using 'pg' driver for database querying
[✓] migrations applied successfully!

生成 SCIM Token

创建一个临时脚本以生成用于 Okta 集成的 SCIM Token。

1. 创建以下脚本：

   apps/site/scripts/get-scim-token.ts

   import { auth } from '@/lib/auth/server';
   
   async function main() {
     // 1. Sign in as an admin to get a session
     const loginRes = await auth.api.signInEmail({
       returnHeaders: true,
       body: {
         email: 'admin@example.com', // Replace with your admin email
         password: 'password1234', // Replace with your admin password
       },
     });
   
     const headers = {
       cookie: loginRes.headers.get('set-cookie') || '',
     };
   
     // 2. Generate the SCIM Token for Okta
     const res = await auth.api.generateSCIMToken({
       body: {
         providerId: 'okta',
       },
       headers,
     });
     console.log('SCIM Token:', res.scimToken);
   }
   main().catch((err) => console.trace(err));

2. 运行脚本：

   pnpm dlx tsx ./scripts/get-scim-token.ts

3. 复制生成的 Token，其格式如 Y0xRcHlHZTVVZGM5aTl3U19SSGtWSFczOm9rdGE=。

配置 Okta API 集成

将 Okta 连接到你的开发者门户。

1. 在 Okta 中，导航到你的 SCIM 应用程序的 Provisioning 选项卡。

2. 点击 Configure API Integration > Enable API Integration。

3. 配置以下默认值：

   • SCIM 2.0 Base URL：输入附加了 /scim/v2 的门户认证 URL，例如 https://<YOUR_PORTAL_DOMAIN>/api/auth/scim/v2。
   • API Token：输入 Bearer <YOUR_SCIM_TOKEN>。确保 Bearer 和 Token 之间有一个空格。

4. 点击 Test API Credentials 以验证连接。如果成功，点击 Save。

配置自动配置（Provisioning）并分配用户

在为应用程序分配用户之前，你应首先启用并配置 Okta 将如何向你的 SCIM 应用程序提供用户帐户及生命周期变更。这确保了在进行分配后，Okta 能够正确地创建、更新和停用帐户。

配置 Provisioning

1. 在 Okta 中，导航到你的 SCIM 应用程序的 Provisioning 选项卡。
2. 选择 To App 设置，然后点击 Edit 配置 provisioning。
3. 启用以下选项，以便 Okta 可以在你的应用中管理用户生命周期事件：
   • Create Users：将 Okta 中创建的新用户自动提供给该应用程序。
   • Update User Attributes：将 Okta 中的个人资料更新同步到应用程序。
   • Deactivate Users：当用户在 Okta 中被取消分配或停用时，在应用程序中停用该用户。
4. 点击 Save。

分配用户

1. 在 Okta 中，导航到你的 SCIM 应用程序的 Assignments 选项卡。
2. 点击 Assign > Assign to People（或 Assign to Groups）。
3. 选择用户或组，然后点击 Assign，接着点击 Done。

验证

若要确认用户同步，请检查你的开发者门户的用户列表或数据库，以验证在 Okta 中分配的用户是否已正确配置：