프로비저닝(Provisioning)

SCIM 프로비저닝을 통한 멤버 관리

Swit의 계정 정보가 IdP의 계정 정보와 동기화되어 사용자 정보의 변경 사항이 실시간으로 반영되는 방식입니다. 사용자 활성 상태에 따라 액세스 제어, 과금 중단 등이 자동으로 이루어지기 때문에 조직 관리자가 별도로 시트를 관리할 필요가 없습니다.

TIP

IdP(Identity Provider)는 사용자의 신원 정보를 제공, 저장 및 관리하는 시스템으로, Microsoft Entra ID (Azure Active Directory), Okta 등이 있습니다.

Swit 프로비저닝 동기화 원리

Swit 프로비저닝은 SCIM (System for Cross-domain Identity Management) 2.0 표준을 따르고 있으며, 아래의 과정을 통해 지정된 IdP 측에서 주기적으로 확인하고 업데이트합니다.

동기화 과정

IdP 측에서 IdP에 포함된 각 사용자 및 그룹별로 Swit에도 동일한 정보가 있는지 확인하는 요청을 한 후 응답 결과에 따라 아래와 같은 후속 요청을 보냅니다.

Swit 측에 해당 사용자 또는 그룹이 없는 경우: Create 요청으로 Swit 측에 동일한 사용자 계정 또는 팀을 신규 생성
Swit 측에 동일한 사용자 또는 그룹이 있으나 정보가 다른 경우: Update 요청을 통해 Swit 측에 동일한 정보를 반영
IdP에서 비활성되거나 삭제된 사용자 또는 그룹이 Swit에 활성 상태로 남아있는 경우: Disable/Delete 요청을 통해 Swit 측에서도 비활성(사용자 계정) 또는 삭제(팀)
이미 Swit 측 정보가 동일할 경우: 후속 요청 없음

TIP

본 섹션은 Swit 프로비저닝이 동작하는 원리에 대한 설명이므로, 빠른 구성을 원한다면 다음 섹션으로 건너 뛰어도 됩니다.

사전 구성

IdP에 Swit의 SCIM 전용 엔드포인트 URL를 입력합니다.
- 추후 IdP가 사용자 및 그룹 정보를 확인·업데이트할 때 이 URL에 요청을 보내게 됩니다. IdP → Swit으로 요청 전송 시 사용할 오픈 API용 인증 정보를 입력합니다.

IdP에서 Swit 프로비저닝 구성하기

IdP에서 Swit 사용자 프로비저닝을 구성하는 방법은 다음과 같습니다. Microsoft Entra ID (Azure Active Directory) 또는 Okta를 IdP로 사용할 경우, 여기를 참고하면 보다 구체적인 절차를 확인할 수 있습니다.

