SAML 그룹 동기화

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • GitLab 15.1에서 자체 관리 인스턴스에 도입되었습니다.
caution
그룹 동기화 구성을 추가하거나 변경하면 매핑된 GitLab 그룹에서 사용자가 제거될 수 있습니다.

사용자 제거는 그룹 이름과 SAML 응답의 groups 목록 간에 불일치가 있을 때 발생합니다.

변경을 진행하기 전에 SAML 응답이 groups 속성을 포함하고
AttributeValue 값이 GitLab의 SAML 그룹 이름과 일치하거나,
그룹 동기화를 비활성화하기 위해 GitLab에서 모든 그룹이 제거되었는지 확인하세요.


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

SAML 그룹 링크 구성

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

Prerequisites:

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

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

  • 하나 이상의 SAML 그룹 링크를 구성하여 SAML ID 공급자(IdP) 그룹 이름을 GitLab 역할에 매핑할 수 있습니다.
  • SAML IdP 그룹의 구성원은 다음 SAML 로그인 시 GitLab 그룹의 구성원으로 추가됩니다.
  • 사용자가 SAML을 사용하여 로그인할 때마다 그룹 구성원 자격이 평가됩니다.
  • SAML 그룹 링크는 최상위 그룹 또는 하위 그룹에 대해 구성할 수 있습니다.
  • SAML 그룹 링크가 생성된 후 제거되는 경우:
    • 다른 SAML 그룹 링크가 구성되어 있는 경우, 제거된 그룹 링크에 있던 사용자는 동기화 중 그룹에서 자동으로 제거됩니다.
    • 다른 SAML 그룹 링크가 구성되어 있지 않은 경우, 사용자는 동기화 중 그룹에 남아 있으며, 해당 사용자는 수동으로 그룹에서 제거해야 합니다.

SAML 그룹을 연결하려면:

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

SAML 그룹 링크

여러 SAML IdP가 있는 자체 관리 GitLab

사용자가 로그인할 때 GitLab은:

  • 구성된 모든 SAML 그룹 링크를 확인합니다.
  • 사용자가 여러 IdP에 걸쳐 소속된 SAML 그룹에 따라 해당 사용자를 해당 GitLab 그룹에 추가합니다.

GitLab의 그룹 링크 매핑은 특정 IdP에 묶여 있지 않으므로 모든 SAML IdP가 SAML 응답에 그룹 속성을 포함하도록 구성해야 합니다. 이는 GitLab이 로그인에 사용된 IdP에 관계없이 SAML 응답의 그룹을 일치시킬 수 있도록 합니다.

예를 들어, 두 개의 IdP인 SAML1과 SAML2가 있습니다.

GitLab의 특정 그룹에서 두 개의 그룹 링크를 구성했습니다:

  • gtlb-owner => Owner role.
  • gtlb-dev => Developer role.

SAML1에서는 사용자가 gtlb-owner의 구성원이지만 gtlb-dev는 아닙니다.

SAML2에서는 사용자가 gtlb-dev의 구성원이지만 gtlb-owner는 아닙니다.

사용자가 SAML1로 그룹에 로그인할 때, SAML 응답은 사용자가 gtlb-owner의 구성원임을 보여주므로 GitLab은 해당 그룹에서 사용자의 역할을 Owner로 설정합니다.

그런 다음 사용자는 로그아웃하고 SAML2로 그룹에 다시 로그인합니다. SAML 응답은 사용자가 gtlb-dev의 구성원임을 보여주므로 GitLab은 해당 그룹에서 사용자의 역할을 Developer로 설정합니다.

이제 이전 예제를 변경하여 사용자가 SAML2에서 gtlb-owner 또는 gtlb-dev의 구성원이 아닌 경우로 가정해 보겠습니다.

  • 사용자가 SAML1로 그룹에 로그인할 때 그룹에서 Owner 역할을 부여받습니다.
  • 사용자가 SAML2로 로그인할 때, 사용자는 구성된 그룹 링크의 구성원이 아니므로 그룹에서 제거됩니다.

