跳到主要内容
版本:3.9.x

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

本指南介绍如何为定制的开发者门户启用 SCIM(跨域身份管理系统)预配。集成 Okta 后,可以自动将用户账户同步到门户,使访问控制保持一致。

开发者门户基于 API7 开发者门户模板。因此,需要修改模板源代码,在身份认证系统 Better Auth 中启用 SCIM 插件。

前置条件​

  1. 已按模板的 apps/site 目录结构部署并配置定制的开发者门户。参阅部署开发者门户和定制开发者门户。
  2. 拥有具备管理员权限的 Okta 账户。

在 Okta 中创建 SCIM 应用​

修改门户代码前,先在 Okta 中设置 SCIM 应用。

  1. 登录 Okta Admin Console。

  2. 打开 Applications > Applications。

  3. 点击 Browse App Catalog。

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

    在 Okta 中搜索 SCIM 集成

  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 {
// …保留已有导入项
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(),
],
});

更新路由处理程序的 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);

更新数据库架构​

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

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. 以管理员身份登录并获取会话
    const loginRes = await auth.api.signInEmail({
    returnHeaders: true,
    body: {
    email: 'admin@example.com', // 替换为你的管理员电子邮件地址
    password: 'password1234', // 替换为你的管理员密码
    },
    });

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

    // 2. 为 Okta 生成 SCIM Token
    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:在门户的身份认证 URL 后添加 /scim/v2,例如 https://<YOUR_PORTAL_DOMAIN>/api/auth/scim/v2。
    • API Token:输入 Bearer <YOUR_SCIM_TOKEN>。确保 Bearer 和 Token 之间有一个空格。
  4. 点击 Test API Credentials 验证连接。验证成功后,点击 Save。

配置 API 集成

配置预配并分配用户​

将用户分配给应用之前,先启用并配置 Okta 对启用 SCIM 的应用执行用户账户预配和生命周期变更的方式。这样,完成分配后,Okta 就能正确创建、更新和停用账户。

配置预配​

  1. 在 Okta 中打开 SCIM 应用的 Provisioning 选项卡。
  2. 选择 To App 设置,点击 Edit 配置预配。
  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 中分配的用户已正确预配。

在数据库中验证用户