SAML 그룹 동기화

Tier: 프리미엄, 얼티밋 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 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를 사용하는 Self-managed GitLab

사용자가 로그인할 때 GitLab은 다음을 수행합니다:

  • 구성된 모든 SAML 그룹 링크를 확인합니다.
  • 여러 IdP를 통해 사용자가 속한 SAML 그룹에 기반하여 해당 사용자를 GitLab 그룹에 추가합니다.

GitLab의 그룹 링크 매핑은 특정 IdP에 묶여 있지 않으므로 SAML 응답에서 그룹을 일치시킬 수 있도록 모든 SAML IdP를 구성해야 합니다. 이것은 사용자가 로그인한 IdP와 관계없이 GitLab이 SAML 응답에서 그룹을 일치시킬 수 있음을 의미합니다.

예를 들어, SAML1 및 SAML2라는 2개의 IdP가 있다고 가정합니다.

GitLab에서 특정 그룹에 대해 두 가지 그룹 링크를 구성했습니다:

  • gtlb-owner => 소유자 역할.
  • gtlb-dev => 개발자 역할.

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

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

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

그 사용자가 로그아웃하고 SAML2로 그룹에 다시 로그인하면 SAML 응답에서 해당 사용자가 gtlb-dev의 구성원임을 보여주기 때문에 GitLab은 해당 사용자의 역할을 개발자로 설정합니다.

이제 사용자가 SAML2에서 gtlb-owner 또는 gtlb-dev의 구성원이 아닌 경우를 위한 이전 예제를 변경해 봅시다.

  • 사용자가 SAML1로 그룹에 로그인하면 해당 사용자는 그룹의 소유자 역할을 받습니다.
  • 사용자가 SAML2로 로그인하면 해당 사용자는 구성된 그룹 링크의 구성원이 아니기 때문에 그룹에서 제거됩니다.

역할 충돌 해결 방법

여러 매핑된 SAML 그룹의 구성원

한 사용자가 동일한 GitLab 그룹에 매핑된 여러 SAML 그룹의 구성원인 경우 해당 사용자는 그룹에서 가장 높은 역할을 받게 됩니다. 예를 들어, 하나의 그룹이 게스트로 연결되고 다른 그룹이 관리자로 연결되면 두 그룹의 구성원인 사용자는 관리자 역할을 받습니다.

상위 그룹 역할이 하위 그룹 역할보다 높음

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

API 사용

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

SAML 그룹 동기화 구성

note
SAML 그룹 동기화를 사용하고 여러 GitLab 노드가 있는 경우 즉, 분산되거나 고가용성 아키텍처에서는 SAML 구성 블록을 레일스 애플리케이션 노드뿐만 아니라 모든 Sidekiq 노드에 포함해야 합니다.
caution
GitLab 그룹에서 사용자가 실수로 제거되는 것을 방지하려면 GitLab에서 그룹 동기화를 활성화하기 전에이 지침을 엄격히 따라야 합니다.

Self-managed GitLab 인스턴스를 위해 SAML 그룹 동기화를 구성하려면:

  1. SAML OmniAuth Provider를 구성합니다.

  2. SAML ID 공급자가 groups_attribute 설정의 값과 동일한 이름의 속성문을 보내도록 해야 합니다. 참고로 /etc/gitlab/gitlab.rb의 다음 제공자 구성 예제를 참조하세요: 

    gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name", # 로그인 버튼의 선택적 라벨, 기본값은 "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라는 이름의 속성문을 보내야 합니다.
note
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 엔드포인트는 구성된 고유한 사용자 식별자(이름 식별자)로 사용자 객체 ID 또는 userPrincipalName 만 지원합니다.

통합이 그룹 동기화를 처리하는 경우, 고유 식별자(예: 12345678-9abc-def0-1234-56789abcde)로 구성된 그룹 링크만 지원됩니다.

Microsoft Azure AD를 통합하려면 다음을 수행합니다.

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

