GitLab.com 그룹용 SCIM 구성

Tier: Premium, Ultimate Offering: GitLab.com

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

  • 사용자 생성
  • 사용자 제거 (SCIM ID 비활성화)
  • 사용자 재추가 (SCIM ID 재활성화)

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

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

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

GitLab Self-Managed에서 SCIM을 설정하려면, Self-Managed형 GitLab 인스턴스용 SCIM 구성을 참조하세요.

GitLab 구성

전제 조건:

GitLab SAML SSO SCIM을 구성하려면:

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

ID 공급자 구성

다음 중 하나를 ID 공급자로 구성할 수 있습니다:

note
다른 공급업체는 GitLab과 함께 작동할 수 있지만 테스트되지 않았으며 지원되지 않습니다. 지원이 필요한 경우 해당 공급업체에 문의해야 합니다. GitLab 지원팀은 관련 로그 항목을 검토하여 지원할 수 있습니다.

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

  • GitLab 16.10에서 변경됨으로 Microsoft Entra ID 용어로 변경.

전제 조건:

Azure Active Directory에 대한 단일 로그인 구성 설정 중에 작성된 SAML 애플리케이션은 SCIM에 대해 설정되어 있어야 합니다. 예시는 예시 구성을 참조하세요.

note
다음 지시사항에 정확히 따라 SCIM 프로비저닝을 구성해야 합니다. 잘못 구성하면 사용자 프로비저닝 및 로그인에 문제가 발생하며 해결하는 데 많은 노력이 필요합니다. 문제가 발생하거나 질문이 있는 경우 GitLab 지원팀에 문의하세요.

Microsoft Entra ID를 SCIM으로 구성하려면:

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

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

Mappings 구성

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

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

  2. Attribute Mapping 페이지에서 Enabled 토글을 끕니다. SCIM 그룹 프로비저닝은 GitLab에서 지원되지 않습니다. 그룹 프로비저닝을 계속 활성화해 두면 Entra ID SCIM 프로비저닝 로그에 오류가 발생할 수 있으며 혼란스럽고 오해를 일으킬 수 있습니다.

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

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

  1. Provision Microsoft Entra ID Users를 선택합니다.
  2. Enabled 토글이 Yes로 설정되어 있는지 확인합니다.
  3. 모든 Target Object Actions이 활성화되어 있는지 확인합니다.
  4. Attribute Mappings 아래에서 구성된 속성 매핑을 일치시키기 위해 매핑을 구성합니다:
    1. 커스텀 앱 SSO 속성 열에서 externalId를 찾아 삭제합니다(선택 사항).
    2. 첫 번째 속성을 편집하여:
      • source attribute를 objectId로
      • target attribute를 externalId로
      • matching precedence를 1로 설정합니다.
    3. 기존의 customappsso 속성을 업데이트하여 구성된 속성 매핑을 일치시킵니다.
    4. 다음 표에 나와있지 않은 추가적인 속성은 삭제합니다. 삭제하지 않아도 문제를 일으키지는 않지만 GitLab은 해당 속성을 사용하지 않습니다.
  5. 매핑 디렉터리 아래에서 고급 옵션 표시 체크박스를 선택합니다.
  6. customappsso에 대한 속성 디렉터리 편집 링크를 선택합니다.
  7. id가 기본 및 필수 필드이고 externalId도 필수 필드인지 확인합니다.
  8. Save를 선택하여 속성 매핑 구성 페이지로 돌아갑니다.
  9. 오른쪽 상단의 X를 클릭하여 Attribute Mapping 구성 페이지를 닫습니다.

설정 구성

Settings 섹션에서:

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

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

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

속성 매핑 구성

note
Microsoft은 Azure Active Directory에서 Entra ID로의 네이밍 스키마 전환 중에 사용자 인터페이스에서 일관성이 없을 수 있습니다. 문제가 있는 경우 더 오래된 버전의 문서를 확인하거나 GitLab 지원팀에 문의하세요.

Entra ID용 SCIM을 구성하는 동안 속성 매핑을 구성합니다. 예시는 예시 구성을 참조하세요.

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

소스 속성 대상 속성 일치 우선 순위
objectId externalId 1
userPrincipalName OR mail 1 emails[type eq "work"].value  
mailNickname userName  
displayName OR Join(" ", [givenName], [surname]) 2 name.formatted  
Switch([IsSoftDeleted], , "False", "True", "True", "False") 3 active  

사용자마다 각 속성 매핑에는:

  • customappsso 속성: 대상 속성에 대응합니다.
  • Microsoft Entra ID 속성: 소스 속성에 대응합니다.
  • 일치 우선 순위가 있습니다.

