SCIM API リファレンス

ベース URL

XID は /scim/v2/organizations/{organization_id} 配下で組織スコープの SCIM 2.0 API を公開します。ユーザーとグループのリソースはパス内の組織 ID で指定します。

ベース URL を使って ID プロバイダーを設定 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 はトークンのハッシュだけを保存し、平文トークンは作成またはローテーション時に一度だけ返します。

エンドポイント

ユーザーリソース

ユーザーリソースは外部識別子として userName を使用します。メール値、プロフィール名フィールド、アクティブ状態、エンタープライズ拡張フィールドは SCIM 生プロファイルに保持されます。

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

一括操作

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 Error スキーマ、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 サービスプロバイダーエンドポイントを公開します。下流 SaaS SCIM push クライアントはローカルの fake-SaaS 証拠を持っていますが、本番サポートには引き続き実際の SaaS 管理者 L4 が必要です。

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

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