SAML 그룹 링크 구성
- API 사용
SAML 그룹 동기화 구성
Microsoft Azure Active Directory 통합
전역 SAML 그룹 멤버십 잠금
자동 멤버 제거
- 여러 SAML 그룹에 속한 사용자는 자동으로 GitLab 그룹에서 제거됨

SAML 그룹 동기화

Tier: Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

그룹 동기화 구성을 추가하거나 변경하면 매핑된 GitLab 그룹에서 사용자가 제거될 수 있습니다. 그룹 이름과 SAML 응답의 groups 디렉터리 간에 불일치가 있는 경우 제거가 발생합니다. 변경하기 전에 SAML 응답에 groups 속성이 포함되어 있는지 확인하고 AttributeValue 값이 GitLab의 SAML 그룹 이름과 일치하거나, 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 그룹을 링크하려면:

SAML 그룹 이름에 relevary saml:AttributeValue 값을 입력합니다. 여기에 입력한 값은 SAML 응답에서 보낸 값과 정확히 일치해야 합니다. 일부 IdP의 경우 이 값은 친숙한 그룹 이름이 아니라 그룹 ID 또는 개체 ID(Azure AD)일 수 있습니다.
Access Level에서 기본 역할이나 사용자 정의 역할 중 하나를 선택합니다.
저장을 선택합니다.
필요한 경우 추가 그룹 링크를 추가하려면 반복합니다.

하나의 사용자가 동일한 GitLab 그룹에 매핑된 여러 SAML 그룹의 멤버인 경우 사용자는 그룹에서 가장 높은 역할을 받습니다. 예를 들어 하나의 그룹이 Guest로 연결되고 다른 그룹이 Maintainer로 연결되면 두 그룹에 모두 속한 사용자는 Maintainer 역할을 받습니다.

사용자가 부여받은:

그룹 동기화의 더 높은 역할은 그룹의 직접 멤버십을 가지고 있는 것으로 표시됩니다.
그룹 동기화의 더 낮거나 동일한 역할은 그룹의 상속 멤버십을 가지고 있는 것으로 표시됩니다.

API 사용

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

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

SAML 그룹 동기화 구성

SAML 그룹 동기화와 여러 GitLab 노드(분산 또는 고가용성 아키텍처의 경우)가 있는 경우 SAML 구성 블록을 Rails 애플리케이션 노드 외에도 모든 Sidekiq 노드에 포함해야 합니다.

GitLab에서 그룹 동기화를 활성화하기 전에 잘 따라와야 합니다. GitLab 그룹에서 사용자가 실수로 제거되는 것을 방지하려면 다음 지침을 따르세요.

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

SAML OmniAuth Provider를 구성합니다.

SAML 식별 공급자가 groups_attribute 설정의 값과 동일한 이름의 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 그룹 동기화를 구성하려면:

GitLab.com 그룹을 위한 SAML SSO를 참조하세요.
SAML 식별 공급자가 Groups 또는 groups라는 이름의 attribute 문을 보내도록 확인합니다.

SAML 응답의 Groups 또는 groups 값은 그룹 이름 또는 ID가 될 수 있습니다. 예를 들어, Azure AD는 이름 대신 Azure 그룹 개체 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와 같은 다른 attribute 이름은 그룹의 소스로 사용할 수 없습니다.

SAML 식별 공급자의 설정에서 필요한 그룹 attribute 이름을 구성하는 방법에 대한 자세한 내용은 Azure AD 및 Okta의 예제 구성을 참조하세요.

Microsoft Azure Active Directory 통합

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

Microsoft는 Azure Active Directory (AD)를 Microsoft Entra ID로 공식 발표했습니다.

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

Graph API endpoint는 user object ID 또는 userPrincipalName 과 같은 구성된 고유 사용자 식별자(Name identifier) attribute만을 지원합니다.

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

Microsoft Azure AD를 통합하려면:

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

GitLab 설정에서 Azure AD 필드

GitLab 설정	Azure 필드
Tenant ID	디렉터리(tenant) ID
Client ID	애플리케이션(client) ID
Client Secret	값(Certificates & secrets 페이지에 표시됨)

Azure AD 구성

