Cato SCIM API를 사용한 사용자 정의 SCIM 앱

이 문서에서는 ID 공급자(IdP)를 사용하여 사용자 및 사용자 그룹을 프로비저닝하기 위해 Cato의 SCIM API를 사용하는 방법을 설명합니다.

IdP 테넌트에서 사용자 지정 SCIM 앱에 대한 더 많은 정보는 IdP를 위한 사용자 지정 SCIM 앱 만들기를 참조하세요.

사용자 지정 네트워크 SCIM 앱

사용자 정의 SCIM 앱을 사용하여 사용자 및 사용자 그룹을 Cato 계정에 프로비저닝하려면 Cato 관리 애플리케이션(CMA)에 앱을 생성하십시오. 또한 IdP의 속성에 Cato SCIM 속성을 매핑해야 합니다.

CMA에서 사용자 지정 SCIM 앱 만들기

SCIM API를 사용하려면 먼저 CMA에서 사용자 정의 SCIM 앱을 만들어야 합니다. 이 앱을 사용하면 IdP와 Cato 플랫폼을 통합할 수 있습니다.

CMA에서 사용자 정의 SCIM 앱을 생성하려면:

  1. 탐색 메뉴에서 액세스 > 디렉터리 서비스를 선택합니다.

  2. SCIM 탭에서 새로 만들기를 클릭합니다.

  3. 앱의 이름을 입력하세요.
  4. 공급자에서 사용자 지정을 선택합니다.
  5. 토큰 생성을 클릭하고 값을 복사하세요; 저장 후에는 사용할 수 없으므로 새 토큰을 생성해야 합니다. 

  6. 저장을 클릭합니다.

  7. 아래 설명된 SCIM API 엔드포인트를 호출할 때 인증을 위해 다음 값을 필요로 합니다:

    • SCIM Base URL: API 요청의 기본 경로로 사용됩니다.

    • Bearer Token: API 요청 검증에 사용됩니다.

Cato SCIM 속성

이것들은 Cato 사용자 및 사용자 그룹의 SCIM 속성으로서 IdP 속성에 매핑해야 합니다.

Cato 사용자 속성

설명

사용자 이름

인증을 위한 사용자 이름

사용자.이름

사용자의 이름

사용자.성

사용자의 성

사용자.이메일

이메일 주소

사용자.표시 이름

사용자의 표시 이름

phoneNumbers[type eq "work"].value

사용자의 업무 전화번호(접두어 포함)

외부 ID

사용자의 ID(이벤트에서 사용됨)

Cato 사용자 그룹 속성

설명

활성화됨

사용자가 SCIM 앱에 할당되고 활성화됨

표시 이름

사용자 그룹의 이름

구성원

사용자 그룹에 속하는 사용자

외부 ID

사용자 그룹의 ID(이벤트에서 사용됨)

Cato SCIM API 이해하기

Cato SCIM API 인증

클라이언트는 RFC 6750에 정의된 바와 같이 bearer 토큰 인증을 사용하여 SCIM API에 인증합니다. 모든 API 요청에는 다음 HTTP 헤더가 포함되어야 합니다:

Authorization: Bearer <access_token>
Content-Type: application/json

Cato 관리 애플리케이션에서 액세스 토큰을 얻을 수 있습니다.

SCIM 엔드포인트의 기본 경로

모든 SCIM API 엔드포인트는 다음 기본 경로를 사용합니다:

/scim/v2/{accountId}/{sourceId}

경로 매개변수: 

  • accountId (string): Cato 테넌트 계정의 고유 식별자

  • sourceId (integer): 특정 IdP 통합을 고유하게 표현하기 위해 Cato에서 할당한 식별자

모든 요청에 이러한 매개변수가 필요하지만 이 문서에서는 간결함을 위해 개별 엔드포인트 경로에서 생략되었습니다.

사용자 관리

이 섹션에서는 Cato SCIM API를 사용하여 SCIM 사용자 엔티티를 생성, 업데이트, 삭제 및 검색하는 방법을 설명합니다.

사용자 생성

HTTP 메서드: POST /Users 

필요한 필드: 

  • userName (string): 고유 사용자 이름 (예: 이메일 주소)

  • externalId (string): IdP의 외부 식별자

  • active (boolean): 사용자를 활성화하려면 true여야 합니다.

참고: id는 SCIM 서비스에 의해 반환되며 이후 API 호출에서 사용해야 합니다. externalId는 선택 사항이며 API 경로에서 사용할 수 없습니다.

응답: 

  • 상태: 201 Created