역할 충돌 해결하기

여러 매핑된 SAML 그룹의 멤버

사용자가 동일한 GitLab 그룹에 매핑된 여러 SAML 그룹의 멤버인 경우,

사용자는 그룹에서 가장 높은 역할을 부여받습니다. 예를 들어, 하나의 그룹이 Guest로 연결되고 다른 그룹이 Maintainer로 연결된 경우, 두 그룹 모두의 사용자는 Maintainer 역할을 부여받습니다.

부모 그룹 역할이 자식 그룹보다 높음

부여된 사용자:

  • Group Sync로 더 높은 역할을 부여받은 경우 해당 그룹의 직접 멤버십으로 표시됩니다.
  • Group Sync로 더 낮거나 동일한 역할을 부여받은 경우 해당 그룹의 상속된 멤버십으로 표시됩니다.

API 사용하기

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

SAML 그룹 동기화 구성

참고: SAML 그룹 동기화를 사용하고 여러 GitLab 노드가 있는 경우, 예를 들어 분산 또는 고가용성 아키텍처에서, 모든 Sidekiq 노드에 SAML 구성 블록을 포함해야 합니다.

경고: 사용자가 GitLab 그룹에서 우발적으로 제거되지 않도록, GitLab에서 그룹 동기화를 활성화하기 전에 다음 지침을 주의 깊게 따르십시오.

자체 관리 GitLab 인스턴스에 대한 SAML 그룹 동기화 구성 방법:

  1. SAML OmniAuth 공급자를 구성합니다.

  2. SAML ID 공급자가 groups_attribute 설정 값과 동일한 이름의 속성 문을 전송하는지 확인합니다. 참조용으로 /etc/gitlab/gitlab.rb의 공급자 구성 예는 다음과 같습니다:

    gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "공급자 이름", # 로그인 버튼의 선택적 레이블, 기본값은 "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 ID 공급자가 Groups 또는 groups라는 이름의 속성 문을 전송하는지 확인합니다.

참고: SAML 응답의 Groups 또는 groups 값은 그룹 이름 또는 ID일 수 있습니다.

예를 들어, Azure AD는 이름 대신 Azure Group Object ID를 보냅니다. SAML 그룹 링크를 구성할 때 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 ID 공급자 설정에서 구성하는 방법에 대한 자세한 내용은 Azure AD 및 Okta용 예제 구성을 참조하세요.

Microsoft Azure Active Directory 통합

참고: Microsoft는 Azure Active Directory (AD)의 이름이 Entra ID로 변경된다고 발표했습니다.

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

Graph API 엔드포인트는 구성된 고유 사용자 식별자(Name identifier) 속성으로 사용자 객체 ID 또는 userPrincipalName만 지원합니다.

통합이 Group Sync를 처리할 때는 12345678-9abc-def0-1234-56789abcde와 같은 그룹 고유 식별자로 구성된 그룹 링크만 지원됩니다.

Microsoft Azure AD를 통합하려면:

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

Azure AD 필드에 대한 GitLab 설정

GitLab 설정 Azure 필드
Tenant ID Directory (tenant) ID
Client ID Application (client) ID
Client Secret 값 (Certificates & secrets 페이지에서)

