---
title: "SCIM API 参考"
description: "用于向 XID 预配用户与组的 SCIM 2.0 端点契约。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/zh-hans/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM API 参考

## 基础 URL

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

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

```shell
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` | 用于存储和返回部门等企业属性。 |

```json
{
  "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，并以幂等方式同步。

```json
{
  "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 状态。

```json
{
  "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`。

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

## 错误响应

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

```json
{
  "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}` 取消用户预配并吊销活跃会话。
- 组成员关系更新是幂等的。未知成员可以在用户从身份提供商到达后解析。

Source: https://xid.dev/zh-hans/scim/index.mdx