跳到主要内容

SCIM 目录同步

SCIM 目录同步可以把 AISIX 组织连接到你的身份提供方（IdP），由目录创建、更新和停用成员账号。AISIX 实现 SCIM 2.0 协议（RFC 7643/7644），Okta、Microsoft Entra ID 以及其他企业身份提供方都原生支持该协议。

目录同步适用于需要把网关用量归因到大量人员的组织，包括数百或数千名成员，同时不要求每个成员都登录控制台。

通过这种方式预配的成员，与可直接创建的无登录成员相同：他们可以拥有 API Key、携带限流和预算，并出现在用量报表中。他们不能登录控制台。

当某个人在 IdP 中被停用或移除时，AISIX 会停用该成员，并禁用该成员拥有的所有 API Key。该变更会传播到网关数据面，因此这些凭证会在网关本身停止工作，而不只是无法在控制台中使用。

启用目录同步​

  1. 打开 Settings，找到 Directory sync (SCIM) 卡片。

  2. 开启 Enable SCIM provisioning（仅组织 Admin 和 Owner 可操作）。

  3. 复制卡片中显示的 SCIM base URL，例如：

    https://<your-cp-api-host>/scim/v2

  4. 选择 Generate SCIM token（仅组织 Owner 可操作），并在离开页面前复制明文值。该值只会显示一次。

在 IdP 的 SCIM 连接器中配置 base URL，并把该 Token 作为 Bearer 凭证。该 Token 是一个具有独占 scim 权限范围的 Admin Token。它只能调用 SCIM 端点，在所有其他 AISIX Cloud Admin API 路由上都会被拒绝，因此即使 IdP 凭证泄漏，也不能读取或变更网关资源。

如需轮换凭证，请生成新的 SCIM Token，更新 IdP 连接器，然后在 Admin tokens 页面吊销旧 Token。

用户如何映射为成员​

SCIM 属性AISIX 成员字段
userName / emails[].value邮箱地址（身份标识）
displayName 或 name显示名称
externalId稳定的 IdP 标识符，在组织内唯一
activefalse 会停用成员并禁用其 API Key
groups团队成员关系（只读，通过 Groups 端点管理）

如果要创建的用户邮箱已经属于该组织中的某个成员，AISIX 会返回 409 唯一性错误。在控制台中创建的成员仍由控制台管理。它们会出现在 IdP 的列表响应中，但 SCIM 不能修改、停用或删除这些成员。目录同步永远不能修改组织 Owner。

通过 SCIM 删除用户时，AISIX 会先禁用该成员的 API Key，再将成员从所有团队中移除，最后移除成员资格。用量历史会保留用于报表。该邮箱会重新可用，因此后续重新预配会创建一个新的成员。

停用与删除​

  • active: false 会保留成员及其 Key，但这些 Key 会在网关侧被禁用。再次设置 active: true 时，只会重新启用目录同步禁用的 Key。由操作人员手动禁用的 Key 会保持禁用状态。
  • DELETE 会永久移除成员资格。Key 保持禁用，并保留其用量历史。

将组映射到团队和角色​

SCIM 组会同步为 AISIX 团队：推送一个组会创建同名团队，组成员关系变化会添加或移除团队成员。

Directory sync (SCIM) 卡片控制角色映射：

  • Default role：当同步成员不属于任何已映射组时获得的组织角色，可以是 member、admin 或自定义角色。
  • Group → role mappings：每个映射将一个目录组的成员分配到一个角色，按组显示名称匹配。任何可分配角色都可以作为目标，包括自定义角色。当成员属于多个已映射组时，admin 映射优先；否则使用组名称排序最靠前的映射。

目录同步成员的角色会在每次组变化时重新计算，包括组重命名；映射或默认角色变更时也会重新计算。在控制台中手动修改的角色会在下一次同步时被覆盖，因此应将目录视为同步成员的事实来源。目录同步永远不能分配 owner 角色。

使用同步成员进行归因​

目录同步会创建成员；归因方式与其他成员相同：

  1. 创建或更新 API Key，并将其 owner 设置为同步成员。
  2. 用量、限流和预算会归因到该成员。

当 IdP 停用该人员时，这些 Key 会在数秒内停止通过网关认证。

支持的端点​

SCIM 接口位于 /scim/v2 下，并以 application/scim+json 响应：

端点方法
/UsersGET（列表，以及对 userName、emails.value、externalId 的 eq 过滤）、POST
/Users/{id}GET、PUT、PATCH、DELETE
/GroupsGET（列表，以及对 displayName、externalId 的 eq 过滤）、POST
/Groups/{id}GET、PUT、PATCH、DELETE
/ServiceProviderConfig、/ResourceTypes、/SchemasGET

PATCH 遵循 SCIM PatchOp 结构，包括 Okta 和 Microsoft Entra ID 会发送的路径形式（active、members[value eq "..."]，以及不带 path 的操作）。列表响应使用 startIndex 和 count 分页（每页最多 200 条）。没有 AISIX 映射的属性（例如电话号码或地址）会被接受并忽略，因此不需要精简 IdP 属性映射。

示例：使用 curl 预配用户：

curl -sS "https://<your-cp-api-host>/scim/v2/Users" \
  -H "Authorization: Bearer ${AISIX_SCIM_TOKEN}" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "dev@example.com",
    "displayName": "Developer One",
    "emails": [
      {
        "value": "dev@example.com",
        "primary": true
      }
    ]
  }'

下一步​

  • 成员：了解手动成员接入路径以及无登录成员的行为。
  • Admin Token：了解 SCIM Token 的权限范围、轮换和吊销。
  • 日志与审计：每个 SCIM 变更都会进入组织审计记录，并以 Token 所有者作为操作者。