GitLab.com 그룹을 위한 SCIM 구성

Tier: Premium, Ultimate Offering: GitLab.com

오픈 표준인 Cross-domain Identity Management(SCIM)을 사용하여 자동으로 다음을 수행할 수 있습니다.

  • 사용자 만들기
  • 사용자 제거 (SCIM 식별 정보 비활성화)
  • 사용자 재추가 (SCIM 식별 정보 재활성화)

GitLab SAML SSO SCIM은 사용자 업데이트를 지원하지 않습니다.

GitLab 그룹에 SCIM이 활성화되면 해당 그룹의 구성원은 GitLab과 식별 공급자 간에 동기화됩니다.

내부 GitLab 그룹 SCIM API는 RFC7644 프로토콜의 일부를 구현합니다. 식별 공급자는 내부 GitLab 그룹 SCIM API를 사용하여 SCIM 앱을 개발할 수 있습니다.

GitLab의 자체 관리형 SCIM 설정에 대해서는 자체 관리형 GitLab 인스턴스를 위한 SCIM 구성을 참조하세요.

GitLab 설정 구성

필수 사항:

GitLab SAML SSO SCIM을 구성하려면:

  1. 왼쪽 사이드 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > SAML SSO를 선택합니다.
  3. SCIM 토큰 생성을 선택합니다.
  4. 식별 공급자 구성을 위해 다음을 저장합니다:
    • Your SCIM token 필드에서 토큰
    • SCIM API endpoint URL 필드에서 URL

식별 공급자 구성

다음 중 하나를 식별 공급자로 구성할 수 있습니다.

참고: 다른 제공업체도 GitLab에서 작동할 수 있지만 테스트되지 않았으며 지원되지 않습니다. 지원이 필요한 경우 제공업체에 문의해야 합니다. 관련 로그 항목을 검토하여 GitLab 지원이 지원할 수 있습니다.

Microsoft Entra ID (이전 Azure Active Directory) 구성

  • 16.10에서 Microsoft Entra ID 용어로 업데이트되었습니다.

필수 사항:

Azure Active Directory를 위해 설정된 SAML 애플리케이션은 SCIM을 설정해야 합니다. 예시는 예시 구성에서 확인할 수 있습니다.

참고: 다음 지침에 정확히 따라야 합니다. 잘못 구성할 경우 사용자 프로비저닝과 로그인에 문제가 발생하여 해결하려면 많은 노력이 필요합니다. 어떤 단계에서 문제가 발생하거나 질문이 있으면 GitLab 지원팀에 문의하세요.

Microsoft Entra ID를 위해 SCIM 구성:

  1. 앱에서 Provisioning 탭으로 이동하고 Get started를 선택합니다.
  2. Provisioning Mode를 자동으로 설정합니다.
  3. 다음 값을 사용하여 Admin Credentials를 완료합니다:
    • GitLab의 SCIM API endpoint URL 필드에서 Tenant URL 필드 값을 사용합니다.
    • GitLab의 Your SCIM token 필드에서 Secret Token 필드 값을 사용합니다.
  4. Connection 테스트를 선택합니다. 테스트에 성공하면 계속하기 전에 설정을 저장하거나 문제 해결 정보를 확인하세요.
  5. 저장을 선택합니다.

저장한 후 Mappings 및 Settings 섹션이 나타납니다.

매핑 구성

Mappings 섹션에서 먼저 그룹을 프로비저닝합니다:

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

  2. Attribute Mapping 페이지에서 Enabled 토글을 끕니다. SCIM 그룹 프로비저닝은 GitLab에서 지원하지 않습니다. 그룹 프로비저닝을 계속 사용하면 Entra ID SCIM 프로비저닝 로그에 오류가 발생하여 혼동 및 오해를 일으킬 수 있습니다.

    참고: Provision Microsoft Entra ID Groups가 비활성화되어 있더라도 매핑 섹션이 “Enabled: Yes”로 표시될 수 있습니다. 이 동작은 무시해도 안전합니다.

  3. 저장을 선택합니다.

그다음, 사용자를 프로비저닝합니다:

  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로 설정합니다.
    3. 기존 customappsso 속성을 구성된 속성 매핑에 일치하도록 업데이트합니다.
    4. 다음 표에 없는 추가적인 속성을 삭제합니다. 삭제하지 않아도 문제가 발생하지는 않지만 GitLab은 해당 속성을 사용하지 않습니다.
  5. 매핑 목록 아래에서 Show advanced options 확인란을 선택합니다.
  6. Edit attribute list for customappsso 링크를 선택합니다.
  7. id가 기본 및 필수 필드이고 externalId도 필수 필드인지 확인합니다.
  8. 저장을 선택하여 속성 매핑 구성 페이지로 돌아갑니다.
  9. 오른쪽 상단의 X를 클릭하여 Attribute Mapping 구성 페이지를 닫습니다.

설정 구성

