跳到主要内容

SCIM 目录同步

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

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

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

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

启用目录同步​

  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 唯一性错误。在 Dashboard 中创建的成员仍由 Dashboard 管理。它们会出现在 IdP 的列表响应中，但 SCIM 不能修改、停用或删除这些成员。目录同步永远不能修改组织 Owner。

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

停用与删除​

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

将 Groups 映射到 Teams 和角色​

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

Directory sync (SCIM) 卡片中的两个设置控制角色映射：

  • Default role：每个同步成员获得的组织角色，默认为 member，也可以设为 admin。
  • Admin group：一个 group 名称。该 group 中的成员会获得 admin 角色，其他成员获得默认角色。

目录同步成员的角色会在每次 group 变化时重新计算，包括 group 重命名。在 Dashboard 中手动修改的角色会在下一次同步时被覆盖，因此应将目录视为同步成员的事实来源。

使用同步成员进行归因​

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

  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 所有者作为操作者。