---
title: "SCIM API 참조"
description: "XID에 사용자와 그룹을 프로비저닝하는 SCIM 2.0 엔드포인트 계약."
locale: "ko"
---

> Documentation Index
> Fetch the locale documentation index at: https://xid.dev/ko/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로 지정됩니다.

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 클라이언트 검색을 위한 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` | 디렉터리 사용자 하나를 조회, 교체, 패치 또는 프로비저닝 해제합니다. |
| `/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는 `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으로 사용자 하나를 찾습니다. |
| `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개 작업, 1MiB 페이로드 제한의 `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 오류는 SCIM 오류 스키마, HTTP 상태, 세부 정보, 선택적 `scimType`와 함께 `application/scim+json`을 반환합니다.

```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용 inbound SCIM Service Provider 엔드포인트를 제공합니다. Downstream SaaS SCIM push client는 로컬 fake-SaaS 증거가 있지만, 프로덕션 지원에는 여전히 실제 SaaS 관리자 L4가 필요합니다.

## 프로비저닝 해제 동작

- 디렉터리 토큰 순환은 짧은 유예 기간 동안 이전 토큰을 계속 유효하게 유지합니다.
- `active=false` 및 `DELETE /Users/{id}` 사용자를 프로비저닝 해제하고 활성 세션을 폐기합니다.
- 그룹 멤버십 업데이트는 멱등입니다. 알 수 없는 멤버는 사용자가 ID 공급자에서 도착한 뒤 해석할 수 있습니다.

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