SCIM(System for Cross-domain Identity Management) 공개 표준을 사용하여 다음 작업을 자동으로 수행할 수 있습니다.

• 사용자 생성.
• 사용자 차단.
• 사용자 다시 추가(SCIM 아이덴티티 재활성화).

GitLab 내부 SCIM API는 RFC7644 프로토콜의 일부를 구현합니다.

GitLab.com 사용자라면 GitLab.com 그룹에 대한 SCIM 구성을 참고합니다.

GitLab 구성#

사전 요구 사항:

• SAML 싱글 사인온 구성.
• 관리자 접근 권한.

GitLab SCIM을 구성하려면 다음 단계를 수행합니다.

1. 오른쪽 상단 모서리에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. SCIM Token 섹션을 펼치고 Generate a SCIM token을 선택합니다.
4. ID 공급자 구성을 위해 다음을 저장합니다.
   • Your SCIM token 필드의 토큰.
   • SCIM API endpoint URL 필드의 URL.

ID 공급자 구성#

GitLab은 여러 ID 공급자와 함께 SCIM을 지원합니다. 다른 ID 공급자도 GitLab과 동작할 수 있지만, 테스트되지 않았으며 지원 대상이 아닙니다. 지원되지 않는 공급자에 대한 도움이 필요하면 공급자에게 직접 문의합니다. GitLab 지원팀은 관련 로그 항목 검토를 지원할 수 있습니다.

Okta 구성#

Okta에 대해 싱글 사인온을 설정하는 과정에서 만든 SAML 애플리케이션을 SCIM용으로 설정해야 합니다.

사전 요구 사항:

• Okta Lifecycle Management 제품을 사용해야 합니다. Okta에서 SCIM을 사용하려면 이 제품 티어가 필요합니다.
• SCIM을 위해 GitLab이 구성되어 있어야 합니다.
• Okta 설정 참고 사항에 설명된 대로 Okta용 SAML 애플리케이션이 설정되어 있어야 합니다.
• Okta SAML 설정이 구성 단계, 특히 NameID 구성과 일치해야 합니다.

Okta를 SCIM용으로 구성하려면 다음 단계를 수행합니다.

1. Okta에 로그인합니다.
2. 오른쪽 상단 모서리에서 Admin을 선택합니다. 이 버튼은 Admin 영역에서는 표시되지 않습니다.
3. Application 탭에서 Browse App Catalog를 선택합니다.
4. GitLab 애플리케이션을 찾아 선택합니다.
5. GitLab 애플리케이션 개요 페이지에서 Add Integration을 선택합니다.
6. Application Visibility에서 두 체크박스를 모두 선택합니다. GitLab 애플리케이션은 SAML 인증을 지원하지 않으므로 아이콘이 사용자에게 표시되지 않아야 합니다.
7. Done을 선택하여 애플리케이션 추가를 완료합니다.
8. Provisioning 탭에서 Configure API integration을 선택합니다.
9. Enable API integration을 선택합니다.
   • Base URL에는 GitLab SCIM 구성 페이지의 SCIM API endpoint URL에서 복사한 URL을 붙여 넣습니다.
   • API Token에는 GitLab SCIM 구성 페이지의 Your SCIM token에서 복사한 SCIM 토큰을 붙여 넣습니다.
10. 구성을 확인하려면 Test API Credentials를 선택합니다.
11. Save를 선택합니다.
12. API 통합 세부 정보를 저장하면 왼쪽에 새 설정 탭이 나타납니다. To App을 선택합니다.
13. Edit를 선택합니다.
14. Create Users와 Deactivate Users 양쪽의 Enable 체크박스를 선택합니다.
15. Save를 선택합니다.
16. Assignments 탭에서 사용자를 할당합니다. 할당된 사용자는 GitLab 그룹에서 생성되고 관리됩니다.

Microsoft Entra ID 구성#

사전 요구 사항:

• SCIM을 위해 GitLab이 구성되어 있어야 합니다.
• Microsoft Entra ID용 SAML 애플리케이션이 설정되어 있어야 합니다.

Azure Active Directory에 대해 싱글 사인온을 설정하는 과정에서 만든 SAML 애플리케이션을 SCIM용으로 설정해야 합니다. 예시는 예시 구성을 참고합니다.

Microsoft Entra ID를 구성할 때는 다음 항목을 구성합니다.

• SCIM을 위한 Microsoft Entra ID.
• 설정.
• 속성 매핑을 포함한 매핑.

SCIM을 위한 Microsoft Entra ID 구성#

1. 앱에서 Provisioning 탭으로 이동하여 Get started를 선택합니다.

2. Provisioning Mode를 Automatic으로 설정합니다.

3. 다음 값을 사용하여 Admin Credentials를 입력합니다.

   • Tenant URL 필드에는 GitLab의 SCIM API endpoint URL 값을 입력합니다.
   • Secret Token 필드에는 GitLab의 Your SCIM token 값을 입력합니다.