각 속성에 대해:

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

만일 SAML 구성이 권장된 SAML 설정과 다르다면, 매핑 속성을 선택하고 그에 맞게 수정합니다. externalId에 매핑한 소스 속성은 SAML NameID에 사용된 속성과 일치해야 합니다.

만일 테이블에 나열되지 않은 매핑이 있는 경우, Microsoft Entra ID 기본 설정을 사용합니다. 필요한 속성 디렉터리은 내부 그룹 SCIM API 문서를 참조하세요.

Okta 구성

단일 사인온 설정 중에 생성된 SAML 애플리케이션을 Okta용으로 SCIM으로 설정해야 합니다.

입력 조건:

Okta를 SCIM으로 구성하려면:

  1. Okta에 로그인합니다.
  2. 오른쪽 상단에서 관리자를 선택합니다. 이 버튼은 관리 영역에서는 표시되지 않습니다.
  3. 애플리케이션 탭에서 앱 카탈로그 검색을 선택합니다.
  4. GitLab을 검색하여 GitLab 애플리케이션을 찾고 선택합니다.
  5. GitLab 애플리케이션 개요 페이지에서 추가를 선택합니다.
  6. 애플리케이션 가시성 아래에서 두 개의 확인란을 모두 선택합니다. 현재 GitLab 애플리케이션은 SAML 인증을 지원하지 않으므로 사용자에게 아이콘이 표시되지 않아야 합니다.
  7. 애플리케이션 추가를 마치려면 완료를 선택합니다.
  8. Provisioning 탭에서 API 통합 구성을 선택합니다.
  9. API 통합 활성화를 선택합니다.
    • 기본 URL에는 GitLab SCIM 구성 페이지의 SCIM API 엔드포인트 URL에서 복사한 URL을 붙여넣습니다.
    • API 토큰에는 GitLab SCIM 구성 페이지의 당신의 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 식별자로 사용자 생성] B -->|예| D(GitLab: 사용자가 그룹의 구성원입니까?) D -->|아니요| E(GitLab: SSO 강제가 활성화되어 있습니까?) E -->|아니요| G E -->|예| F[GitLab이 메시지를 다시 보냄:\n멤버의 이메일 주소는 SAML 계정에 연결되지 않았습니다] D -->|예| G[SCIM 식별자를 사용자에게 연결]

프로비저닝 중:

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

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

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

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

GitLab 그룹용 SCIM 프로비저닝을 통해 생성된 사용자의 비밀번호

모든 사용자 계정에 비밀번호가 필요합니다. SCIM 프로비저닝을 사용하여 생성된 사용자의 경우, GitLab은 자동으로 랜덤한 비밀번호를 생성하며, 사용자는 첫 번째 로그인 시 비밀번호를 설정할 필요가 없습니다. GitLab 그룹용 SCIM 프로비저닝을 통해 생성된 사용자의 비밀번호에 대한 자세한 정보는 통합 인증 방법으로 생성된 사용자의 생성된 비밀번호를 참조하십시오.

SCIM 및 SAML 식별자 연결

그룹 SAML이 구성되어 있고 기존 GitLab.com 계정이 있는 경우, 사용자는 SCIM 및 SAML 식별자를 연결할 수 있습니다. 동기화가 활성화된 상태에서 기존 사용자에 대해 프로비저닝 오류가 발생할 수 있으므로 사용자는 이를 수행하기 전에 이를 수행해야 합니다.

SCIM 및 SAML 식별자를 연결하려면:

  1. GitLab.com 사용자 계정의 기본 이메일 주소를 신원 제공자의 사용자 프로필 이메일 주소와 일치하도록 업데이트합니다.
  2. SAML 식별자를 연결합니다.

액세스 제거

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

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

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

SCIM을 활성화해도 SAML 식별자가 없는 기존 사용자는 자동으로 제거되지 않습니다.

note
비프로비저닝은 GitLab 사용자 계정을 삭제하지 않습니다.
graph TD A[SCIM 앱에서 사용자 제거] -->|IdP가 GitLab에 요청을 보냄| B(GitLab: 사용자가 그룹의 구성원입니까?) B -->|아니요| C[할 일 없음] B -->|예| D[GitLab이 그룹에서 사용자 제거]

액세스 재활성화

SCIM을 통해 사용자를 제거하거나 비활성화한 후, 해당 사용자를 SCIM 식별자 제공자에 추가하여 사용자를 재활성화할 수 있습니다.

신원 제공자가 구성된 일정에 따라 동기화를 수행한 후, 사용자의 SCIM 식별자가 다시 활성화되고 그룹 멤버십이 복원됩니다.