SCIM

개요 {#overview}

SCIM(System for Cross-domain Identity Management)는 개방형 표준이며 표준화된 인터페이스로 사용자 정보를 교환할 수 있도록 제공한다.
SCIM을 이용해 IdP(Identity Provider)로부터 구성원과 그룹을 프로비저닝하는 과정을 간소화하고, 수작업을 줄일 수 있다.

다음의 SCIM 2.0 RFC 문서를 기반으로 구현한다.

• RFC 7642: Definitions, Overview, Concepts, and Requirements
• RFC 7643: Core Schema
• RFC 7644: Protocol

지원 기능 {#supported-features}

IdP(Identity Provider) 또는 인사 시스템에서 SCIM 연동을 통해 다음과 같은 기능을 활용할 수 있다.

자동 계정 생성(Provisioning)

신규 입사한 구성원 정보를 IdP 또는 인사 시스템에 추가하면 프로비저닝을 통해 NAVER WORKS에도 자동으로 계정이 생성된다.

자동 계정 비활성화(Deprovisioning)

구성원이 퇴사하여 IdP 또는 인사 시스템에서 삭제되면 NAVER WORKS에서도 자동으로 비활성화된다.
비활성화된 구성원은 더 이상 NAVER WORKS에 로그인할 수 없다. 자세한 내용은 User - Status를 참고한다.

정보 동기화

IdP 또는 인사 시스템에서 구성원 정보(이름, 이메일, 전화번호 등)가 변경되면 NAVER WORKS에도 자동으로 동기화된다.

그룹 관리

프로젝트, TF 등을 위한 커뮤니케이션 목적의 팀을 구성할 때 그룹 멤버십을 중앙에서 관리할 수 있다.
IdP 또는 인사 시스템에서 그룹의 멤버를 추가하거나 삭제하면 NAVER WORKS에도 자동으로 반영된다.
이를 통해 메시지방 및 메시지방 기능(노트, 캘린더, 폴더, 할 일) 리소스의 접근 권한을 제어할 수 있다.
자세한 내용은 Group을 참고한다.

전제 조건 {#prerequisites}

SCIM 프로비저닝은 유료 상품에서만 사용할 수 있다. 무료 상품에서는 사용할 수 없다.

API 호출 {#api-call}

API endpoint {#api-endpoint}

SCIM API를 호출하기 위한 엔드포인트는 다음과 같다.

https://www.worksapis.com/scim/v2

예를 들어, 구성원 목록을 조회한다면 다음과 같이 호출한다.

GET https://www.worksapis.com/scim/v2/Users

Authorization {#authorization}

API를 호출하려면 Access Token이 필요하다.

SCIM 전용 Long-Lived Token 발급 방법을 참고하여 Access Token을 획득하고, Authorization 헤더를 사용하여 Bearer Token 방식으로 호출해야 한다.

Authorization: Bearer {Access Token}

Resources {#resources}

User {#user}

API {#user-api}

구성원을 관리할 수 있다.

Status {#user-status}

SCIM으로 프로비저닝되는 구성원의 상태 라이프사이클은 다음과 같다.

구성원의 활성화 여부는 active 속성(boolean)으로 관리한다.
WORKS 내에서 active 속성값은 '로그인 가능 여부'를 의미한다.
각 구성원 상태별 active 속성값은 다음과 같다.

구성원 상태에 대한 자세한 설명은 Directory API 개요 - 구성원(users)를 참조한다.

Group {#group}

SCIM Group API로는 내부 그룹만 조작할 수 있다.
동적 그룹은 조회만 가능하다.
외부 그룹은 생성, 수정, 삭제, 조회할 수 없다.

API {#group-api}

프로젝트나 사내 모임 활동과 같은 커뮤니케이션을 위한 그룹을 관리할 수 있다.

관리자/구성원 {#group-administrator-and-member}

• SCIM Group API로 그룹 관리자는 추가/삭제할 수 없다.
• SCIM Group API로 그룹 관리자가 아니어도 그룹을 수정, 삭제할 수 있다.
• 그룹 구성원으로는 구성원 또는 그룹만 지정할 수 있다.
  NAVER WORKS 서비스에서는 그룹 구성원으로 조직도 지정할 수 있다.
• SCIM Group API로 그룹 구성원을 변경하더라도 그룹 관리자 및 조직 타입 그룹 구성원은 변경되지 않는다.

메시지방 기능 {#group-team-feature}

• 그룹 추가 시 메시지방 기능, 메일링리스트 기능은 모두 비활성화된 상태로 생성된다.
  이 기능을 사용하려면 NAVER WORKS 서비스 내에서 그룹을 수정하거나 NAVER WORKS API를 이용하여 활성화한다.
• SCIM Group API로 설정할 수 없는 속성(메시지방 기능, 메일링리스트, 공개여부 등)은 그룹 수정 또는 그룹 부분 수정 SCIM API가 호출되어도 기존값을 유지한다.

호출 제한 {#rate-limit}

SCIM API는 API당 240 requests/min의 호출 제한이 적용된다.

제약 사항 {#limitations}

• Filter
  • eq만 제공한다.
  • User는 userName 속성, Group은 displayName 속성으로만 필터링할 수 있다.
  • 그 외의 기능은 제공하지 않는다.
• Patch Operation
  • 자세한 내용은 PATCH Operation을 참고한다.
• 다음의 기능을 제공하지 않는다.
  • Bulk Operations
  • Sync Password
  • Sort
  • eTag
  • Self Resource
• 그룹사 환경에서는 다음과 같은 제약 조건이 있다.
  • Access Token은 발급받은 도메인에만 사용할 수 있다. 그룹사 환경에서는 각 도메인 에서 발급받은 Access Token을 사용해야 한다.
  • SCIM User API로는 다른 도메인에 겸직 설정을 할 수 없다. Admin Console 또는 NAVER WORKS API를 사용해야 한다.
• SSO(SAML 2.0)와 함께 사용할 경우 Developer Console > SSO > WORKS as SP(SAML)에서 User Key를 반드시 "NAVER WORKS Account(ex. id@domain)"로 선택해야 한다.
• SCIM을 통해 프로비저닝된 리소스도 NAVER WORKS/LINE WORKS 서비스 내에서 수정, 삭제할 수 있다.
  단, SCIM을 통해 프로비저닝된 속성을 NAVER WORKS 서비스 또는 API로 수정하면 IdP(Identity Provider)와 데이터 불일치가 발생할 수 있다.
• SCIM User API로 설정할 수 없는 속성(소속 조직, 직급, 직책, 공개 여부 등)은 Admin Console 또는 NAVER WORKS API를 사용하여 변경할 수 있다. 수정 또는 부분 수정을 하더라도 이 속성들의 값은 유지된다.

PATCH Operation {#patch-operation}

RFC 7644 - 3.5.2. Modifying with PATCH 명세에 따라 동작한다.

filter 연산은 제한적으로 제공한다.

• eq, and 연산자만 제공한다.
• and 연산은 최대 2개의 피연산자만 허용한다.
  즉, A and B는 허용하지만 A and B and C는 제공하지 않는다.

허용하는 Operation 유형 {#patch-operation-use-case}

Request Body의 Operations 속성에서 수정하려는 대상 속성의 유형에 따라 허용하는 포맷은 다음과 같다.

단일 값 속성 유형 (string, integer, boolean)

ADD, REPLACE

• Use Case 1

{  "op": "[ ADD | REPLACE ]",  "path": "{key}",  "value": "{value}"}

• Use Case 2

{  "op": "[ ADD | REPLACE ]",  "value": {    "{key}": "{value}"  }}

REMOVE

{  "op": "REMOVE",  "path": "{key}"}

Object 속성 유형

ADD, REPLACE

• Use Case 1

{  "op": "[ ADD | REPLACE ]",  "path": "{mainKey}.{subKey}",  "value": "{value}"}

• Use Case 2

{  "op": "[ ADD | REPLACE ]",  "path": "{mainKey}",  "value": {    "{subKey1}": "{value1}",    "{subKey2}": "{value2}",    ...  }}

• Use Case 3

{  "op": "[ ADD | REPLACE ]",  "value": {    "{mainKey}": {      "{subKey1}": "{value1}",      "{subKey2}": "{value2}" ,      ...    }  }}

REMOVE

• Use Case 1

{  "op": "REMOVE",  "path": "{mainKey}"}

• Use Case 2

{  "op": "REMOVE",  "path": "{mainKey}.{subKey}"}

Array 속성 유형

ADD, REPLACE

• Use Case 1

{  "op": "[ ADD | REPLACE ]",  "path": "{key}",  "value": [    object1,    object2,    ...  ]}

• Use Case 2

{  "op": "[ ADD | REPLACE ]",  "value": {    "{key}": [      object1,      object2,      ...    ]  }}

• Use Case 3

{  "op": "[ ADD | REPLACE ]",  "path": "{key}[filter]",  "value": object}

• Use Case 4

{  "op": "[ ADD | REPLACE ]",  "path": "{key}[filter].{subKey}",  "value": "{value}"}

• Use Case 5 : ADD 만 지원

{  "op": "ADD",  "path": "{key}",  "value": object}

REMOVE

• Use Case 1

{  "op": "REMOVE",  "path": "{key}"}

• Use Case 2

{  "op": "REMOVE",  "path": "{key}[filter]"}

• Use Case 3

{  "op": "REMOVE",  "path": "{key}",  "value": [    {      "value": "{value}"    },    ...  ]}

• Use Case 4

{  "op": "REMOVE",  "path": "{key}[filter]",  "value": [    {      "value": "{value}"    },    ...  ]}

감사 {#audit}

Admin Console의 감사 > 주소록 페이지에서 서비스 타입을 SCIM으로 필터링하면 SCIM API 호출 이력을 확인할 수 있다.