SAML 그룹 동기화

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 15.1에서 Self-managed 인스턴스에 도입되었습니다.
caution
그룹 동기화 구성을 추가하거나 변경하면 매핑된 GitLab 그룹에서 사용자가 제거될 수 있습니다. 그룹 이름과 SAML 응답의 groups 목록 간에 불일치가 있는 경우 제거가 발생합니다. 변경하기 전에 SAML 응답에 groups 속성이 포함되어 있는지 및 AttributeValue 값이 GitLab의 SAML Group Name과 일치하는지 확인하거나, GitLab에서 모든 그룹을 제거하여 그룹 동기화를 비활성화합니다.

Azure를 사용하여 그룹 동기화 데모를 보려면 데모: SAML 그룹 동기화를 참조하세요.

SAML 그룹 링크 구성

SAML 그룹 동기화는 해당 그룹에 하나 이상의 SAML 그룹 링크가 있는 경우에만 해당 그룹을 관리합니다.

필수 조건:

  • Self-managed GitLab 인스턴스는 SAML 그룹 동기화를 구성해야 합니다. GitLab.com 인스턴스는 이미 SAML 그룹 동기화가 구성되어 있으며 추가 구성이 필요하지 않습니다.

SAML이 활성화되면 소유자 역할을 하는 사용자는 그룹 Settings > SAML Group Links에 새로운 메뉴 항목을 볼 수 있습니다.

  • 하나 이상의 SAML 그룹 링크를 구성하여 SAML 식별 공급자 그룹 이름을 GitLab 역할에 매핑할 수 있습니다.
  • SAML 식별 공급자 그룹의 구성원은 다음 SAML 로그인시 GitLab 그룹의 구성원으로 추가됩니다.
  • 사용자의 그룹 멤버십은 각 사용자가 SAML을 사용하여 로그인할 때마다 평가됩니다.
  • SAML 그룹 링크는 최상위 그룹 또는 하위 그룹에 대해 구성할 수 있습니다.
  • SAML 그룹 링크가 생성 후 제거되고 다음과 같은 경우:
    • 다른 SAML 그룹 링크가 구성되어 있으면 제거된 그룹에 속한 사용자 링크가 동기화 중에 그룹에서 자동으로 제거됩니다.
    • 다른 SAML 그룹 링크가 구성되어 있지 않으면 사용자는 동기화 중에 그룹에 남게 됩니다. 이러한 사용자는 그룹에서 수동으로 제거해야 합니다.

SAML 그룹을 링크하려면:

  1. SAML Group Name에 관련 saml:AttributeValue 값을 입력하십시오. 여기에 입력한 값은 SAML 응답에서 보낸 값과 정확히 일치해야 합니다. 일부 IdP의 경우 이는 친숙한 그룹 이름이 아닌 그룹 ID 또는 객체 ID (Azure AD)일 수 있습니다.
  2. Access Level에서 역할을 선택합니다.
  3. 저장을 선택합니다.
  4. 필요한 경우 추가 그룹 링크를 추가하려면 반복합니다.

SAML Group Links

하나의 사용자가 동일한 GitLab 그룹에 여러 SAML 그룹에 속한 경우 사용자는 그룹에서 가장 높은 역할을 받습니다. 예를 들어, 하나의 그룹은 게스트로 링크되고 다른 그룹은 메인테이너로 링크되면 두 그룹에 모두 속한 사용자는 메인테이너 역할을 받게 됩니다.

그룹 동기화로 인해 더 높은 역할을 받은 사용자는 직접 멤버십으로 표시됨. 더 낮거나 동일한 역할을 받은 사용자는 상속된 멤버십으로 표시됨.

API 사용

GitLab API를 사용하여 SAML 그룹 링크를 나열, 추가 및 삭제할 수 있습니다.

SAML 그룹 동기화 구성

