SCIM API 参考

基础 URL

XID 在 /scim/v2/organizations/{organization_id} 下公开组织范围的 SCIM 2.0 API。用户和组资源通过路径中的组织 ID 定位。

使用基础 URL 配置你的身份提供商 https://xid.dev/scim/v2/organizations/{organization_id} 以及创建或轮换目录时只显示一次的目录令牌。

curl https://xid.dev/scim/v2/organizations/{organization_id}/Users \
  -H 'Authorization: Bearer scim_xxx' \
  -H 'Content-Type: application/scim+json'

认证

SCIM 调用使用由管理 API 创建的目录 Bearer 令牌。XID 只存储令牌哈希，并且只在创建或轮换时返回一次明文令牌。

请求头	值	备注
`Authorization`	`Bearer scim_xxx`	组织范围内的用户和组端点必填。
`Content-Type`	`application/scim+json`	POST、PUT 和 PATCH 请求必需。
`Accept`	`application/scim+json`	推荐所有 SCIM 客户端使用。

端点

端点	方式	使用
`/scim/v2/ServiceProviderConfig`	`GET`	用于 SCIM 客户端发现的服务提供商配置响应。
`/scim/v2/Schemas`	`GET`	用户和组架构元数据。
`/scim/v2/ResourceTypes`	`GET`	支持的 SCIM 资源类型。
`/scim/v2/organizations/{organization_id}/Users`	`GET, POST`	创建并列出目录用户。
`/scim/v2/organizations/{organization_id}/Users/{id}`	`GET, PUT, PATCH, DELETE`	读取、替换、修补或取消预配一个目录用户。
`/scim/v2/organizations/{organization_id}/Groups`	`GET, POST`	创建并列出目录组。
`/scim/v2/organizations/{organization_id}/Groups/{id}`	`GET, PUT, PATCH, DELETE`	读取、替换、修补或移除一个目录组。

用户资源

用户资源使用 userName 作为外部标识符。邮箱值、资料姓名字段、活跃状态和企业扩展字段都会保留在 SCIM 原始资料中。

SCIM 字段	XID 行为
`id`	稳定的 XID 目录用户 ID。
`userName`	必填。必须在目录内唯一。
`active`	`false` 会取消用户预配并吊销活跃会话。
`emails`	主邮箱用于匹配和账户链接。
`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User`	用于存储和返回部门等企业属性。

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "alice@example.com",
  "active": true,
  "name": { "givenName": "Alice", "familyName": "Lee" },
  "emails": [{ "value": "alice@example.com", "primary": true }]
}

组资源

组资源使用 displayName 作为唯一目录组名。成员引用 SCIM 用户 ID，并以幂等方式同步。

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "dir_user_123", "display": "alice@example.com" }
  ]
}

过滤、排序和分页

XID 支持 SCIM 过滤语法，包含 and、or、not 以及比较运算符（eq、ne、co、sw、ew、gt、ge、lt、le、pr）。不支持的表达式返回 invalidFilter。列表响应使用 SCIM 从 1 开始的分页，包含 startIndex、count 和 totalResults，以及可选的 sortBy 和 sortOrder。

查询	支持
`filter=userName eq "alice@example.com"`	按 userName 查找一个用户。
`filter=displayName eq "Engineering"`	按 displayName 查找一个组。
`filter=userName sw "alice" and active eq true`	组合逻辑运算符和比较运算符。
`sortBy=userName&sortOrder=ascending`	对用户或组列表结果排序。
`startIndex=1&count=100`	从第一条结果开始最多返回 100 个资源。
`attributes=userName,emails.value`	仅返回 schemas、id 和请求的 SCIM 属性。
`excludedAttributes=emails,meta`	返回默认资源，但不包含被排除的 SCIM 属性。

批量操作

POST /scim/v2/organizations/{organization_id}/Bulk 接受最多 100 个操作、载荷上限 1 MiB 的 BulkRequest。即使部分操作失败，响应也会在 BulkResponse 中返回每个操作的 HTTP 状态。

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "Operations": [
    {
      "method": "POST",
      "path": "/Users",
      "bulkId": "user1",
      "data": { "userName": "alice@example.com", "active": true }
    }
  ]
}

ETag and If-Match

资源 GET 响应包含来自 meta.version 的 ETag: W/"<meta.version>"。PUT 和 PATCH 需要与当前版本匹配的 If-Match 头；缺失时返回 428，不匹配时返回 412。

PATCH 操作

PATCH 请求使用 urn:ietf:params:scim:api:messages:2.0:PatchOp。XID 支持对可写资料字段和组成员关系执行 add、replace 和 remove。

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    { "op": "replace", "path": "active", "value": false }
  ]
}

错误响应

SCIM 错误返回 application/scim+json，包含 SCIM 错误结构、HTTP 状态、详情和可选 scimType。

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "scimType": "uniqueness",
  "detail": "userName already exists"
}

ServiceProviderConfig 能力

ServiceProviderConfig 公布 sort.supported=true、bulk.supported=true 和 etag.supported=true。
XID 为外部 IdP 公开入站 SCIM Service Provider 端点。下游 SaaS SCIM push client 有本地 fake-SaaS 证据，但生产支持仍需要真实 SaaS 管理员 L4。

取消预配行为

目录令牌轮换会让旧令牌在短暂宽限期内继续有效。
active=false 和 DELETE /Users/{id} 取消用户预配并吊销活跃会话。
组成员关系更新是幂等的。未知成员可以在用户从身份提供商到达后解析。