使用 Okta 为开发者门户配置 SCIM 预配
本指南介绍如何为定制的开发者门户启用 SCIM(跨域身份管理系统)预配。集成 Okta 后,可以自动将用户账户同步到门户,使访问控制保持一致。
开发者门户基于 API7 开发者门户模板。因此,需要修改模板源代码,在身份认证系统 Better Auth 中启用 SCIM 插件。
前置条件
在 Okta 中创建 SCIM 应用
修改门户代码前,先在 Okta 中设置 SCIM 应用。
-
登录 Okta Admin Console。
-
打开 Applications > Applications。
-
点击 Browse App Catalog。
-
搜索
SCIM,选择 SCIM 2.0 Test App (Header Auth)。
-
点击 Add Integration。
-
在 General Settings 选项卡中为应用命名,例如 API7 Portal。

-
在 Sign-On Options 选项卡中选择 Secure Web Authentication (SWA)。
- 如果已单独配置 SSO,也可以选择 SAML 或 OIDC。

-
点击 Done 完成应用创建。
在开发者门户中启用 SCIM
更新门户代码,安装并配置 SCIM 插件。
安装 SCIM 插件
在项目根目录或 apps/site 目录中安装 SCIM 插件。确保插件版本与 better-auth 版本匹配。
pnpm add @better-auth/scim@1.4.10
在服务器端和客户端添加插件
修改服务器端和客户端文件,注册 SCIM 插件。
import {
// …保留已有导入项
organization,
openAPI,
} from 'better-auth/plugins';
import { scim } from '@better-auth/scim';
export const auth = betterAuth({
// …保留已有配置
plugins: [
nextCookies(),
organization(),
openAPI(),
scim(),
...getTestingConfig(),
],
});
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)管理用户。更新路由处理程序以支持这些方法。
// 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。
-
创建以下脚本。
apps/site/scripts/get-scim-token.tsimport { 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 Tokenconst 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 -
复制生成的 Token,其格式为
Y0xRcHlHZTVVZGM5aTl3U19SSGtWSFczOm9rdGE=。
配置 Okta API 集成
将 Okta 连接到开发者门户。
-
在 Okta 中打开 SCIM 应用的 Provisioning 选项卡。
-
点击 Configure API Integration > Enable API Integration。
-
配置以下默认项。
- SCIM 2.0 Base URL:在门户的身份认证 URL 后添加
/scim/v2,例如https://<YOUR_PORTAL_DOMAIN>/api/auth/scim/v2。 - API Token:输入
Bearer <YOUR_SCIM_TOKEN>。确保Bearer和 Token 之间有一个空格。
- SCIM 2.0 Base URL:在门户的身份认证 URL 后添加
-
点击 Test API Credentials 验证连接。验证成功后,点击 Save。

配置预配并分配用户
将用户分配给应用之前,先启用并配置 Okta 对启用 SCIM 的应用执行用户账户预配和生命周期变更的方式。这样,完成分配后,Okta 就能正确创建、更新和停用账户。
配置预配
- 在 Okta 中打开 SCIM 应用的 Provisioning 选项卡。
- 选择 To App 设置,点击 Edit 配置预配。
- 启用以下选项,使 Okta 可以管理应用中的用户生命周期事件。
- Create Users:将 Okta 中创建的新用户预配到应用。
- Update User Attributes:将 Okta 中的用户资料更新同步到应用。
- Deactivate Users:用户在 Okta 中取消分配或停用时,在应用中停用该用户。
- 点击 Save。

分配用户
- 在 Okta 中打开 SCIM 应用的 Assignments 选项卡。
- 点击 Assign > Assign to People,或选择 Assign to Groups。
- 选择用户或组,点击 Assign,然后点击 Done。

验证
在开发者门户的用户列表或数据库中,确认你在 Okta 中分配的用户已正确预配。
