SCIM API 참조

기본 URL

XID는 /scim/v2/organizations/{organization_id} 아래에서 조직 범위 SCIM 2.0 API를 제공합니다. 사용자 및 그룹 리소스는 경로의 조직 ID로 지정됩니다.

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는 토큰 해시만 저장하며 생성 또는 순환 시 평문 토큰을 한 번만 반환합니다.

엔드포인트

사용자 리소스

사용자 리소스는 외부 식별자로 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개 작업, 1MiB 페이로드 제한의 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 오류는 SCIM 오류 스키마, HTTP 상태, 세부 정보, 선택적 scimType와 함께 application/scim+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 공급자에서 도착한 뒤 해석할 수 있습니다.