使用 Okta 为自定义开发者门户配置 SCIM 预配

本指南介绍如何为基于 API7 Developer Portal Boilerplate 的自定义开发者门户启用 SCIM（跨域身份管理系统）预配。通过集成 Okta，你可以自动将开发者账户同步到门户。

本指南涵盖自定义门户应用中所需的代码级更改，以便它能够暴露 SCIM 端点并处理预配请求。

前置条件

• 你的自定义开发者门户通过 API7 Developer Portal Boilerplate 部署。
• 你已配置门户并可以访问其身份认证路由。
• 你拥有具有管理权限的 Okta 账户。

开发者门户 SCIM 的基本设置请参见配置开发者门户。

步骤 1：在 Okta 中创建 SCIM 应用程序

在修改门户代码之前，请在 Okta 中创建 SCIM 应用程序。

1. 登录 Okta Admin Console。
2. 转到 Applications -> Applications。
3. 单击 Browse App Catalog。
4. 搜索 SCIM。
5. 选择 SCIM 2.0 Test App (Header Auth)。
6. 单击 Add Integration。
7. 在 General Settings 中，为应用命名，例如 API7 Portal。
8. 在 Sign-On Options 中，选择 Secure Web Authentication (SWA)。
9. 单击 Done。

步骤 2：安装 SCIM 插件

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

pnpm add @better-auth/scim@1.4.10

步骤 3：在门户代码中注册插件

更新服务器和客户端身份认证代码以注册 SCIM 支持。

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

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

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

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

import {
  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(),
  ],
});

步骤 4：更新路由处理程序

SCIM 预配操作需要额外的 HTTP 方法。请相应更新身份认证路由处理程序。

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

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

步骤 5：应用数据库迁移

SCIM 插件需要额外的数据库表。

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

你应该看到迁移输出，表明数据库 Schema 变更已成功应用。

步骤 6：生成 SCIM 令牌

创建一个临时脚本来生成用于 Okta 集成的 SCIM 令牌。

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

import { auth } from '@/lib/auth/server';

async function main() {
  const loginRes = await auth.api.signInEmail({
    returnHeaders: true,
    body: {
      email: 'admin@example.com',
      password: 'password1234',
    },
  });

  const headers = {
    cookie: loginRes.headers.get('set-cookie') || '',
  };

  const res = await auth.api.generateSCIMToken({
    body: {
      providerId: 'okta',
    },
    headers,
  });

  console.log('SCIM Token:', res.scimToken);
}

main().catch((err) => console.trace(err));

运行脚本：

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

复制生成的令牌以用于下一步。

步骤 7：配置 Okta API 集成

1. 在 Okta 中，打开 SCIM 应用的 Provisioning 选项卡。
2. 单击 Configure API Integration。
3. 启用 API 集成。
4. 设置：
   • 将 SCIM 2.0 Base URL 设为 https://<YOUR_PORTAL_DOMAIN>/api/auth/scim/v2
   • 将 API Token 设为 Bearer <YOUR_SCIM_TOKEN>
5. 单击 Test API Credentials。
6. 如果测试成功，单击 Save。

步骤 8：配置预配并分配用户

配置预配

1. 在 Provisioning 选项卡中，选择 To App。
2. 单击 Edit。
3. 启用你需要的功能：
   • Create Users
   • Update User Attributes
   • Deactivate Users
4. 单击 Save。

分配用户

1. 打开 Assignments 选项卡。
2. 单击 Assign -> Assign to People 或 Assign to Groups。
3. 选择要预配的用户或组。
4. 单击 Assign，然后单击 Done。

步骤 9：验证预配

验证 Okta 中分配的用户是否已预配到你的自定义开发者门户中。

根据你的门户运维方式，可以在门户用户列表中或直接在后端数据库中确认。

后续步骤

• 配置开发者门户 — 管理内置门户设置，包括 SCIM 预配。
• 定制开发者门户 — 通过附加行为扩展 Boilerplate。
• 开发者门户 SSO 状态 — 在规划与 SCIM 预配配套的交互式登录选项前，先了解已发布组件之间的不匹配问题。