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 엔드포인트 URL 필드의 URL

식별 공급자 구성

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

참고: 다른 공급자는 GitLab과 작동할 수 있지만 테스트되지 않았으며 지원되지 않습니다. 지원을 받으려면 해당 공급자에 문의해야 합니다. GitLab 지원팀은 관련 로그 항목을 검토함으로써 지원할 수 있습니다.

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

  • GitLab 16.10에서 변경되어 GitLab에서 Microsoft Entra ID 용어 사용

필수 사항:

Azure Active Directory에서 설정된 SAML 애플리케이션이 SCIM으로 설정되어 있어야 합니다. 예시는 예시 구성을 참조하세요.

참고: 본 지침에 따라 SCIM 프로비저닝을 정확하게 구성해야 합니다. 잘못 구성하면 사용자 프로비저닝 및 로그인에 문제가 발생하며 해결하기 위해 많은 노력이 필요합니다. 어떠한 단계에 문제 또는 질문이 있으면 GitLab 지원팀에 문의하십시오.

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

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

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

매핑 구성

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

  1. Microsoft Entra ID 그룹 프로비저닝를 선택합니다.

  2. 속성 매핑 페이지에서 Enabled 토글을 끕니다. SCIM 그룹 프로비저닝은 GitLab에서 지원되지 않습니다. 그룹 프로비저닝을 사용하지 않아도 SCIM 사용자 프로비저닝에는 영향을 주지 않지만 Entra ID SCIM 프로비저닝 로그에 오류가 표시되어 혼동을 줄 수 있습니다.

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

  3. 저장을 선택합니다.

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

  1. Microsoft Entra ID 사용자 프로비저닝를 선택합니다.
  2. Enabled 토글이 Yes로 설정되어 있는지 확인합니다.
  3. 모든 대상 개체 작업이 활성화되어 있는지 확인합니다.
  4. 속성 매핑에서 구성된 속성 매핑과 일치하도록 매핑을 구성합니다:
    1. customappsso Attribute 열에서 externalId를 선택하여 선택합니다.
    2. 첫 번째 속성을 편집하여:
      • objectId의 출처 속성
      • externalId의 대상 속성
      • 1의 일치 우선순위
    3. 기존의 customappsso 속성을 구성된 속성 매핑과 일치하도록 업데이트합니다.
    4. 다음 표에 없는 추가 속성을 삭제합니다. 삭제하지 않아도 문제가 발생하지는 않지만 GitLab에서 해당 속성을 사용하지는 않습니다.
  5. 매핑 목록 아래에서 고급 옵션 표시 확인란을 선택합니다.
  6. customappsso에 대한 속성 목록 편집 링크를 선택합니다.
  7. id가 주 키이며 필수 필드인지, 그리고 externalId 역시 필수 필드인지 확인합니다.
  8. 저장을 선택하여 자동으로 SCIM 프로비저닝을 시작할 수 있게 됩니다.

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

속성 매핑 구성

note

Azure Active Directory에서 Entra ID 네이밍 체계로 전환하는 동안 사용자 인터페이스에 불일치가 있을 수 있습니다. 문제가 있는 경우 이전 버전의 문서를 확인하거나 GitLab 지원팀에 문의할 수 있습니다.

SCIM을 위한 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`이 `Firstname Lastname` 형식과 일치하지 않는 경우 `Join` 표현식을 사용하세요.
  3. 이것은 직접 매핑이 아닌 표현식 매핑 유형입니다. 매핑 유형 드롭다운 목록에서 표현식을 선택하세요.

각 속성 매핑은 다음을 포함합니다.

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

각 속성에 대해:

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

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

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

Okta 구성

Okta에서 단일 사인온 설정 중에 만들어진 SAML 애플리케이션은 SCIM으로 설정해야 합니다.

사전 요구 사항:

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에서 복사한 URL을 붙여넣습니다.
    • API 토큰에는 GitLab SCIM 구성 페이지의 SCIM 토큰에서 복사한 SCIM 토큰을 붙여넣습니다.
  10. 구성을 확인하려면 API 자격 증명 테스트를 선택하세요.
  11. 저장을 선택하세요.
  12. API 통합 세부 정보를 저장한 후 왼쪽에 새로운 설정 탭이 나타납니다. 앱에를 선택하세요.
  13. 편집을 선택하세요.
  14. 사용자 생성과 사용자 비활성화의 확인란을 선택하세요.
  15. 저장을 선택하세요.
  16. 할당 탭에서 사용자를 지정하세요. 지정된 사용자는 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번 시도한 후에도 사용 가능한 사용자 이름이 없으면 무작위 문자열이 사용자 이름에 추가됩니다.

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

  • Identity provider의 대시보드를 통해.
  • 직접 링크를 방문하여.

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

GitLab 그룹을 통해 SCIM을 사용하여 생성된 사용자의 암호

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

SCIM 및 SAML 신원 연결

만약 그룹 SAML이 구성되어 있고 기존의 GitLab.com 계정이 있다면, 사용자는 SCIM과 SAML 신원을 연결할 수 있습니다. 사용자는 동기화가 활성화된 상태에서 기존 사용자에 대한 프로비저닝 오류가 발생할 수 있으므로, 동기화가 켜기 전에 이 작업을 수행해야 합니다.

SCIM 및 SAML 신원을 연결하려면:

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

액세스 제거

신원 제공자에서 사용자의 액세스를 제거하려면 사용자를 삭제하거나 비활성화하여 다음에 대한 액세스를 제거합니다:

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

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

SCIM을 활성화해도, SAML 신원이 없는 기존 사용자는 자동으로 제거되지 않습니다.

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

%%{init: { "fontFamily": "GitLab Sans" }}%% graph TD accTitle: 사용자 비프로비저닝 accDescr: SCIM 앱에서 사용자를 제거하여 GitLab 그룹에서 사용자를 제거하는 방법. A[SCIM 앱에서 사용자 제거] -->|IdP가 GitLab에 요청을 보냄| B(GitLab: 사용자가 그룹의 일부인가요?) B -->|아니오| C[할 일 없음] B -->|예| D[GitLab이 사용자를 그룹에서 제거]

액세스 재활성화

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

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