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 그룹 이름과 일치하는지 확인하거나, GitLab에서 모든 그룹이 제거되어 그룹 동기화가 비활성화되도록 합니다.


Azure를 사용한 그룹 동기화 데모는 그룹 동기화 데모: SAML 그룹 동기화를 참조하세요.

SAML 그룹 링크 구성

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

사전 요구 사항:

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

SAML이 활성화되면 소유자 역할을 가진 사용자는 그룹의 설정 > SAML 그룹 링크에서 새 메뉴 항목을 볼 수 있습니다.

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

SAML 그룹을 링크하려면:

  1. SAML 그룹 이름에 relevand saml:AttributeValue의 값을 입력하십시오. 여기에 입력된 값은 SAML 응답으로 전송된 값과 정확히 일치해야 합니다. 일부 IdP에서는 친숙한 그룹 이름 대신에 그룹 ID 또는 객체 ID (Azure AD)일 수 있습니다.
  2. 액세스 레벨에서 역할을 선택하십시오.
  3. 저장을 선택하십시오.
  4. 필요한 경우 추가 그룹 링크를 추가하려면 반복합니다.

SAML Group Links

만약 사용자가 동일한 GitLab 그룹에 여러 SAML 그룹의 구성원인 경우, 사용자는 그룹 중 가장 높은 역할을 받습니다. 예를 들어, 하나의 그룹이 게스트로 연결되고 다른 그룹이 Maintainer로 연결되면 두 그룹에 속한 사용자는 Maintainer 역할을 받습니다.

그룹 동기화로 인해 부여받은:

  • 더 높은 역할은 그룹의 직접 회원으로 표시됩니다.
  • 낮거나 동일한 역할은 그룹의 상속된 회원으로 표시됩니다.

API 사용

디렉터리, 추가, 삭제를 위해 GitLab API를 사용할 수 있습니다.

SAML 그룹 동기화 구성

note
Self-managed GitLab 인스턴스에서 SAML 그룹 동기화를 사용하고 여러 GitLab 노드가 있다면, SAML 구성 블록을 레일 애플리케이션 노드뿐 아니라 모든 Sidekiq 노드에 포함해야 합니다. 예를 들어 분산 또는 고가용성 아키텍처에서 사용하는 경우입니다.
caution
GitLab에서 그룹 동기화를 활성화하기 전에 반드시 이 지침을 엄격히 따르세요. GitLab 그룹에서 실수로 사용자가 제거되는 것을 방지하기 위한 것입니다.

Self-managed GitLab 인스턴스용 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 인스턴스용 SAML 그룹 동기화 구성 방법:

  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 통합

note
Microsoft는 Azure Active Directory (AD)가 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
클라이언트 시크릿 값(Certificates & Secrets 페이지에서)

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. 애플리케이션_이름에 대한 관리자 동의 부여를 선택한 후 확인 대화상자에서 예를 선택합니다. 두 권한에 대한 상태 열은 관리가 <application_name>에 대해 부여됨과 함께 녹색 확인 표시로 변경됩니다.

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를 사용하는 경우 적절한 로그인 API 엔드포인트 및 그래프 API 엔드포인트를 입력합니다. 대부분의 조직에서는 기본 값이 작동합니다.
  7. 변경 사항 저장을 선택합니다.

자체 호스팅하는 경우:

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

이 구성으로 사용자가 SAML로 로그인하고 Azure가 응답에 그룹 초과 클레임을 보내면, GitLab은 그룹 동기화 작업을 시작하여 Microsoft Graph API를 호출하고 사용자의 그룹 멤버십을 검색합니다. 그런 다음 GitLab 그룹 멤버십은 SAML 그룹 링크에 따라 업데이트됩니다.

전역 SAML 그룹 멤버십 잠금

Tier: Premium, Ultimate Offering: 자체 호스팅, GitLab 전담

GitLab 15.10에서 도입되었습니다.

GitLab 관리자는 전역 SAML 그룹 멤버십 잠금을 사용하여 그룹 멤버가 멤버십이 동기화된 하위 그룹에 새 멤버를 초대하는 것을 방지할 수 있습니다.

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

전역 그룹 멤버십 잠금이 활성화되면:

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

전역 그룹 멤버십 잠금을 활성화하려면:

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

자동 멤버 제거

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

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

  • Alex Garcia는 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 그룹에서 제거됨

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

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

그렇지 않은 경우, 이 문제를 해결하기 위해 그룹 클레임을 애플리케이션에 할당된 그룹 옵션으로 변경함으로써 문제를 해결할 수 있습니다.

그룹 클레임 관리.