note
SAML Group Sync를 사용하고 여러 GitLab 노드가 있는 경우 Sidekiq 노드에도 SAML 구성 블록을 반드시 포함해야 합니다. 이는 분산되었거나 고가용성 아키텍처의 경우입니다.
caution
GitLab에서 그룹 동기화를 활성화하기 전에 반드시 지시에 따라 사용자가 실수로 그룹에서 제거되는 것을 방지하십시오.

Self-managed GitLab instances의 경우 SAML 그룹 동기화를 구성하려면:

  1. SAML OmniAuth Provider를 구성하십시오.

  2. SAML 식별 공급자가 groups_attribute 설정의 값과 같은 이름의 속성 문을 보내도록하십시오. 예를 들어, 다음 공급자 구성 예제를 참조하십시오. /etc/gitlab/gitlab.rb: 

    gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name", # optional label for login button, defaults to "Saml",
    groups_attribute: 'Groups',
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      idp_sso_target_url: "https://login.example.com/idp",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

GitLab.com instances의 경우 SAML Group Sync를 구성하려면:

  1. GitLab.com 그룹을 위한 SAML SSO를 참조하십시오.
  2. SAML 식별 공급자가 Groups 또는 groups라는 이름의 속성 문을 보내도록하십시오.
note
SAML 응답의 Groups 또는 groups의 값은 그룹 이름 또는 ID가 될 수 있습니다. 예를 들어, Azure AD는 이름 대신 Azure 그룹 개체 ID를 보냅니다. SAML Group Links를 구성할 때 ID 값을 사용하십시오.
<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

http://schemas.microsoft.com/ws/2008/06/identity/claims/groups 와 같은 다른 속성 이름은 그룹의 소스로써 허용되지 않습니다.

SAML 식별 공급자의 설정에서 필요한 그룹 속성 이름을 구성하는 자세한 정보는 Azure AD 및 Okta에 대한 구성 예제를 참조하십시오.

Microsoft Azure Active Directory 통합

참고: Microsoft는 Azure Active Directory (AD)를 Microsoft Entra ID로 변경하기로 발표했습니다.

Azure AD는 최대 150개의 그룹을 그룹 클레임으로 보냅니다. 사용자가 150개 이상의 그룹 멤버인 경우, Azure AD는 SAML 응답에서 그룹 초과 클레임 속성을 보냅니다. 그런 다음 Microsoft Graph API를 사용하여 그룹 멤버십을 얻어야 합니다.

Microsoft Azure AD를 통합하려면:

  • Azure AD를 구성하여 GitLab이 Microsoft Graph API와 통신하도록합니다.
  • GitLab을 구성합니다.

GitLab 설정에서 Azure AD 필드로

GitLab 설정 Azure 필드
테넌트 ID 디렉터리(테넌트) ID
클라이언트 ID 응용 프로그램(클라이언트) ID
클라이언트 비밀 값(인증서 및 비밀 페이지에 있음)

Azure AD 구성

  1. Azure Portal에서 Microsoft Entra ID > 앱 등록 > 모든 앱으로 이동하여 GitLab SAML 애플리케이션을 선택합니다.
  2. 필수 항목에서 응용 프로그램(클라이언트) ID 및 디렉터리(테넌트) ID 값이 표시됩니다. GitLab 구성에 필요한 이 값들을 복사합니다.
  3. 왼쪽 내비게이션에서 인증서 및 비밀을 선택합니다.
  4. 클라이언트 비밀 탭에서 새 클라이언트 비밀을 선택합니다.
    1. 설명 텍스트 상자에 설명을 추가합니다.
    2. 만료 드롭다운 목록에서 자격 증명의 만료 날짜를 설정합니다. 비밀이 만료되면 GitLab 통합이 자격 증명을 업데이트 할 때까지 더 이상 작동하지 않습니다.
    3. 자격 증명을 생성하려면 추가를 선택합니다.
    4. 자격 증명의 값을 복사합니다. 이 값은 한 번만 표시되며 GitLab 구성에 필요합니다.
  5. 왼쪽 내비게이션에서 API 권한을 선택합니다.
  6. Microsoft Graph > 애플리케이션 권한을 선택합니다.
  7. GroupMember.Read.All 및 User.Read.All 확인란을 선택합니다.
  8. 저장하려면 권한 추가를 선택합니다.
  9. ****에 대해 **관리자 동의 부여**를 선택한 다음 확인 대화 상자에서 **예**를 선택합니다. 두 권한에 대한 **상태** 열은 ****에 대해 **부여됨**으로 변경되어야 합니다.