Azure AD 구성

  1. Azure Portal에서 Microsoft Entra ID > 앱 등록 > 모든 애플리케이션으로 이동하여 GitLab SAML 애플리케이션을 선택합니다.
  2. Essentials 아래에 Application (client) ID 및 Directory (tenant) ID 값이 표시됩니다. 이 값을 복사하십시오. GitLab 구성에 필요합니다.
  3. 왼쪽 내비게이션에서 Certificates & secrets를 선택합니다.
  4. Client secrets 탭에서 New client secret을 선택합니다.
    1. Description 텍스트 상자에 설명을 추가합니다.
    2. Expires 드롭다운 목록에서 자격 증명의 만료 날짜를 설정합니다. 비밀이 만료되면 자격 증명이 업데이트될 때까지 GitLab 통합이 더 이상 작동하지 않습니다.
    3. 자격 증명을 생성하려면 Add를 선택합니다.
    4. 자격 증명의 Value를 복사합니다. 이 값은 한 번만 표시되며 GitLab 구성에 필요합니다.
  5. 왼쪽 내비게이션에서 API permissions를 선택합니다.
  6. Microsoft Graph > Application permissions를 선택합니다.
  7. GroupMember.Read.All 및 User.Read.All 체크박스를 선택합니다.
  8. Add permissions를 선택하여 저장합니다.
  9. Grant admin consent for <application_name>을 선택한 다음 확인 대화 상자에서 Yes를 선택합니다. 두 권한의 Status 열은 Granted for <application_name>와 함께 녹색 확인으로 변경되어야 합니다.

GitLab 구성하기

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 최상위 그룹을 찾습니다.

  2. 설정 > SAML SSO를 선택합니다.

  3. 그룹에 대한 SAML SSO 구성을 합니다.

  4. Microsoft Azure 통합 섹션에서 이 그룹에 대해 Microsoft Azure 통합 활성화 체크박스를 선택합니다.
    이 섹션은 SAML SSO가 그룹에 대해 구성되고 활성화되어 있는 경우에만 표시됩니다.

  5. Azure Portal에서 Azure Active Directory를 구성할 때 미리 얻은 Tenant ID, Client ID 및 Client secret를 입력합니다.

  6. 선택 사항. 미국 정부를 위해 Azure AD를 사용하거나 Azure AD China를 사용하는 경우, 적절한 로그인 API 엔드포인트와 Graph API 엔드포인트를 입력합니다. 기본값은 대부분의 조직에서 작동합니다.

  7. 변경사항 저장을 선택합니다.

자체 관리형으로 구성하려면:

  1. 인스턴스에 대한 SAML SSO 구성을 합니다.

  2. 왼쪽 사이드바에서 맨 아래에 있는 Admin을 선택합니다.

  3. 설정 > 일반을 선택합니다.

  4. Microsoft Azure 통합 섹션에서 이 그룹에 대해 Microsoft Azure 통합 활성화 체크박스를 선택합니다.

  5. Azure Portal에서 Azure Active Directory를 구성할 때 미리 얻은 Tenant ID, Client ID 및 Client secret를 입력합니다.

  6. 선택 사항. 미국 정부를 위해 Azure AD를 사용하거나 Azure AD China를 사용하는 경우, 적절한 로그인 API 엔드포인트와 Graph API 엔드포인트를 입력합니다. 기본값은 대부분의 조직에서 작동합니다.

  7. 변경사항 저장을 선택합니다.

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

글로벌 SAML 그룹 멤버십 잠금

Tier: Premium, Ultimate Offering: Self-managed, GitLab Dedicated

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

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

글로벌 그룹 멤버십 잠금이 활성화되면:

  • 오직 관리자만 멤버십을 관리할 수 있으며, 접근 수준을 포함합니다.
  • 사용자는 할 수 없습니다:
    • 다른 그룹과 프로젝트를 공유합니다.
    • 그룹에서 생성된 프로젝트에 멤버를 초대합니다.

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

  1. 귀하의 자체 관리형 GitLab 인스턴스에 대한 SAML 구성을 합니다.

  2. 왼쪽 사이드바에서 맨 아래에 있는 Admin을 선택합니다.

  3. 설정 > 일반을 선택합니다.

  4. 가시성 및 접근 제어 섹션을 확장합니다.

  5. SAML 그룹 링크 동기화에 멤버십 잠금이 선택되어 있는지 확인합니다.

자동 멤버 제거