설정 섹션 내에서:

  1. 원하는 경우, 오류 발생 시 이메일 알림 보내기 확인란을 선택합니다.
  2. 원하는 경우, 우발적인 삭제 방지 확인란을 선택합니다.
  3. 필요한 경우, 모든 변경 사항이 저장되도록 저장을 선택합니다.

매핑 및 설정을 구성한 후, 응용 프로그램 개요 페이지로 돌아가 자동 SCIM 프로비저닝 시작을 선택하여 GitLab의 사용자에 대한 자동 SCIM 프로비저닝을 시작합니다.

경고: 동기화한 후에 id와 externalId로 매핑된 필드를 변경하면 오류가 발생할 수 있습니다. 이로인해 프로비저닝 오류, 중복 사용자가 발생하고 기존 사용자가 GitLab 그룹에 액세스하지 못할 수 있습니다.

속성 매핑 구성

참고: 마이크로소프트가 Azure Active Directory에서 Entra ID 네이밍 체계로 전환하는 동안 사용자 인터페이스에서 불일치가 발생할 수 있습니다. 문제가 있으면 이전 버전의 이 문서를 확인하거나 GitLab 지원팀에 문의할 수 있습니다.

SCIM을 위한 Microsoft Entra ID 구성 중에 속성 매핑을 구성합니다. 예를 들어 예제 구성을 참조하세요.

다음 표는 GitLab에서 필요한 속성 매핑을 제공합니다.

소스 속성 대상 속성 일치 우선 순위
objectId externalId 1
userPrincipalName 또는 mail 1 emails[type eq "work"].value  
mailNickname userName  
displayName 또는 Join(" ", [givenName], [surname]) 2 name.formatted  
Switch([IsSoftDeleted], , "False", "True", "True", "False") 3 active  
  1. `userPrincipalName`이 이메일 주소가 아니거나 전달할 수 없는 경우 소스 속성으로 `mail`을 사용합니다.
  2. `displayName`이 `이름 성`의 형식과 일치하지 않는 경우, `Join` 식을 사용하세요.
  3. 이것은 직접적인 매핑이 아닌 표현 매핑 유형입니다. 드롭다운 목록에서 매핑 유형에서 Expression을 선택하세요.

각 속성 매핑에는 다음이 포함되어 있습니다:

  • customappsso 속성과 대상 속성이 일치합니다.
  • Microsoft Entra ID 속성과 소스 속성이 일치합니다.
  • 일치 우선 순위가 지정됩니다.

각 속성에 대해:

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

SAML 구성이 권장 SAML 설정과 다른 경우, 매핑 속성을 선택하고 해당 사항에 맞게 수정합니다. externalId 대상 속성에 매핑하는 소스 속성은 SAML NameID에 사용된 속성과 일치해야 합니다.

표에 나열되지 않은 경우, Microsoft Entra ID 기본값을 사용합니다. 필요한 속성 목록은 내부 그룹 SCIM API 문서를 참조하세요.

Okta 구성

Okta에서 단일 로그온 설정 중에 만든 SAML 응용 프로그램은 SCIM을 위해 설정되어야 합니다.

전제 조건:

  • Okta Lifecycle Management 제품을 사용해야 합니다. 이 제품 티어는 Okta에서 SCIM을 사용하려면 필수입니다.
  • GitLab가 구성되어 있어야 합니다.
  • Okta에 대한 SAML 응용 프로그램은 Okta 설정 참고에 설명된 대로 설정되어야 합니다.
  • Okta SAML 설정이 구성 단계와 정확히 일치해야 합니다. 특히 NameID 구성이 일치해야 합니다.

Okta의 SCIM 구성을 위해:

  1. Okta에 로그인합니다.
  2. 오른쪽 상단에서 관리자를 선택합니다. 이 버튼은 관리 영역에서는 표시되지 않습니다.
  3. 애플리케이션 탭에서 애플리케이션 카탈로그 탐색을 선택합니다.
  4. GitLab을 검색하고 GitLab 애플리케이션을 찾아 선택합니다.
  5. GitLab 애플리케이션 개요 페이지에서 추가를 선택합니다.
  6. 애플리케이션 표시 아래 두 개의 확인란 모두 선택합니다. 현재 GitLab 애플리케이션은 SAML 인증을 지원하지 않으므로 아이콘은 사용자에게 표시되지 않아야 합니다.
  7. 애플리케이션 추가를 완료하려면 완료를 선택합니다.
  8. 프로비저닝 탭에서 API 통합 구성을 선택합니다.
  9. API 통합 사용을 선택합니다.
    • 기본 URL에는 GitLab SCIM 구성 페이지에서 복사한 SCIM API 엔드포인트 URL을 붙여 넣습니다.
    • API 토큰에는 GitLab SCIM 구성 페이지에서 복사한 SCIM 토큰을 붙여 넣습니다.
  10. 구성을 검증하려면 API 자격 증명 테스트를 선택합니다.
  11. 저장을 선택합니다.
  12. API 통합 세부정보를 저장한 후, 왼쪽에 새로운 설정 탭이 나타납니다. To App을 선택합니다.
  13. 편집을 선택합니다.
  14. 사용자 생성과 사용자 비활성화 두 가지에 대한 활성화 확인란을 선택합니다.
  15. 저장을 선택합니다.
  16. 할당 탭에서 사용자를 할당합니다. 할당된 사용자는 GitLab 그룹에서 생성 및 관리됩니다.

