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

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

本指南涵盖了自定义门户应用程序中所需的代码级更改，以便它可以公开 SCIM 端点并处理配置请求。

先决条件

• 你的自定义开发者门户是从 API7 开发者门户样板部署的。
• 你已配置门户并可以访问其身份验证路由。
• 你拥有具有管理权限的 Okta 账户。

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

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

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

1. 登录 Okta 管理控制台。
2. 转至 应用程序 -> 应用程序。
3. 单击“浏览应用程序目录”。
4. 搜索SCIM。
5. 选择 SCIM 2.0 测试应用程序（标头验证）。
6. 单击“添加集成”。
7. 在 常规设置 中，为应用程序命名，例如 API7 门户。
8. 在登录选项中，选择安全 Web 身份验证 (SWA)。
9. 单击“完成”。

步骤2：安装SCIM 插件

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

pnpm add @better-auth/scim@1.4.10

第三步：在门户代码中注册插件

更新服务器和客户端身份验证代码以注册 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 方法来进行配置操作。相应地更新 auth路由处理程序。

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

你应该看到迁移输出，表明架构更改已成功应用。

步骤 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 应用程序的 配置 选项卡。
2. 单击配置 API 集成。
3. 启用 API 集成。
4. 设置： — SCIM 2.0 基础 URL 至 https://<YOUR_PORTAL_DOMAIN>/api/auth/scim/v2 — API 代币 为 Bearer <YOUR_SCIM_TOKEN>
5. 单击测试 API 凭证。
6. 如果测试成功，点击保存。

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

配置配置

1. 在配置选项卡中，选择到应用程序。
2. 单击“编辑”。
3. 启用你需要的功能： — 创建用户 — 更新用户属性 — 停用用户
4. 单击“保存”。

分配用户

1. 打开作业选项卡。
2. 单击 分配 -> 分配给人员 或 分配给组。
3. 选择要配置的用户或组。
4. 单击“分配”，然后单击“完成”。

步骤 9：验证配置

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

你可以在门户用户列表中或直接在支持数据库中确认这一点，具体取决于你操作门户的方式。

后续步骤

• 配置开发者门户 — 管理内置门户设置，包括 SCIM 预配。
• 自定义开发者门户 — 通过附加行为扩展样板。
• 为开发者门户配置 SSO — 在 SCIM 预配旁边添加交互式登录选项。