4. Test Connection을 선택합니다.

   테스트가 성공하면 구성을 저장합니다.

   테스트가 실패하면 문제 해결을 참고하여 해결을 시도합니다.

5. Save를 선택합니다.

저장하면 Mappings 및 Settings 섹션이 나타납니다.

매핑 구성#

그룹 동기화는 선택 사항입니다. 구성하려면 Mappings 섹션에서 먼저 그룹을 프로비저닝합니다.

1. Provision Microsoft Entra ID Groups를 선택합니다.

2. 속성 매핑 페이지에서 Enabled 토글을 켭니다.

3. Target Object Actions에서 Create, Update, Delete 체크박스를 선택합니다.

4. Attribute Mappings에서 첫 번째 속성을 다음과 같이 편집합니다.

   • source attribute는 displayName.
   • target attribute는 displayName.
   • matching precedence는 1.

5. Save를 선택합니다.

다음으로 사용자를 프로비저닝합니다.

1. Provision Microsoft Entra ID Users를 선택합니다.
2. Enabled 토글이 Yes로 설정되어 있는지 확인합니다.
3. 모든 Target Object Actions가 활성화되어 있는지 확인합니다.
4. Attribute Mappings에서 구성된 속성 매핑과 일치하도록 매핑을 구성합니다.
   1. 선택 사항. customappsso Attribute 칼럼에서 externalId를 찾아 삭제합니다.
   2. 첫 번째 속성을 다음과 같이 편집합니다.
      • Source attribute는 objectId.
      • Target attribute는 externalId.
      • Matching precedence는 1.
      • Apply this mapping은 Always로 설정
   3. 기존 customappsso 속성을 구성된 속성 매핑과 일치하도록 업데이트합니다.
   4. 속성 매핑 표에 없는 추가 속성은 삭제합니다. 삭제하지 않아도 문제가 발생하지는 않지만, GitLab은 해당 속성을 사용하지 않습니다.
5. 매핑 목록 아래에서 Show advanced options 체크박스를 선택합니다.
6. Edit attribute list for customappsso 링크를 선택합니다.
7. id가 기본 필수 필드이고 externalId도 필수인지 확인합니다.
8. Save를 선택하면 속성 매핑 구성 페이지로 돌아갑니다.
9. Attribute Mapping 구성 페이지를 닫으려면 오른쪽 상단 모서리에서 X를 선택합니다.

속성 매핑 구성#

SCIM을 위해 Entra ID를 구성하는 동안 속성 매핑을 구성합니다. 예시는 예시 구성을 참고합니다.

다음 표는 GitLab에 필요한 속성 매핑입니다.

각 속성 매핑은 다음으로 구성됩니다.

• 대상 속성에 해당하는 customappsso Attribute.
• 소스 속성에 해당하는 Microsoft Entra ID Attribute.
• 매핑 우선순위.

각 속성에 대해 다음 단계를 수행합니다.

1. 기존 속성을 편집하거나 새 속성을 추가합니다.
2. 드롭다운 목록에서 필요한 소스 및 대상 속성 매핑을 선택합니다.
3. Ok를 선택합니다.
4. Save를 선택합니다.

SAML 구성이 권장 SAML 설정과 다르면 매핑 속성을 선택하여 그에 맞게 수정합니다. externalId 대상 속성에 매핑하는 소스 속성은 SAML NameID에 사용되는 속성과 일치해야 합니다.

표에 없는 매핑은 Microsoft Entra ID 기본값을 사용합니다. 필수 속성 목록은 내부 인스턴스 SCIM API 문서를 참고합니다.

설정 구성#

Settings 섹션에서 다음 단계를 수행합니다.

1. 선택 사항. 필요하면 Send an email notification when a failure occurs 체크박스를 선택합니다.
2. 선택 사항. 필요하면 Prevent accidental deletion 체크박스를 선택합니다.
3. 필요하면 Save를 선택하여 모든 변경 사항이 저장되었는지 확인합니다.

매핑과 설정을 구성한 후 앱 개요 페이지로 돌아가 Start provisioning을 선택하면 GitLab에서 사용자의 자동 SCIM 프로비저닝이 시작됩니다.

접근 권한 제거#

ID 공급자에서 사용자를 제거하거나 비활성화하면 아이덴티티가 active: false로 표시되어 GitLab에서 사용자가 차단되며, SCIM 아이덴티티는 GitLab 사용자 계정에 연결된 상태로 유지됩니다.

SCIM으로 사용자를 디프로비저닝해도 연결된 SAML 아이덴티티는 제거되지 않습니다.

사용자 SCIM 아이덴티티를 업데이트하려면 GitLab 내부 SCIM API를 사용합니다.

접근 권한 재활성화#

SCIM으로 사용자가 제거되거나 비활성화된 후에는 해당 사용자를 SCIM ID 공급자에 추가하여 재활성화할 수 있습니다.