사용자 액세스

동기화 프로세스 중에, 모든 새로운 사용자는 다음과 같은 일들이 있습니다:

다음 다이어그램은 사용자를 SCIM 앱에 추가할 때의 상황을 설명합니다:

graph TD A[SCIM 앱에 사용자 추가] -->|IdP가 사용자 정보를 GitLab에 보냄| B(GitLab: 이메일이 존재하는가?) B -->|아니오| C[GitLab이 SCIM ID로 사용자를 생성함] B -->|예| D(GitLab: 사용자가 그룹의 일부인가?) D -->|아니오| E(GitLab: SSO 강제가 활성화되었는가?) E -->|아니오| G E -->|예| F[GitLab이 메시지 반환:\n회원의 이메일 주소가 SAML 계정과 연결되지 않음] D -->|예| G[SCIM ID를 사용자에 연결함]

프로비저닝 중에:

  • GitLab 사용자 계정이 존재하는지 확인할 때 기본 및 보조 이메일이 고려됩니다.
  • 중복된 사용자 이름은 사용자 생성 시 1 접미사가 추가되어 처리됩니다. 예를 들어, test_user가 이미 존재하면 test_user1이 사용됩니다. 만약 test_user1이 이미 존재하면 GitLab은 사용되지 않은 사용자 이름을 찾기 위해 접미사를 증가시킵니다. 4번 시도한 후에도 사용되지 않은 사용자 이름을 찾지 못하면 무작위 문자열이 사용자 이름에 추가됩니다.

이후 방문 시, 새로운 사용자와 기존 사용자는 다음 중 하나를 통해 그룹에 액세스할 수 있습니다:

  • Identity provider의 대시보드를 통해서.
  • 직접 링크를 방문함으로써.

역할에 대한 정보는 그룹 SAML 페이지를 참조하세요.

GitLab 그룹을 위한 SCIM를 통해 생성된 사용자의 암호

GitLab은 모든 사용자 계정에 암호가 필요합니다. SCIM 프로비저닝을 통해 생성된 사용자들을 위해, GitLab은 자동으로 무작위 암호를 생성하며, 사용자들은 첫 번째 로그인 시 암호를 설정할 필요가 없습니다. GitLab이 그룹용 SCIM을 통해 생성된 사용자들에 대해 암호를 생성하는 방법에 대한 자세한 정보는 통합 인증 방법을 통해 생성된 사용자를 위한 생성된 암호을 참조하세요.

SCIM 및 SAML ID 연결

만약 그룹 SAML이 구성되었고 기존 GitLab.com 계정이 있다면 사용자는 자신의 SCIM 및 SAML ID를 연결할 수 있습니다. 동기화가 활성화되어 있는 경우 기존 사용자들을 위해 프로비저닝 오류가 발생할 수 있기 때문에 사용자들은 동기화가 활성화되기 전에 이 작업을 수행해야 합니다.

SCIM 및 SAML ID를 연결하려면:

  1. 기본 이메일 주소를 사용자 프로필 이메일 주소와 일치하도록 GitLab.com 사용자 계정을 업데이트합니다.
  2. SAML ID를 연결합니다.

액세스 제거

액세스 제공자에서 사용자를 제거하거나 비활성화하여 다음에 액세스를 제거할 수 있습니다:

  • 최상위 그룹.
  • 모든 하위 그룹 및 프로젝트.

액세스 제공자가 구성된 일정에 따라 동기화를 수행한 이후에 사용자의 멤버십이 박탈되며 액세스가 제거됩니다.

SCIM을 활성화하더라도 SAML ID가 없는 기존 사용자들은 자동으로 제거되지 않습니다.

참고: 비프로비전은 GitLab 사용자 계정을 삭제하지 않습니다.

graph TD A[SCIM 앱에서 사용자 제거] -->|IdP가 GitLab에 요청을 보냄| B(GitLab: 사용자가 그룹의 일부인가?) B -->|아니오| C[아무 것도 하지 않음] B -->|예| D[GitLab이 사용자를 GitLab 그룹에서 제거함]

액세스 재활성화

  • GitLab 16.0에서 플래그(skip_saml_identity_destroy_during_scim_deprovision)를 사용하여 개선되었습니다. 기본 설정은 비활성화 상태입니다.
  • GitLab 16.4부터 GA(일반 사용 가능)됩니다. skip_saml_identity_destroy_during_scim_deprovision 플래그가 제거되었습니다.

SCIM을 통해 사용자가 제거되거나 비활성화된 후, 해당 사용자를 SCIM 액세스 제공자에 추가함으로써 사용자를 다시 활성화할 수 있습니다.

액세스 제공자가 구성된 일정에 따라 동기화를 수행한 이후에 사용자의 SCIM ID가 재활성화되며 그룹 멤버십이 복구됩니다.