---
title: "SCIM API リファレンス"
description: "XID にユーザーとグループをプロビジョニングする SCIM 2.0 エンドポイント契約。"
locale: "ja"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ja/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 を使って ID プロバイダーを設定 `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 クライアント検出用の ServiceProviderConfig レスポンス。 |
| `/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` | ディレクトリユーザー 1 件を読み取り、置換、パッチ、またはプロビジョニング解除します。 |
| `/scim/v2/organizations/{organization_id}/Groups` | `GET, POST` | ディレクトリグループを作成、一覧表示します。 |
| `/scim/v2/organizations/{organization_id}/Groups/{id}` | `GET, PUT, PATCH, DELETE` | ディレクトリグループ 1 件を読み取り、置換、パッチ、または削除します。 |

## ユーザーリソース

ユーザーリソースは外部識別子として `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 は `and`、`or`、`not` と比較演算子（`eq`、`ne`、`co`、`sw`、`ew`、`gt`、`ge`、`lt`、`le`、`pr`）を含む SCIM フィルター文法をサポートします。未サポート式は `invalidFilter` を返します。一覧応答は `startIndex`、`count`、`totalResults` を使う SCIM 1 始まりのページネーションと、任意の `sortBy`、`sortOrder` を使用します。

| クエリ | サポート |
| --- | --- |
| `filter=userName eq "alice@example.com"` | userName でユーザーを 1 件検索します。 |
| `filter=displayName eq "Engineering"` | displayName でグループを 1 件検索します。 |
| `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 Error スキーマ、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 サービスプロバイダーエンドポイントを公開します。下流 SaaS SCIM push クライアントはローカルの fake-SaaS 証拠を持っていますが、本番サポートには引き続き実際の SaaS 管理者 L4 が必要です。

## プロビジョニング解除の動作

- ディレクトリトークンのローテーションでは、以前のトークンが短い猶予期間だけ有効なままになります。
- `active=false` および `DELETE /Users/{id}` ユーザーのプロビジョニングを解除し、アクティブなセッションを取り消します。
- グループメンバーシップ更新は冪等です。不明なメンバーは、ユーザーが ID プロバイダーから到着した後に解決できます。

Source: https://xid.dev/ja/scim/index.mdx