GitLab 구성

GitLab.com 그룹을 구성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 최상위 그룹을 찾습니다.
  2. 설정 > SAML SSO를 선택합니다.
  3. 그룹에 대한 SAML SSO를 구성합니다.
  4. Microsoft Azure 통합 섹션에서 이 그룹에서 Microsoft Azure 통합 사용 확인란을 선택합니다. 이 섹션은 그룹의 SAML SSO가 구성되고 활성화된 경우에만 표시됩니다.
  5. Azure Active Directory를 구성할 때 이전에 얻은 테넌트 ID, 클라이언트 ID 및 클라이언트 비밀을 입력합니다.
  6. 선택 사항. 미국 정부용 Azure AD 또는 Azure AD China를 사용하는 경우 해당 로그인 API 엔드포인트 및 Graph API 엔드포인트를 입력합니다. 대부분의 조직에서는 기본값이 작동합니다.
  7. 변경 사항 저장을 선택합니다.

자체 관리형을 위한 구성:

  1. 인스턴스에 대해 SAML SSO를 구성합니다.
  2. 왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
  3. 설정 > 일반을 선택합니다.
  4. Microsoft Azure 통합 섹션에서 이 그룹에서 Microsoft Azure 통합 사용 확인란을 선택합니다.
  5. Azure Active Directory를 구성할 때 이전에 얻은 테넌트 ID, 클라이언트 ID 및 클라이언트 비밀을 입력합니다.
  6. 선택 사항. 미국 정부용 Azure AD 또는 Azure AD China를 사용하는 경우 해당 로그인 API 엔드포인트 및 Graph API 엔드포인트를 입력합니다. 대부분의 조직에서는 기본값이 작동합니다.
  7. 변경 사항 저장을 선택합니다.

이 구성을 통해 사용자가 SAML 및 Azure에 그룹 초과 클레임이 응답으로 전송되면, GitLab은 Microsoft Graph API를 호출하여 사용자의 그룹 멤버십을 검색하고 그런 다음 GitLab 그룹 멤버십은 SAML 그룹 링크에 따라 업데이트됩니다.

글로벌 SAML 그룹 멤버십 잠금

상세정보: 티어: 프리미엄, 얼티밋 오퍼링: 자체 관리, GitLab 전용

GitLab 관리자는 글로벌 SAML 그룹 멤버십 잠금을 사용하여 SAML 그룹 링크와 동기화된 하위 그룹으로의 새 멤버 초대를 방지할 수 있습니다.

글로벌 그룹 멤버십 잠금은 SAML 그룹 링크 동기화가 구성된 최상위 그룹의 하위 그룹에만 적용됩니다. SAML 그룹 링크 동기화가 구성된 최상위 그룹의 멤버십을 수정할 수 없습니다.

글로벌 그룹 멤버십 잠금이 활성화된 경우:

  • 관리자만 모든 그룹의 멤버십과 액세스 수준을 관리할 수 있습니다.
  • 사용자는 다음을 할 수 없습니다:
    • 프로젝트를 다른 그룹과 공유합니다.
    • 그룹에서 프로젝트에 멤버를 초대합니다.

글로벌 그룹 멤버십 잠금을 활성화하려면:

  1. 자체 관리형 GitLab 인스턴스에 대해 SAML을 구성합니다.
  2. 왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
  3. 설정 > 일반을 선택합니다.
  4. 가시성 및 액세스 제어 섹션을 확장합니다.
  5. SAML 그룹 링크 동기화를위한 멤버십 잠금이 선택되어 있는지 확인합니다.

