版本：3.10.x

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

SCIM（跨域身份管理系统）让 Okta 可以在基于 API7 Developer Portal Boilerplate 的自定义开发者门户中预配和更新身份。该集成会添加服务端插件和数据库 schema；它不是一项用于在官方前端镜像中启用端点的设置。

预配身份不会自动创建门户组织成员关系，也不会授予 API 产品访问权限。在使用 SCIM 管理开发者访问权限之前，请将预配生命周期与应用程序的授权模型集成。

前置条件

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

以下流程面向使用 Better Auth 1.7.1 的 Boilerplate v0.15.3。选择其他 SCIM 插件版本前，请检查应用程序锁定的 Better Auth 版本。

在 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)。
单击 Done。

配置常规设置

选择登录选项

安装 SCIM 插件并创建凭据

从 Boilerplate 工作区根目录将 SCIM 插件添加到站点软件包：

pnpm --filter @api7ee/site add @better-auth/scim@1.7.1

生成一个不输出到终端的不透明预配 Token：

export SCIM_TOKEN="$(openssl rand -hex 32)"

在生成 schema 和运行应用程序时保持该值可用。将它存储在部署的密钥管理器中，并在 Okta 中配置为相同的预配凭据。不要将它提交到源代码管理系统。

在门户代码中注册插件

在 apps/site/src/lib/auth/server.ts 中，将 SCIM 插件添加到现有服务端配置。保留应用程序中的其他插件和钩子。SCIM 插件要求事务支持，因此还需要在现有 Drizzle 适配器上启用事务：

apps/site/src/lib/auth/server.ts
import { scim } from '@better-auth/scim';

const scimToken = process.env.SCIM_TOKEN;
if (!scimToken) {
  throw new Error('SCIM_TOKEN is required');
}

export const auth = betterAuth({
  // 保留其他现有的 Better Auth 选项。
  database: drizzleAdapter(db, {
    provider: 'pg',
    usePlural: true,
    transaction: true,
  }),
  plugins: [
    // 在此处保留现有插件。
    scim({
      connections: [{
        id: 'okta',
        credentials: [{
          type: 'bearer',
          id: 'okta-primary',
          token: scimToken,
          scopes: ['scim.users.read', 'scim.users.write'],
        }],
      }],
    }),
  ],
});

SCIM 1.7.1 在连接上声明凭据。它不提供浏览器端 scimClient 插件或 generateSCIMToken API。用户读取和写入 scope 支持下方的用户预配流程；组预配需要单独的 scope 和应用程序集成。

检查路由处理程序

apps/site/src/routes/api/auth/$.ts 中的 TanStack Start 处理程序已经将 GET、POST、PUT、PATCH 和 DELETE 委托给 auth.handler。请保留该处理程序，不要添加 Next.js 路由或使用 toNextJsHandler。

应用数据库迁移

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

cd apps/site
pnpm dlx auth@1.7.1 generate \
  --config ./src/lib/auth/server.ts \
  --output ./src/lib/db/schema.ts
pnpm db:generate
pnpm db:migrate

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

使用配置好的 SCIM_TOKEN 部署更新后的应用程序。连接 Okta 前，请先确认身份认证路由可访问。

对于本地应用程序，可执行以下读取检查：

curl --fail-with-body -i \
  "http://localhost:3001/api/auth/scim/v2/Users?count=1" \
  -H "Authorization: Bearer ${SCIM_TOKEN}" \
  -H "Accept: application/scim+json"

远程部署时请替换 origin。返回 200 的 SCIM 列表响应（其中可以尚无资源）可验证端点身份认证和数据库访问，但不能验证门户授权。连接 ID okta 通过 bearer 凭据选择，不属于 URL 的一部分。

配置 Okta API 集成

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

配置 API 集成

配置预配并分配用户

配置预配

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

启用创建用户

分配用户

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

分配给用户

验证预配

确认分配操作会创建 SCIM 资源、属性更新会修改该资源，而停用操作会将该资源标记为非活动状态。请检查 SCIM API 和后端数据库，不要假定门户用户列表中出现条目就意味着整个集成已验证。

然后测试你实现的授权集成：组织成员关系、登录、订阅以及使用先前签发的凭据进行访问。SCIM 停用本身不能证明所有门户或网关访问权限都已撤销。

验证数据库中的用户

后续步骤

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

前置条件​

在 Okta 中创建 SCIM 应用程序​

安装 SCIM 插件并创建凭据​

在门户代码中注册插件​

检查路由处理程序​

应用数据库迁移​

配置 Okta API 集成​

配置预配并分配用户​

配置预配​

分配用户​

验证预配​

后续步骤​