오류: 

  • 400 Bad Request: 잘못된 스키마

  • 401 Unauthorized 

  • 409 Conflict: userName 또는 externalId 중복

사용자 업데이트

PUT

HTTP 메서드: PUT /Users/{id} 

필요한 필드: 

  • id: Cato의 내부 SCIM ID

응답: 

  • 상태: 200 OK

오류: 

  • 401 Unauthorized 

  • 404 Not Found 

  • 409 Conflict: userName 또는 externalId 중복

PATCH

HTTP 메서드: PATCH /Users/{id} 

응답: 

  • 상태: 200 OK

오류: 

  • 400 Bad Request: 잘못된 스키마 또는 패치 구문

  • 401 Unauthorized 

  • 404 Not Found 

  • 409 Conflict: 중복 식별자

사용자 삭제

HTTP 메서드:DELETE /Users/{id}

응답:

  • 상태: 204 No Content

이것은 소프트 삭제입니다. 사용자는 시스템에 남아 있지만 검색에서는 반환되지 않습니다.

ID로 사용자 가져오기

HTTP 메서드:GET /Users/{id}

응답:

  • 상태: 200 OK

오류:

  • 401 Unauthorized

  • 404 Not Found

사용자 검색

HTTP 메서드:GET /Users

쿼리 매개변수:

  • filter: 사용자를 필터링하는 쿼리 (예: userName eq "user@domain.com")

  • count (선택 사항)

  • startIndex (선택 사항)

지원되는 필터:

  • eq만 지원됨

  • 지원되는 속성: userName, email, givenName, familyName

  • 복합 필터는 이 형식만 지원됩니다:

    filter=emails[type eq "work"] 그리고 email eq "bob@cato.com"

응답:

  • 상태: 200 OK

오류:

  • 401 권한 없음

그룹 관리

이 섹션에서는 Cato 환경에서 그룹 엔터티를 생성, 업데이트, 삭제, 그리고 검색하기 위해 SCIM API를 사용하는 방법을 설명합니다.

그룹 생성

HTTP 메서드:POST /Groups

응답:

  • 상태: 201 Created

오류:

  • 401 권한 없음

  • 409 Conflict: 중복된 displayName 또는 객체 ID

그룹 업데이트

PUT

HTTP 메서드:PUT /Groups/{id}

응답:

  • 상태: 200 OK

오류:

  • 401 권한 없음

  • 404 찾을 수 없음

  • 409 충돌

PATCH

HTTP 메서드:PATCH /Groups/{id}

지원되는 패치 경로:

  • displayName

  • members

응답:

  • 상태: 200 OK

오류:

  • 400 잘못된 요청: 유효하지 않은 스키마 또는 패치 문법

  • 401 권한 없음

  • 404 찾을 수 없음

  • 409 충돌

그룹 삭제

HTTP 메서드:DELETE /Groups/{id}

응답:

  • 상태: 204 내용 없음

참고

중요: 이것은 강제 삭제입니다. 그룹이 영구적으로 삭제됩니다.

ID로 그룹 가져오기

HTTP 메서드:GET /Groups/{id}

선택적 쿼리 매개변수:

  • excludeAttributes (예: members)

응답:

  • 상태: 200 OK

오류:

  • 401 권한 없음

  • 404 찾을 수 없음

그룹 검색

HTTP 메서드:GET /Groups

쿼리 매개변수:

  • filter: displayName eq "Group Name"만 지원됩니다

  • count (선택 사항)

  • startIndex (선택 사항)

복합 필터 또는 지원되지 않는 연산자는 필터링 없이 모든 그룹을 반환합니다.

응답:

  • 상태: 200 OK

오류:

  • 401 권한 없음

메모

생성 시 id 필드의 동작

  • id 필드는 사용자 및 그룹 생성 요청에서 선택 사항입니다.

  • 누락되면 SCIM 서비스가 고유한 id를 생성합니다.

  • 항상 후속 API 호출에서 반환된 id 값을 사용하십시오.

참고

중요: 필요하지 않은 경우 클라이언트 생성 ID 사용을 권장하지 않습니다. SCIM id는 권위 있는 식별자입니다.

삭제 동작

  • 사용자 삭제 DELETE /Users/{id}는 소프트 삭제를 수행하며, active 필드를 false로 설정합니다. 사용자는 GET /Users/{id}를 통해 검색할 수 있지만 GET /Users 결과에는 제외됩니다.

  • 그룹 삭제 DELETE /Groups/{id}는 강제 삭제를 수행합니다. 그룹이 영구적으로 삭제됩니다.

도움이 되었습니까?

0명 중 0명이 도움이 되었다고 했습니다.

댓글 0개