자동 멤버 제거

그룹 동기화 후 매핑된 SAML 그룹의 멤버가 아닌 사용자는 그룹에서 제거됩니다. GitLab.com에서 최상위 그룹의 사용자는 제거되는 대신 기본 멤버십 역할이 할당됩니다.

예를 들어, 다음 다이어그램에서:

  • Alex Garcia가 GitLab에 서명하고 있지 않아 SAML 그룹 C에 속하지 않기 때문에 GitLab 그룹 C에서 제거됩니다.
  • Sidney Jones는 SAML 그룹 C에 속하지만 아직 로그인하지 않았기 때문에 GitLab 그룹 C에 추가되지 않습니다.
graph TB subgraph SAML 사용자 SAMLUserA[Sidney Jones] SAMLUserB[Zhang Wei] SAMLUserC[Alex Garcia] SAMLUserD[Charlie Smith] end subgraph SAML 그룹 SAMLGroupA["그룹 A"] --> SAMLGroupB["그룹 B"] SAMLGroupA --> SAMLGroupC["그룹 C"] SAMLGroupA --> SAMLGroupD["그룹 D"] end SAMLGroupB --> |멤버|SAMLUserA SAMLGroupB --> |멤버|SAMLUserB SAMLGroupC --> |멤버|SAMLUserA SAMLGroupC --> |멤버|SAMLUserB SAMLGroupD --> |멤버|SAMLUserD SAMLGroupD --> |멤버|SAMLUserC
graph TB subgraph GitLab 사용자 GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab 그룹 GitLabGroupA["그룹 A (SAML 구성됨)"] --> GitLabGroupB["그룹 B (SAML 그룹 링크 구성되지 않음)"] GitLabGroupA --> GitLabGroupC["그룹 C (SAML 그룹 링크 구성됨)"] GitLabGroupA --> GitLabGroupD["그룹 D (SAML 그룹 링크 구성됨)"] end GitLabGroupB --> |멤버|GitLabUserA GitLabGroupC --> |멤버|GitLabUserB GitLabGroupC --> |멤버|GitLabUserC GitLabGroupD --> |멤버|GitLabUserC GitLabGroupD --> |멤버|GitLabUserD
graph TB subgraph GitLab 사용자 GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph Alex Garcia 서명 후의 GitLab 그룹 GitLabGroupA[그룹 A] GitLabGroupA["그룹 A (SAML 구성됨)"] --> GitLabGroupB["그룹 B (SAML 그룹 링크 구성되지 않음)"] GitLabGroupA --> GitLabGroupC["그룹 C (SAML 그룹 링크 구성됨)"] GitLabGroupA --> GitLabGroupD["그룹 D (SAML 그룹 링크 구성됨)"] end GitLabGroupB --> |멤버|GitLabUserA GitLabGroupC --> |멤버|GitLabUserB GitLabGroupD --> |멤버|GitLabUserC GitLabGroupD --> |멤버|GitLabUserD

여러 SAML 그룹에 속한 사용자가 GitLab 그룹에서 자동으로 제거됨

SAML을 사용하여 Azure AD를 사용하는 경우, 조직의 사용자 중 150개 이상의 그룹에 속한 사용자가 SAML 그룹 동기화를 사용하는 경우 해당 사용자의 그룹 멤버십이 손실될 수 있습니다. 자세한 내용은 Microsoft Group overages를 참조하십시오.

GitLab에는 150개 이상의 그룹에 속한 사용자가 있는 조직을 위해 SAML 그룹 동기화를 가능하게 하는 Microsoft Azure Active Directory 통합이 있습니다. 이 통합은 모든 사용자 멤버십을 얻기 위해 Microsoft Graph API를 사용하며 150개의 그룹으로 제한되지 않습니다.

그렇지 않으면 이 문제를 해결하기 위해 그룹 클레임을 응용 프로그램에 할당된 그룹 옵션으로 변경함으로써 문제를 해결할 수 있습니다.

그룹 클레임 관리.