GitLab 설정을 Azure AD 필드로

GitLab 설정 Azure 필드
Tenant ID 디렉터리 (테넌트) ID
Client ID 애플리케이션 (클라이언트) ID
Client Secret 값 (인증서 및 비밀 페이지에서)

Azure AD 구성

  1. Azure Portal에서 Microsoft Entra ID > App registrations > All applications으로 이동하고 GitLab SAML 애플리케이션을 선택합니다.
  2. 필수 사항 아래에서 애플리케이션 (클라이언트) ID 및 디렉터리 (테넌트) 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. 관리자 동의 허용을 선택한 다음 확인 대화 상자에서 동의함을 선택합니다. 두 권한에 대한 상태 열은 Granted for <application_name>으로 변경되어야 합니다.

GitLab 구성

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

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

사용자 관리에 대한 GitLab 콘텐츠를 찾으시나요?:)

자동 구성원 제거

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

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

  • Alex Garcia는 GitLab에 로그인하고 SAML 그룹 C에 속하지 않기 때문에 GitLab 그룹 C에서 제거됩니다.
  • Sidney Jones는 SAML 그룹 C에 속하지만 아직 로그인하지 않았기 때문에 GitLab 그룹 C에 추가되지 않습니다.
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TB accTitle: Automatic member removal accDescr: 그룹 동기화가 설정된 경우 로그인 전 사용자의 그룹 멤버십이 어떻게 결정되는지 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
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TB accTitle: Automatic member removal accDescr: 그룹 C에 로그인하지 않은 Sidney의 사용자 멤버십, 그리고 그룹 B가 그룹 링크를 구성하지 않은 경우 subgraph GitLab 사용자 GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab 그룹 GitLabGroupA["그룹 A<br> (SAML 구성됨)"] --> GitLabGroupB["그룹 B<br> (SAML 그룹 링크 구성되지 않음)"] GitLabGroupA --> GitLabGroupC["그룹 C<br> (SAML 그룹 링크 구성됨)"] GitLabGroupA --> GitLabGroupD["그룹 D<br> (SAML 그룹 링크 구성됨)"] end GitLabGroupB --> |멤버|GitLabUserA GitLabGroupC --> |멤버|GitLabUserB GitLabGroupC --> |멤버|GitLabUserC GitLabGroupD --> |멤버|GitLabUserC GitLabGroupD --> |멤버|GitLabUserD
%%{init: { "fontFamily": "GitLab Sans" }}%% graph TB accTitle: Automatic member removal accDescr: 그룹 링크가 활성화된 그룹에 가입한 후 Alex Garcia의 멤버십이 작동하는 방법 subgraph GitLab 사용자 GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph Alex Garcia가 그룹에 로그인한 후의 GitLab 그룹 GitLabGroupA[그룹 A] GitLabGroupA["그룹 A<br> (SAML 구성됨)"] --> GitLabGroupB["그룹 B<br> (SAML 그룹 링크 구성되지 않음)"] GitLabGroupA --> GitLabGroupC["그룹 C<br> (SAML 그룹 링크 구성됨)"] GitLabGroupA --> GitLabGroupD["그룹 D<br> (SAML 그룹 링크 구성됨)"] end GitLabGroupB --> |멤버|GitLabUserA GitLabGroupC --> |멤버|GitLabUserB GitLabGroupD --> |멤버|GitLabUserC GitLabGroupD --> |멤버|GitLabUserD

다수의 SAML 그룹에 속한 사용자가 GitLab 그룹에서 자동으로 제거됨

SAML과 함께 Azure AD를 사용할 때 조직 구성원 중 150개 이상의 그룹에 속한 사용자가 SAML 그룹 동기화를 사용하는 경우, 해당 사용자는 그룹 멤버십을 상실할 수 있습니다. 자세한 내용은 Microsoft 그룹 초과를 참조하세요.

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

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

그룹 클레임 관리