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과 아이덴티티 제공자 간에 동기화됩니다.

내부 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.

아이덴티티 제공자 구성

다음 중 하나를 아이덴티티 제공자로 구성할 수 있습니다:

note
다른 제공자도 GitLab과 함께 작동할 수 있지만, 테스트되지 않았으며 지원되지 않습니다. 지원을 원하시면 제공자에게 연락해야 합니다. GitLab 지원팀은 관련 로그 항목을 검토하여 도와줄 수 있습니다.

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

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

사전 요구 사항:

단일 서명 설정 동안 생성된 SAML 애플리케이션은 Azure Active Directory를 위해 SCIM에 대해 설정되어야 합니다.
예시를 보려면 예시 구성을 참조하세요.

note
다음 지침에 따라 SCIM 프로비저닝을 정확하게 구성해야 합니다. 잘못 구성될 경우 사용자 프로비저닝 및 로그인에 문제가 발생할 수 있으며, 이는 해결하는 데 많은 노력이 필요합니다. 각 단계에서 문제가 발생하거나 질문이 있는 경우 GitLab 지원팀에 문의하세요.

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

  1. 앱에서 프로비저닝 탭으로 이동하여 시작하기를 선택합니다.
  2. 프로비저닝 모드를 자동으로 설정합니다.
  3. 다음 값을 사용하여 관리자 자격 증명을 완료합니다:
    • Tenant URL 필드를 위한 GitLab의 SCIM API endpoint URL.
    • Secret Token 필드를 위한 GitLab의 Your SCIM token.
  4. 연결 테스트를 선택합니다. 테스트가 성공하면 계속하기 전에 구성을 저장하거나 문제 해결 정보를 참조하세요.
  5. 저장을 선택합니다.

저장 후, 매핑 및 설정 섹션이 나타납니다.

매핑 구성

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

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

  2. 속성 매핑 페이지에서 Enabled 토글을 끕니다. SCIM 그룹 프로비저닝은 GitLab에서 지원되지 않습니다. 그룹 프로비저닝을 활성화해도 SCIM 사용자 프로비저닝에는 영향을 미치지 않지만, 혼란스럽고 오해의 소지가 있는 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. 속성 매핑에서 매핑을 구성하여 구성된 속성 매핑과 일치하게 합니다:
    1. 선택 사항. customappsso Attribute 열에서 externalId를 찾아 삭제합니다.
    2. 첫 번째 속성을 다음으로 편집합니다:
      • source attribute: objectId
      • target attribute: externalId
      • matching precedence: 1
    3. 기존의 customappsso 속성을 업데이트하여 구성된 속성 매핑과 일치하게 합니다.
    4. 다음 표에 없는 추가 속성을 삭제합니다. 삭제하지 않더라도 문제가 발생하지 않지만, GitLab은 해당 속성을 사용하지 않습니다.

  5. 매핑 목록 아래에서 고급 옵션 표시 체크박스를 선택합니다.

  6. customappsso에 대한 속성 목록 편집 링크를 선택합니다.

  7. id가 기본 및 필수 필드이며, externalId도 필수임을 확인합니다.

  8. 저장을 선택하여 속성 매핑 구성 페이지로 돌아갑니다.

  9. 오른쪽 상단 모서리에 있는 X를 클릭하여 속성 매핑 구성 페이지를 닫습니다.

설정 구성

설정 섹션에서:

  1. 선택 사항. 원할 경우 실패가 발생할 때 이메일 알림 전송 체크박스를 선택합니다.

  2. 선택 사항. 원할 경우 우발적인 삭제 방지 체크박스를 선택합니다.

  3. 필요하다면 저장을 선택하여 모든 변경사항이 저장되었는지 확인합니다.

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

경고: 한 번 동기화되면, id 및 externalId에 매핑된 필드를 변경하면 오류가 발생할 수 있습니다. 여기에는 프로비저닝 오류, 중복 사용자 등이 포함되며, 기존 사용자가 GitLab 그룹에 접근하지 못하게 할 수 있습니다.

속성 매핑 구성

주의: Microsoft가 Azure Active Directory에서 Entra ID 명명 체계로 전환하는 동안 사용자 인터페이스에서 불일치가 발생할 수 있습니다. 문제가 발생하면 문서의 이전 버전을 보거나 GitLab 지원팀에 문의할 수 있습니다.

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

다음 표는 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가 Firstname Lastname 형식과 일치하지 않는 경우 Join 표현식을 사용합니다.
  3. 이는 직접 매핑이 아닌 표현식 매핑 유형입니다. Mapping type 드롭다운 목록에서 Expression을 선택합니다.

각 속성 매핑은 다음과 같이 구성됩니다:

  • customappsso Attribute, 대상 속성에 해당합니다.
  • Microsoft Entra ID Attribute, 소스 속성에 해당합니다.
  • 일치하는 우선 순위가 있습니다.

각 속성에 대해:

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

SAML 구성가 권장 SAML 설정과 다를 경우, 매핑 속성을 선택하고 그에 따라 수정합니다. externalId 대상 속성과 매핑되는 소스 속성은 SAML NameID에 사용된 속성과 일치해야 합니다.

표에 나열되지 않은 매핑은 Microsoft Entra ID 기본값을 사용하세요. 필수 속성 목록은 내부 그룹 SCIM API 문서를 참조하세요.

Okta 구성

싱글 사인온을 위해 설정된 SAML 애플리케이션은 SCIM에 맞게 설정되어야 합니다.

전제 조건:

SCIM을 위해 Okta를 구성하려면:

  1. Okta에 로그인합니다.

  2. 오른쪽 상단 코너에서 Admin을 선택합니다. Admin 영역에서는 버튼이 보이지 않습니다.

  3. Application 탭에서 Browse App Catalog를 선택합니다.

  4. GitLab을 검색하여 GitLab 애플리케이션을 찾고 선택합니다.

  5. GitLab 애플리케이션 개요 페이지에서 Add를 선택합니다.

  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 그룹에서 생성 및 관리됩니다.

사용자 접근

동기화 과정에서 모든 신규 사용자:

  • GitLab 계정을 받습니다.
  • 초대 이메일을 통해 그룹에 환영받습니다. 이메일 확인을 검증된 도메인으로 생략할 수 있습니다.

다음 다이어그램은 SCIM 앱에 사용자를 추가할 때 발생하는 일을 설명합니다:

%%{init: { "fontFamily": "GitLab Sans" }}%% graph TD accTitle: SCIM 애플리케이션에 사용자 추가 accDescr: GitLab이 SCIM 아이디를 사용자가 있는지 여부를 결정하는 방법. 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번 시도 후에도 사용하지 않는 사용자 이름이 발견되지 않으면 사용자 이름에 무작위 문자열이 첨부됩니다.

다음 방문 시 새로운 사용자와 기존 사용자는 그룹에 다음과 같은 방법으로 접근할 수 있습니다:

  • ID 제공자의 대시보드를 통해.
  • 링크를 직접 방문하여.

역할 정보는 Group 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 사용자 계정을 삭제하지 않습니다.

%%{init: { "fontFamily": "GitLab Sans" }}%% graph TD accTitle: 사용자 탈프로비저닝 accDescr: SCIM 앱에서 사용자를 제거하면 GitLab 그룹에서도 제거되는 방법. 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에서 일반적으로 사용 가능. 기능 플래그 skip_saml_identity_destroy_during_scim_deprovision 제거됨.

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

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