ID 공급자가 구성된 일정에 따라 동기화를 수행하면 사용자의 SCIM 아이덴티티가 재활성화되고 GitLab 인스턴스 접근이 복원됩니다. 디프로비저닝 중에도 연결된 SAML 아이덴티티가 유지되므로 사용자는 SSO로 즉시 로그인할 수 있습니다.

SCIM을 사용한 그룹 동기화#

히스토리

• GitLab 18.0에서 self_managed_scim_group_sync라는 기능 플래그와 함께 도입. 기본적으로 비활성화.
• GitLab 18.2에서 GitLab Self-Managed에 기본적으로 활성화.
• GitLab 18.6에서 일반 공개. 기능 플래그 self_managed_scim_group_sync 제거.

사용자 프로비저닝 외에도 SCIM을 사용하여 ID 공급자와 GitLab 사이의 그룹 멤버십을 동기화할 수 있습니다. 이 방법을 사용하면 ID 공급자의 그룹 멤버십을 기준으로 GitLab 그룹에서 사용자를 자동으로 추가하고 제거할 수 있습니다.

사전 요구 사항:

• SAML 그룹 링크를 먼저 구성해야 합니다.
• ID 공급자의 SAML 그룹 이름이 GitLab에 구성된 SAML 그룹 이름과 일치해야 합니다.

SCIM 그룹 동기화는 SAML 그룹 링크와 함께 동작하여 그룹 멤버십을 관리합니다. ID 공급자가 SCIM API로 그룹 멤버십 변경 사항을 전송하면, GitLab은 해당 SCIM 그룹과 연결된 SAML 그룹 링크가 있는 모든 GitLab 그룹에서 사용자 멤버십을 업데이트합니다.

SCIM은 단방향 프로토콜이며, 변경 사항은 ID 공급자에서 GitLab으로 전달됩니다. GitLab에서 SAML 그룹 링크를 추가하거나 제거하는 등 변경하더라도 ID 공급자는 SCIM으로 이러한 변경 사항을 감지할 수 없습니다.

SAML 그룹 링크와 SCIM 그룹 연결#

ID 공급자가 SCIM 그룹을 처음 프로비저닝하면(POST /Groups), GitLab은 SCIM 그룹 ID를 그룹 이름이 일치하는 모든 기존 SAML 그룹 링크와 연결합니다. 같은 그룹 이름으로 새 SAML 그룹 링크를 만들면, GitLab은 기존 SCIM 그룹 ID를 새 SAML 그룹 링크에 자동으로 상속합니다.

SAML 그룹 링크 삭제#

GitLab에서 SAML 그룹 링크를 삭제해도 해당 링크로 그룹에 속한 멤버는 그룹에 남습니다. 다만 그룹 링크가 제거되었으므로 SCIM은 더 이상 해당 그룹의 멤버십을 관리하지 않습니다. 필요하면 그룹에서 멤버를 제거할 수 있습니다.

SCIM 그룹과 연결된 SAML 그룹 링크를 모두 삭제하면 다음과 같이 동작합니다.

• GitLab은 해당 그룹의 SCIM 멤버십 캐시를 지웁니다.
• ID 공급자는 다음 동기화 주기에 404 Group not found 응답을 받습니다.

SCIM 그룹 동기화를 재개하려면 새 SAML 그룹 링크를 만들고 ID 공급자에서 해당 그룹의 SCIM 동기화를 트리거합니다.

ID 공급자에서 그룹 동기화 구성#

ID 공급자에서 그룹 동기화를 구성하는 자세한 지침은 공급자의 문서를 참고합니다. 예시는 다음과 같습니다.

• Okta Groups API
• Microsoft Entra ID (Azure AD) SCIM Groups
  • 기본적으로 displayName 소스 속성은 사용자 친화적인 이름을 가진 SAML 그룹 링크를 찾는 데 사용됩니다.
  • 다만 SAML 그룹 링크가 이름에 개체 ID를 사용한다면 소스 속성을 objectId로 업데이트해야 합니다.

Okta 애플리케이션 카탈로그의 표준 GitLab SCIM 애플리케이션은 그룹 동기화를 지원하지 않습니다. 대안으로 Okta와의 그룹 동기화를 위한 사용자 정의 SCIM 통합을 만들 수 있습니다. 자세한 내용은 이슈 582729를 참고합니다.

문제 해결#

SCIM 문제 해결 가이드를 참고합니다.

Footnotes

1. userPrincipalName 이 이메일 주소가 아니거나 전달 불가능한 경우 mail을 소스 속성으로 사용합니다. ↩

2. displayName 이 Firstname Lastname 형식과 일치하지 않는 경우 Join 표현식을 사용합니다. ↩

3. 이 항목은 직접 매핑이 아니라 표현식 매핑 유형입니다. Mapping type 드롭다운 목록에서 Expression을 선택합니다. ↩