프로비저닝을 설정할 IdP에 접속합니다.
해당 IdP의 매뉴얼을 참조하여 아래의 SCIM 관련 주요 정보를 입력합니다. 레이블 명칭은 IdP별로 상이할 수 있습니다.
- SCIM 엔드포인트 URL: https://saml.swit.io/scim/v2
- 인증 정보(참고 문서: https://devdocs.swit.io/docs/guides/
  1. OAuth 2.0 방식 선택
  2. OAuth 인증 엔드포인트: https://openapi.swit.io/oauth/authorize
  3. OAuth 토큰 교환 엔드포인트: https://openapi.swit.io/oauth/token
  4. OAuth 스코프: admin:read admin:write
  5. Client ID와 Client Secret은 Swit Developers 웹사이트에서 앱을 구성한 다음, 해당 값을 복사할 수 있습니다.
  6. 또한 IdP에서 제공하는 OAuth callback URL을 아래 화면의 Redirect URLs 목록에 추가해주세요.
OAuth 인증을 마친 후, IdP에서 Swit에 연동하고자 하는 정보의 속성값을 매핑(Mappings)합니다.

Swit에 프로비저닝 가능한 매핑 속성

Swit에서 사용하는 사용자 및 그룹 속성 명칭은 아래와 같으며, IdP의 각 속성과 매핑할 수 있습니다.

사용자 속성

IdP 측 사용자 고유 ID: externalId (매칭 기준 속성으로 사용 권장)
이메일 주소: userName (매칭 기준 속성으로 사용 권장)
사용자 활성 여부: active
연락처: phoneNumbers
사용자 이름: displayName
Swit에서 사용할 인터페이스 언어: preferredLanguage
- 계정 생성 시에만 동기화하고 이미 사용 중인 계정에는 동기화하지 않을 것을 권장합니다. 대부분의 IdP는 속성별로 이러한 옵션을 제공합니다.
커스텀 필드: urn:ietf:params:scim:schemas:extension:SwitCustomField:2.0:User:<<CUSTOM_FIELD_ID>>

TIP

각 멤버가 프로비저닝 시도 시, Swit에서 사용하는 사용자 속성 중 userName과 externalId가 일반적으로 매칭 기준 속성으로 권장됩니다.

그룹 속성

IdP의 ‘그룹’은 Swit의 ‘팀’과 동기화됩니다.

IdP 측 사용자 고유 ID: externalId
그룹 명칭: displayName (매칭 기준 속성으로 사용 권장)
소속 멤버 목록: members

TIP

각 멤버가 프로비저닝 시도 시, 사용자 속성은 userName과 externalId가, 그룹 속성은 userName이 매칭 속성으로 권장됩니다.

Swit에서 설정 가능한 프로비저닝 옵션

프로비저닝으로 사용자 속성을 동기화하면, 멤버들이 자신의 프로필 정보를 직접 수정해도 이내 곧 IdP 정보로 동기화되어버리기 때문에 다소간의 혼란을 겪을 수 있습니다. 이에 Swit에서는 멤버들이 프로필 정보를 직접 수정할 수 없게 하는 옵션을 제공하고 있습니다.
이 옵션을 사용하려면 관리자 콘솔 > SAML 구성에서 프로비저닝 동기화 항목을 '멤버 프로필은 프로비저닝을 통해서만 변경'으로 설정해주세요.(SAML을 이용한 Single sign-on 활성화 선택 시에만 사용 가능)
이 옵션을 사용하면 아래와 같이 멤버들이 커스텀 필드 이외의 프로필 정보를 직접 수정할 수 없게 됩니다.

IdP별 연동 예시 보기

아래는 Microsoft Entra ID (Azure Active Directory)와 Okta의 프로비저닝 연동 예시입니다. 참고하여 프로비저닝 구성을 완료하세요.

Microsoft Entra ID (Azure Active Directory)

아래의 절차에 따라 Azure AD Gallery에서 Swit 앱을 설치합니다. 만일 SSO 설정을 위해 이미 Swit 앱을 설치했다면 해당 앱을 선택해주세요.

Azure Portal에 로그인한 다음, Active Directory > Enterprise applications와 All applications를 선택합니다.
앱 목록에서 Swit을 선택합니다. AAD에 설치한 Swit 앱에서 프로비저닝을 구성하는 방법은 아래와 같습니다.
1. 왼쪽 패널에서 Provisioning 항목을 선택한 다음, Get Started 버튼을 클릭하여 구성을 시작합니다.
2. 프로비저닝 모드를 Automatic으로 설정합니다.
Admin Credentials에서 Authorize 버튼 클릭 후, 표시되는 모달을 통해 OAuth 2.0 인증을 진행합니다. 이때 동기화되는 Swit 조직의 관리자 계정으로 로그인되어 있어야 합니다.
Mappings 영역은 사용자 및 그룹에서 동기화할 속성을 매핑하기 위한 곳입니다. Azure AD Gallery에서 설치한 앱이라면 대부분의 매핑이 사전 구성되어있지만, 커스텀이 필요하면 Swit에 프로비저닝 가능한 매핑 속성 섹션을 참고하여 설정을 변경해주세요.
필요하다면 Settings 영역에서 원하는 항목에 체크한 후 Save 버튼을 클릭하여 설정을 마칩니다.
왼쪽 패널에서 Users and groups 항목을 선택한 후 Swit 프로비저닝을 사용하게 할 사용자들을 추가합니다.
Provisioning 화면으로 다시 이동한 후 Start provisioning 탭을 클릭합니다.
- AAD의 프로비저닝은 최대 40분 주기로 사용자 및 그룹 속성을 동기화합니다. 다음 사이클을 기다리지 않고 바로 동기화를 확인해보려면 Provision on demand 탭을 클릭하세요.

Okta

Okta에 접속한 후, 관리자 계정으로 로그인합니다.
Admin Console > Applications 탭에서 Applications를 선택합니다.
프로비저닝을 구성할 앱을 선택합니다.
General 탭에서 App Settings 섹션 우측의 Edit 버튼을 클릭합니다.
Provisioning항목을 SCIM으로 선택한 다음, Save 버튼을 클릭합니다.
클릭하는 순간 Provisioning 탭이 새로 생성됩니다. 해당 탭에서 Integration 페이지로 이동합니다.
SCIM Connection 섹션 우측의 Edit 버튼을 클릭한 다음, 다음과 같이 항목들을 채워 넣습니다.
- SCIM connector base URL: https://saml.swit.io/scim/v2
- Unique identifier field for users: userName
- Supported provisioning actions: 다음 다섯 가지 항목에 모두 체크
  - Import New Users and Profile Updates
  - Push New Users
  - Push Profile Updates
  - Push Groups
  - Import Groups
- Authentication Mode: OAuth 2
OAuth 2 섹션은 IdP에서 Swit 프로비저닝 구성하기를 참고하여 입력해주세요.
- 단, 스코프 정보는 따로 입력할 수 없으므로 Authorization endpoint URI 항목에 다음과 같이 파라미터로 추가해서 입력해주세요.
  - https://openapi.swit.io/oauth/authorize?scope=admin%3Aread%20admin%3Awrite
- Swit Developers 사이트 앱 내 Redirect URLs 목록에는 https://your.site.com/oauth/callback을 추가해주세요.
Settings에서 To App 메뉴를 선택한 후, Provisioning to App 섹션 우측의 Edit 버튼을 클릭하여 프로비저닝을 허용할 항목을 선택하고 Save 버튼을 클릭합니다.
하단의 Attribute Mappings 섹션에서 Swit 연동에 필수적인 매핑(Mapping) 필수 정보를 입력합니다.