그룹 동기화 후, 매핑된 SAML 그룹의 구성원이 아닌 사용자는 그룹에서 제거됩니다.
GitLab.com에서는 최상위 그룹의 사용자에게 기본 멤버십 역할이 할당되며, 제거되지 않습니다.

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

  • Alex Garcia는 GitLab에 로그인하고 SAML 그룹 C에 속하지 않기 때문에 GitLab 그룹 C에서 제거됩니다.
  • Sidney Jones는 SAML 그룹 C에 속하지만, 아직 로그인하지 않아서 GitLab 그룹 C에 추가되지 않습니다.
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TB accTitle: 자동 멤버 제거 accDescr: 그룹 동기화가 설정된 경우 사용자의 그룹 멤버십이 로그인 전에 어떻게 결정되는지. subgraph SAML 사용자 SAMLUserA[Sidney Jones] SAMLUserB[Zhang Wei] SAMLUserC[Alex Garcia] SAMLUserD[Charlie Smith] end subgraph SAML 그룹 SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] SAMLGroupA --> SAMLGroupC["Group C"] SAMLGroupA --> SAMLGroupD["Group D"] end SAMLGroupB --> |구성원|SAMLUserA SAMLGroupB --> |구성원|SAMLUserB SAMLGroupC --> |구성원|SAMLUserA SAMLGroupC --> |구성원|SAMLUserB SAMLGroupD --> |구성원|SAMLUserD SAMLGroupD --> |구성원|SAMLUserC
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TB accTitle: 자동 멤버 제거 accDescr: Sid가 그룹 C에 로그인하지 않았고 그룹 B에 그룹 링크가 구성되지 않았을 때의 사용자 멤버십. subgraph GitLab 사용자 GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab 그룹 GitLabGroupA["Group A<br> (SAML 구성됨)"] --> GitLabGroupB["Group B<br> (SAML 그룹 링크 미구성)"] GitLabGroupA --> GitLabGroupC["Group C<br> (SAML 그룹 링크 구성됨)"] GitLabGroupA --> GitLabGroupD["Group D<br> (SAML 그룹 링크 구성됨)"] end GitLabGroupB --> |구성원|GitLabUserA GitLabGroupC --> |구성원|GitLabUserB GitLabGroupC --> |구성원|GitLabUserC GitLabGroupD --> |구성원|GitLabUserC GitLabGroupD --> |구성원|GitLabUserD
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TB accTitle: 자동 멤버 제거 accDescr: Alex Garcia가 그룹 링크가 활성화된 그룹에 로그인한 후의 멤버십 작동 방식. subgraph GitLab 사용자 GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph Alex Garcia가 로그인한 후의 GitLab 그룹 GitLabGroupA[Group A] GitLabGroupA["Group A<br> (SAML 구성됨)"] --> GitLabGroupB["Group B<br> (SAML 그룹 링크 미구성)"] GitLabGroupA --> GitLabGroupC["Group C<br> (SAML 그룹 링크 구성됨)"] GitLabGroupA --> GitLabGroupD["Group D<br> (SAML 그룹 링크 구성됨)"] end GitLabGroupB --> |구성원|GitLabUserA GitLabGroupC --> |구성원|GitLabUserB GitLabGroupD --> |구성원|GitLabUserC GitLabGroupD --> |구성원|GitLabUserD

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

Azure AD와 SAML을 사용할 때, 조직의 사용자가 150개 이상의 그룹의 구성원인 경우 SAML 그룹 동기화를 사용하는 경우,
해당 사용자는 그룹 구성원을 잃을 수 있습니다.

자세한 내용은
Microsoft 그룹 초과 사용을 참조하세요.

GitLab에는 150개 이상의 그룹에 속한 사용자를 위한 SAML 그룹 동기화를 가능하게 하는
Microsoft Azure Active Directory 통합이 있습니다.
이 통합은 Microsoft Graph API를 사용하여 모든 사용자 회원 정보를 가져오며, 150개 그룹에 제한되지 않습니다.

그렇지 않으면, 그룹 클레임을 변경하여 응용 프로그램에 할당된 그룹 옵션을 사용할 수 있습니다.

그룹 클레임 관리