Azure Portal에 들어가서 Microsoft Entra ID > App registrations > All applications로 이동한 다음 GitLab SAML 애플리케이션을 선택합니다.
Essentials 아래에서 Application (client) ID와 Directory (tenant) ID 값이 표시됩니다. 이 값들은 GitLab 구성에 필요하므로 복사합니다.
왼쪽 네비게이션에서 Certificates & secrets를 선택합니다.
Client secrets 탭에서 New client secret를 선택합니다.
1. Description 텍스트 상자에 설명을 추가합니다.
2. Expires 드롭다운 디렉터리에서 자격 증명의 만료 날짜를 설정합니다. 시크릿이 만료되면 GitLab 통합이 자격 증명이 업데이트될 때까지 더 이상 작동하지 않습니다.
3. 자격 증명을 생성하려면 Add를 선택합니다.
4. 자격 증명의 Value를 복사합니다. 이 값은 한 번만 표시되며 GitLab 구성에 필요합니다.
왼쪽 네비게이션에서 API permissions를 선택합니다.
Microsoft Graph > Application permissions을 선택합니다.
GroupMember.Read.All 및 User.Read.All의 확인란을 선택합니다.
권한을 저장하려면 Add permissions를 선택합니다.
****에 대한 관리자 동의 부여를 선택한 후 확인 대화상자에서 **Yes**를 선택합니다. 두 권한의 **Status** 열은 **Granted for ``**으로 변경되어야 합니다.

GitLab 구성

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

왼쪽 사이드바에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.
Settings > SAML SSO를 선택합니다.
그룹에 대한 SAML SSO를 구성합니다.
Microsoft Azure 통합 섹션에서 Enable Microsoft Azure integration for this group 확인란을 선택합니다. 해당 섹션은 그룹에 SAML SSO가 구성되어 활성화된 경우에만 표시됩니다.
이전에 Azure Active Directory를 구성할 때 얻은 Tenant ID, Client ID, 및 Client Secret를 입력합니다.
선택사항입니다. Azure AD를 사용하는 경우 미국 정부용이나 중국용 Azure AD에 적절한 Login API endpoint 및 Graph API endpoint를 입력합니다. 대부분의 조직에서는 기본 값이 작동합니다.
Save changes를 선택합니다.

Self-Managed를 위해 구성하려면:

인스턴스에 대한 SAML SSO를 구성합니다.
왼쪽 사이드바에서 가장 아래에서 Admin Area를 선택합니다.
Settings > General을 선택합니다.
Microsoft Azure integration 섹션에서 Enable Microsoft Azure integration for this group 확인란을 선택합니다.
이전에 Azure Active Directory를 구성할 때 얻은 Tenant ID, Client ID, 및 Client Secret를 입력합니다.
선택사항입니다. Azure AD를 사용하는 경우 미국 정부용이나 중국용 Azure AD에 적절한 Login API endpoint 및 Graph API endpoint를 입력합니다. 대부분의 조직에서는 기본 값이 작동합니다.
Save changes를 선택합니다.

이 구성으로 사용자가 SAML로 로그인하고 Azure가 응답으로 그룹 이탈 클레임을 보내면 GitLab은 Microsoft Graph API를 호출하여 사용자의 그룹 멤버십을 검색한 후 SAML 그룹 링크에 따라 GitLab 그룹 멤버십을 업데이트합니다.

전역 SAML 그룹 멤버십 잠금

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

GitLab 15.10에서 도입.

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

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

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

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

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

Self-Managed GitLab 인스턴스에 대해 SAML을 구성합니다.
왼쪽 사이드바에서 가장 아래에서 Admin Area를 선택합니다.
Settings > General을 선택합니다.
Visibility and access controls 섹션을 확장합니다.
Lock memberships to SAML Group Links synchronization이 선택되어 있는지 확인합니다.

자동 멤버 제거

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

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

Alex Garcia가 GitLab에 로그인하고 SAML Group C에 속하지 않았기 때문에 GitLab Group C에서 제거됩니다.
Sidney Jones는 SAML Group C에 속하지만 아직 로그인하지 않았으므로 GitLab Group C에 추가되지 않습니다.

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

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

GitLab은 Microsoft Azure Active Directory 통합을 보유한 조직을 위해 SAML 그룹 동기화를 가능하게 하는데, 이 통합은 150개 이상의 그룹에 속한 사용자 명단을 가져오기 위해 Microsoft Graph API를 사용하며 150개의 그룹에 한정되지 않습니다.

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

SAML 그룹 동기화

SAML 그룹 링크 구성

API 사용

SAML 그룹 동기화 구성

Microsoft Azure Active Directory 통합

GitLab 설정에서 Azure AD 필드

Azure AD 구성

GitLab 구성

전역 SAML 그룹 멤버십 잠금

자동 멤버 제거

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

도움말

기능 사용 가능성과 제품 평가판

도움받기