SAML 그룹 동기화

요약

SAML 그룹 동기화를 사용하면 SAML ID 제공자(IdP)에서의 사용자 그룹 할당을 기반으로 특정 권한을 가진 사용자를 기존 GitLab 그룹에 할당할 수 있습니다. 예를 들어, 사용자 @amelia가 SAML IdP의 security 그룹에 할당된 경우, SAML 그룹 동기화를 사용하여 @amelia를 Maintainer 권한으로 security-gitlab 그룹에 할당하고, Reporter 권한으로 vulnerability...

히스토리

GitLab 15.1에서 GitLab Self-Managed에 도입되었습니다.

SAML 그룹 동기화를 사용하면 SAML ID 제공자(IdP)에서의 사용자 그룹 할당을 기반으로 특정 권한을 가진 사용자를 기존 GitLab 그룹에 할당할 수 있습니다. SAML 그룹 동기화를 사용하면 SAML IdP 그룹과 GitLab 그룹 간의 다대다 매핑을 생성할 수 있습니다.

예를 들어, 사용자 @amelia가 SAML IdP의 security 그룹에 할당된 경우, SAML 그룹 동기화를 사용하여 @amelia를 Maintainer 권한으로 security-gitlab 그룹에 할당하고, Reporter 권한으로 vulnerability 그룹에 할당할 수 있습니다.

SAML 그룹 동기화는 그룹을 생성하지 않습니다. 먼저 그룹을 생성한 다음 매핑을 생성해야 합니다.

GitLab.com에서는 SAML 그룹 동기화가 기본적으로 구성되어 있습니다. GitLab Self-Managed에서는 수동으로 구성해야 합니다.

권한 우선순위#

그룹 동기화는 매핑된 그룹에서 사용자의 권한과 멤버십 유형을 결정합니다.

다중 SAML IdP#

사용자가 로그인하면 GitLab은:

구성된 모든 SAML 그룹 링크를 확인합니다.
다양한 IdP에서 사용자가 속한 SAML 그룹을 기반으로 해당 사용자를 대응하는 GitLab 그룹에 추가합니다.

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

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

GitLab의 특정 그룹에 두 개의 그룹 링크를 구성했다고 가정합니다:

gtlb-owner => Owner 권한
gtlb-dev => Developer 권한

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 그룹의 멤버인 경우, 해당 사용자는 해당 SAML 그룹 중 가장 높은 권한을 할당받습니다.

예를 들어, 사용자가 한 그룹에서 Guest 권한을 갖고 다른 그룹에서 Maintainer 권한을 갖는 경우 Maintainer 권한이 할당됩니다.

멤버십 유형#

SAML 그룹에서 사용자의 권한이 하위 그룹 중 하나의 권한보다 높은 경우, 매핑된 GitLab 그룹에서 사용자의 멤버십은 매핑된 그룹에서 할당된 권한에 따라 다릅니다.

그룹 동기화를 통해 사용자에게 할당된 권한이:

더 높은 권한인 경우, 사용자는 그룹의 직접 멤버가 됩니다.
동일하거나 낮은 권한인 경우, 사용자는 그룹의 상속 멤버가 됩니다.

자동 멤버 제거#

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

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

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

Mermaid 다이어그램 (26줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: How group membership of users is determined before sign in if group sync is set up.
subgraph SAML users
SAMLUserA[Sidney Jones]
SAMLUserB[Zhang Wei]
SAMLUserC[Alex Garcia]
SAMLUserD[Charlie Smith]
end
subgraph SAML groups
SAMLGroupA["Group A"] --> SAMLGroupB["Group B"]
SAMLGroupA --> SAMLGroupC["Group C"]
SAMLGroupA --> SAMLGroupD["Group D"]
end
SAMLGroupB --> |Member|SAMLUserA
SAMLGroupB --> |Member|SAMLUserB
SAMLGroupC --> |Member|SAMLUserA
SAMLGroupC --> |Member|SAMLUserB
SAMLGroupD --> |Member|SAMLUserD
SAMLGroupD --> |Member|SAMLUserC

Mermaid 다이어그램 (25줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: User membership for Sidney when she has not signed into group C, and group B has not configured group links.
subgraph GitLab users
  GitLabUserA[Sidney Jones]
  GitLabUserB[Zhang Wei]
  GitLabUserC[Alex Garcia]
  GitLabUserD[Charlie Smith]
end

subgraph GitLab groups
GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
end
GitLabGroupB --> |Member|GitLabUserA
GitLabGroupC --> |Member|GitLabUserB
GitLabGroupC --> |Member|GitLabUserC
GitLabGroupD --> |Member|GitLabUserC
GitLabGroupD --> |Member|GitLabUserD

Mermaid 다이어그램 (23줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: How membership of Alex Garcia works once she has signed into a group that has group links enabled.
subgraph GitLab users
GitLabUserA[Sidney Jones]
GitLabUserB[Zhang Wei]
GitLabUserC[Alex Garcia]
GitLabUserD[Charlie Smith]
end
subgraph GitLab groups after Alex Garcia signs in
GitLabGroupA[Group A]
GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
end
GitLabGroupB --> |Member|GitLabUserA
GitLabGroupC --> |Member|GitLabUserB
GitLabGroupD --> |Member|GitLabUserC
GitLabGroupD --> |Member|GitLabUserD

SAML 그룹 동기화 구성#

그룹 동기화 구성을 추가하거나 변경하면 그룹 이름이 SAML 응답의 나열된 groups와 일치하지 않는 경우 매핑된 GitLab 그룹에서 사용자가 제거될 수 있습니다. 사용자가 제거되는 것을 방지하려면 그룹 동기화를 구성하기 전에 다음 중 하나를 확인하십시오:

SAML 응답에 groups 속성이 포함되어 있고 AttributeValue 값이 GitLab의 SAML 그룹 이름과 일치합니다.
모든 그룹이 GitLab에서 제거되어 그룹 동기화를 비활성화합니다.

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

SAML 그룹 동기화를 구성하려면:

GitLab.com 그룹용 SAML SSO를 참조하십시오.
SAML ID 제공자가 Groups 또는 groups라는 속성 문을 전송하는지 확인합니다.

SAML 그룹 동기화를 구성하려면:

SAML OmniAuth 제공자를 구성합니다.

SAML ID 제공자가 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"
    }
  }
]

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에 대한 예시 구성을 참조하십시오.

SAML 그룹 링크 구성#

SAML 그룹 동기화는 하나 이상의 SAML 그룹 링크가 있는 그룹만 관리합니다.

사전 요구사항:

GitLab Self-Managed 인스턴스에 SAML 그룹 동기화가 구성되어 있어야 합니다.

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

하나 이상의 SAML 그룹 링크를 구성하여 SAML IdP 그룹 이름을 GitLab 권한에 매핑할 수 있습니다.
SAML IdP 그룹의 멤버는 다음 SAML 로그인 시 GitLab 그룹의 멤버로 추가됩니다.
그룹 멤버십은 사용자가 SAML을 사용하여 로그인할 때마다 평가됩니다.
SAML 그룹 링크는 최상위 그룹 또는 모든 하위 그룹에 대해 구성할 수 있습니다.
SAML 그룹 링크가 생성된 다음 제거된 경우:
- 다른 SAML 그룹 링크가 구성되어 있으면, 제거된 그룹 링크에 있던 사용자는 동기화 중에 자동으로 그룹에서 제거됩니다.
- 다른 SAML 그룹 링크가 구성되어 있지 않으면, 사용자는 동기화 중에도 그룹에 남아 있습니다. 해당 사용자는 그룹에서 수동으로 제거해야 합니다.

SAML 그룹을 연결하려면:

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

GitLab Duo 시트 할당 관리#

히스토리

GitLab 17.8의 GitLab.com에 saml_groups_duo_pro_add_on_assignment라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
GitLab 18.0의 GitLab Self-Managed에 도입되었습니다.

사전 요구사항:

활성 GitLab Duo 애드온 구독

SAML 그룹 동기화는 IdP 그룹 멤버십을 기반으로 GitLab Duo 시트 할당 및 제거를 관리할 수 있습니다. 구독에 남은 시트가 있을 때만 시트가 할당됩니다.

GitLab.com에 대해 구성하려면:

SAML 그룹 링크를 구성할 때 이 그룹의 사용자에게 GitLab Duo 시트 할당 체크박스를 선택합니다.
저장을 선택합니다.
GitLab Duo Pro 또는 GitLab Duo Enterprise 시트가 할당되어야 하는 모든 SAML 사용자에 대한 추가 그룹 링크를 추가하기 위해 반복합니다. 이 설정이 활성화된 그룹 링크와 일치하지 않는 ID 제공자 그룹 멤버십을 가진 사용자의 경우 GitLab Duo 시트가 할당 해제됩니다.

이 체크박스는 활성 GitLab Duo 애드온 구독이 없는 그룹에는 표시되지 않습니다.

Self-Managed에 대해 구성하려면:

SAML OmniAuth 제공자를 구성합니다.

구성에 groups_attribute와 duo_add_on_groups가 포함되어 있는지 확인합니다. duo_add_on_groups 중 하나 이상의 멤버인 사용자는 시트가 사용 가능한 경우 GitLab Duo 시트가 할당됩니다. 참조용으로 /etc/gitlab/gitlab.rb의 다음 제공자 구성 예시를 참조하십시오:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name",
    groups_attribute: 'Groups',
    duo_add_on_groups: ['Developers', 'Freelancers'],
    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"
    }
  }
]

Microsoft Azure Active Directory 통합#

히스토리

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

Note

Microsoft는 Azure Active Directory(AD)가 Entra ID로 이름이 변경되고 있다고 발표했습니다.

Microsoft Azure를 사용한 그룹 동기화 데모는 데모: SAML 그룹 동기화를 참조하십시오.

Azure AD는 groups 클레임에서 최대 150개의 그룹을 전송합니다. Azure AD와 SAML 그룹 동기화를 사용할 때, 조직의 사용자가 150개 이상의 그룹의 멤버인 경우, Azure AD는 그룹 초과에 대한 SAML 응답에서 groups 클레임 속성을 전송하며, 사용자가 그룹에서 자동으로 제거될 수 있습니다.

이 문제를 방지하려면 Azure AD 통합을 사용할 수 있습니다. 이 통합은:

150개 그룹으로 제한되지 않습니다.
Microsoft Graph API를 사용하여 모든 사용자 멤버십을 가져옵니다. Graph API 엔드포인트는 Azure 구성 고유 사용자 식별자(이름 식별자) 속성으로 사용자 개체 ID 또는 userPrincipalName만 허용합니다.
그룹 동기화를 처리할 때 그룹 고유 식별자(예: 12345678-9abc-def0-1234-56789abcde)로 구성된 그룹 링크만 지원합니다.

또는 그룹 클레임을 애플리케이션에 할당된 그룹 옵션을 사용하도록 변경할 수 있습니다.

Azure AD 구성#

통합의 일환으로 GitLab이 Microsoft Graph API와 통신할 수 있도록 허용해야 합니다.

Azure AD를 구성하려면:

Azure Portal에서 Microsoft Entra ID > 앱 등록 > 모든 애플리케이션으로 이동하고 GitLab SAML 애플리케이션을 선택합니다.
기본 정보 아래에 애플리케이션(클라이언트) ID와 디렉토리(테넌트) ID 값이 표시됩니다. GitLab 구성에 필요하므로 이 값들을 복사합니다.
왼쪽 탐색에서 인증서 및 비밀을 선택합니다.
클라이언트 비밀 탭에서 새 클라이언트 비밀을 선택합니다.
1. 설명 텍스트 상자에 설명을 추가합니다.
2. 만료 드롭다운 목록에서 자격 증명의 만료 날짜를 설정합니다. 비밀이 만료되면 자격 증명이 업데이트될 때까지 GitLab 통합이 더 이상 작동하지 않습니다.
3. 자격 증명을 생성하려면 추가를 선택합니다.
4. 자격 증명의 값을 복사합니다. 이 값은 한 번만 표시되며 GitLab 구성에 필요합니다.
왼쪽 탐색에서 API 권한을 선택합니다.
Microsoft Graph > 애플리케이션 권한을 선택합니다.
GroupMember.Read.All 및 User.Read.All 체크박스를 선택합니다.
저장하려면 권한 추가를 선택합니다.
<application_name>에 대한 관리자 동의 부여를 선택한 다음 확인 대화상자에서 예를 선택합니다. 두 권한 모두에 대한 상태 열이 <application_name>에 대해 부여됨이라는 녹색 체크로 변경되어야 합니다.

GitLab 구성#

Azure AD를 구성한 후 GitLab이 Azure AD와 통신할 수 있도록 GitLab을 구성해야 합니다.

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

다음 표는 구성에 대한 GitLab 설정과 해당 Azure AD 필드를 나열합니다:

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

GitLab.com 그룹에 대해 Azure AD를 구성하려면:

상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준이어야 합니다.
설정 > SAML SSO를 선택합니다.
그룹에 대한 SAML SSO를 구성합니다.
Microsoft Azure 통합 섹션에서 이 그룹에 대한 Microsoft Azure 통합 활성화 체크박스를 선택합니다. 이 섹션은 그룹에 SAML SSO가 구성되고 활성화된 경우에만 표시됩니다.
Azure Portal에서 Azure Active Directory를 구성할 때 이전에 얻은 테넌트 ID, 클라이언트 ID, 클라이언트 비밀을 입력합니다.
선택 사항. 미국 정부용 Azure AD 또는 Azure AD 중국을 사용하는 경우 적절한 로그인 API 엔드포인트와 Graph API 엔드포인트를 입력합니다. 기본값은 대부분의 조직에서 작동합니다.
변경사항 저장을 선택합니다.

사전 요구사항:

관리자 액세스.

GitLab Self-Managed에 대해 구성하려면:

인스턴스에 대한 SAML SSO를 구성합니다.
오른쪽 상단 모서리에서 관리자를 선택합니다.
왼쪽 사이드바에서 설정 > 일반을 선택합니다.
Microsoft Azure 통합 섹션에서 이 그룹에 대한 Microsoft Azure 통합 활성화 체크박스를 선택합니다.
Azure Portal에서 Azure Active Directory를 구성할 때 이전에 얻은 테넌트 ID, 클라이언트 ID, 클라이언트 비밀을 입력합니다.
선택 사항. 미국 정부용 Azure AD 또는 Azure AD 중국을 사용하는 경우 적절한 로그인 API 엔드포인트와 Graph API 엔드포인트를 입력합니다. 기본값은 대부분의 조직에서 작동합니다.
변경사항 저장을 선택합니다.

전역 SAML 그룹 멤버십 잠금#

히스토리

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

SAML 그룹 멤버십에 전역 잠금을 적용할 수 있습니다. 이 잠금은 SAML 그룹 링크와 멤버십이 동기화되는 하위 그룹에 새 멤버를 초대할 수 있는 사람을 제한합니다.

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

그룹 또는 하위 그룹을 코드 소유자로 설정할 수 없습니다. 자세한 내용은 전역 그룹 멤버십 잠금과의 비호환성을 참조하십시오.
관리자만 그룹 멤버를 관리하고 액세스 수준을 변경할 수 있습니다.
그룹 멤버는:
- 프로젝트를 다른 그룹과 공유할 수 없습니다.
- 그룹에서 생성된 프로젝트에 멤버를 초대할 수 없습니다.
- SAML 그룹 링크 동기화에 구성된 최상위 그룹의 멤버십을 수정할 수 없습니다.

그룹 멤버십 잠금#

사전 요구사항:

GitLab Self-Managed에 대한 SAML SSO가 구성되어 있어야 합니다.
관리자 액세스.

SAML 그룹 링크 동기화에 멤버십을 잠그려면:

오른쪽 상단 모서리에서 관리자를 선택합니다.
왼쪽 사이드바에서 설정 > 일반을 선택합니다.
가시성 및 액세스 제어 섹션을 확장합니다.
SAML 그룹 링크 동기화에 멤버십 잠금 체크박스를 선택합니다.

SAML 그룹 동기화

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

원문 보기

번역일: 2026-05-22

요약

히스토리

GitLab 15.1에서 GitLab Self-Managed에 도입되었습니다.

SAML 그룹 동기화는 그룹을 생성하지 않습니다. 먼저 그룹을 생성한 다음 매핑을 생성해야 합니다.

GitLab.com에서는 SAML 그룹 동기화가 기본적으로 구성되어 있습니다. GitLab Self-Managed에서는 수동으로 구성해야 합니다.

권한 우선순위#

그룹 동기화는 매핑된 그룹에서 사용자의 권한과 멤버십 유형을 결정합니다.

다중 SAML IdP#

사용자가 로그인하면 GitLab은:

구성된 모든 SAML 그룹 링크를 확인합니다.
다양한 IdP에서 사용자가 속한 SAML 그룹을 기반으로 해당 사용자를 대응하는 GitLab 그룹에 추가합니다.

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

GitLab의 특정 그룹에 두 개의 그룹 링크를 구성했다고 가정합니다:

gtlb-owner => Owner 권한
gtlb-dev => Developer 권한

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

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

이제 SAML2에서 사용자가 gtlb-owner나 gtlb-dev 중 어느 것의 멤버도 아닌 이전 예시로 변경해 봅시다.

사용자가 SAML1로 그룹에 로그인하면 사용자는 해당 그룹에서 Owner 권한을 받습니다.
사용자가 SAML2로 로그인하면 구성된 그룹 링크 중 어느 것의 멤버도 아니기 때문에 그룹에서 제거됩니다.

다중 SAML 그룹#

사용자가 동일한 GitLab 그룹에 매핑된 여러 SAML 그룹의 멤버인 경우, 해당 사용자는 해당 SAML 그룹 중 가장 높은 권한을 할당받습니다.

예를 들어, 사용자가 한 그룹에서 Guest 권한을 갖고 다른 그룹에서 Maintainer 권한을 갖는 경우 Maintainer 권한이 할당됩니다.

멤버십 유형#

그룹 동기화를 통해 사용자에게 할당된 권한이:

더 높은 권한인 경우, 사용자는 그룹의 직접 멤버가 됩니다.
동일하거나 낮은 권한인 경우, 사용자는 그룹의 상속 멤버가 됩니다.

자동 멤버 제거#

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

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

Mermaid 다이어그램 (26줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: How group membership of users is determined before sign in if group sync is set up.
subgraph SAML users
SAMLUserA[Sidney Jones]
SAMLUserB[Zhang Wei]
SAMLUserC[Alex Garcia]
SAMLUserD[Charlie Smith]
end
subgraph SAML groups
SAMLGroupA["Group A"] --> SAMLGroupB["Group B"]
SAMLGroupA --> SAMLGroupC["Group C"]
SAMLGroupA --> SAMLGroupD["Group D"]
end
SAMLGroupB --> |Member|SAMLUserA
SAMLGroupB --> |Member|SAMLUserB
SAMLGroupC --> |Member|SAMLUserA
SAMLGroupC --> |Member|SAMLUserB
SAMLGroupD --> |Member|SAMLUserD
SAMLGroupD --> |Member|SAMLUserC

Mermaid 다이어그램 (25줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: User membership for Sidney when she has not signed into group C, and group B has not configured group links.
subgraph GitLab users
  GitLabUserA[Sidney Jones]
  GitLabUserB[Zhang Wei]
  GitLabUserC[Alex Garcia]
  GitLabUserD[Charlie Smith]
end

subgraph GitLab groups
GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
end
GitLabGroupB --> |Member|GitLabUserA
GitLabGroupC --> |Member|GitLabUserB
GitLabGroupC --> |Member|GitLabUserC
GitLabGroupD --> |Member|GitLabUserC
GitLabGroupD --> |Member|GitLabUserD

Mermaid 다이어그램 (23줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: How membership of Alex Garcia works once she has signed into a group that has group links enabled.
subgraph GitLab users
GitLabUserA[Sidney Jones]
GitLabUserB[Zhang Wei]
GitLabUserC[Alex Garcia]
GitLabUserD[Charlie Smith]
end
subgraph GitLab groups after Alex Garcia signs in
GitLabGroupA[Group A]
GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
end
GitLabGroupB --> |Member|GitLabUserA
GitLabGroupC --> |Member|GitLabUserB
GitLabGroupD --> |Member|GitLabUserC
GitLabGroupD --> |Member|GitLabUserD

SAML 그룹 동기화 구성#

SAML 응답에 groups 속성이 포함되어 있고 AttributeValue 값이 GitLab의 SAML 그룹 이름과 일치합니다.
모든 그룹이 GitLab에서 제거되어 그룹 동기화를 비활성화합니다.

SAML 그룹 동기화를 구성하려면:

GitLab.com 그룹용 SAML SSO를 참조하십시오.
SAML ID 제공자가 Groups 또는 groups라는 속성 문을 전송하는지 확인합니다.

SAML 그룹 동기화를 구성하려면:

SAML OmniAuth 제공자를 구성합니다.

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"
    }
  }
]

<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에 대한 예시 구성을 참조하십시오.

SAML 그룹 링크 구성#

SAML 그룹 동기화는 하나 이상의 SAML 그룹 링크가 있는 그룹만 관리합니다.

사전 요구사항:

GitLab Self-Managed 인스턴스에 SAML 그룹 동기화가 구성되어 있어야 합니다.

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

하나 이상의 SAML 그룹 링크를 구성하여 SAML IdP 그룹 이름을 GitLab 권한에 매핑할 수 있습니다.
SAML IdP 그룹의 멤버는 다음 SAML 로그인 시 GitLab 그룹의 멤버로 추가됩니다.
그룹 멤버십은 사용자가 SAML을 사용하여 로그인할 때마다 평가됩니다.
SAML 그룹 링크는 최상위 그룹 또는 모든 하위 그룹에 대해 구성할 수 있습니다.
SAML 그룹 링크가 생성된 다음 제거된 경우:
- 다른 SAML 그룹 링크가 구성되어 있으면, 제거된 그룹 링크에 있던 사용자는 동기화 중에 자동으로 그룹에서 제거됩니다.
- 다른 SAML 그룹 링크가 구성되어 있지 않으면, 사용자는 동기화 중에도 그룹에 남아 있습니다. 해당 사용자는 그룹에서 수동으로 제거해야 합니다.

SAML 그룹을 연결하려면:

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

GitLab Duo 시트 할당 관리#

히스토리

GitLab 17.8의 GitLab.com에 saml_groups_duo_pro_add_on_assignment라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
GitLab 18.0의 GitLab Self-Managed에 도입되었습니다.

사전 요구사항:

활성 GitLab Duo 애드온 구독

SAML 그룹 동기화는 IdP 그룹 멤버십을 기반으로 GitLab Duo 시트 할당 및 제거를 관리할 수 있습니다. 구독에 남은 시트가 있을 때만 시트가 할당됩니다.

GitLab.com에 대해 구성하려면:

SAML 그룹 링크를 구성할 때 이 그룹의 사용자에게 GitLab Duo 시트 할당 체크박스를 선택합니다.
저장을 선택합니다.
GitLab Duo Pro 또는 GitLab Duo Enterprise 시트가 할당되어야 하는 모든 SAML 사용자에 대한 추가 그룹 링크를 추가하기 위해 반복합니다. 이 설정이 활성화된 그룹 링크와 일치하지 않는 ID 제공자 그룹 멤버십을 가진 사용자의 경우 GitLab Duo 시트가 할당 해제됩니다.

이 체크박스는 활성 GitLab Duo 애드온 구독이 없는 그룹에는 표시되지 않습니다.

Self-Managed에 대해 구성하려면:

SAML OmniAuth 제공자를 구성합니다.

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name",
    groups_attribute: 'Groups',
    duo_add_on_groups: ['Developers', 'Freelancers'],
    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"
    }
  }
]

Microsoft Azure Active Directory 통합#

히스토리

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

Note

Microsoft는 Azure Active Directory(AD)가 Entra ID로 이름이 변경되고 있다고 발표했습니다.

Microsoft Azure를 사용한 그룹 동기화 데모는 데모: SAML 그룹 동기화를 참조하십시오.

이 문제를 방지하려면 Azure AD 통합을 사용할 수 있습니다. 이 통합은:

150개 그룹으로 제한되지 않습니다.
Microsoft Graph API를 사용하여 모든 사용자 멤버십을 가져옵니다. Graph API 엔드포인트는 Azure 구성 고유 사용자 식별자(이름 식별자) 속성으로 사용자 개체 ID 또는 userPrincipalName만 허용합니다.
그룹 동기화를 처리할 때 그룹 고유 식별자(예: 12345678-9abc-def0-1234-56789abcde)로 구성된 그룹 링크만 지원합니다.

또는 그룹 클레임을 애플리케이션에 할당된 그룹 옵션을 사용하도록 변경할 수 있습니다.

Azure AD 구성#

통합의 일환으로 GitLab이 Microsoft Graph API와 통신할 수 있도록 허용해야 합니다.

Azure AD를 구성하려면:

Azure Portal에서 Microsoft Entra ID > 앱 등록 > 모든 애플리케이션으로 이동하고 GitLab SAML 애플리케이션을 선택합니다.
기본 정보 아래에 애플리케이션(클라이언트) ID와 디렉토리(테넌트) ID 값이 표시됩니다. GitLab 구성에 필요하므로 이 값들을 복사합니다.
왼쪽 탐색에서 인증서 및 비밀을 선택합니다.
클라이언트 비밀 탭에서 새 클라이언트 비밀을 선택합니다.
1. 설명 텍스트 상자에 설명을 추가합니다.
2. 만료 드롭다운 목록에서 자격 증명의 만료 날짜를 설정합니다. 비밀이 만료되면 자격 증명이 업데이트될 때까지 GitLab 통합이 더 이상 작동하지 않습니다.
3. 자격 증명을 생성하려면 추가를 선택합니다.
4. 자격 증명의 값을 복사합니다. 이 값은 한 번만 표시되며 GitLab 구성에 필요합니다.
왼쪽 탐색에서 API 권한을 선택합니다.
Microsoft Graph > 애플리케이션 권한을 선택합니다.
GroupMember.Read.All 및 User.Read.All 체크박스를 선택합니다.
저장하려면 권한 추가를 선택합니다.
<application_name>에 대한 관리자 동의 부여를 선택한 다음 확인 대화상자에서 예를 선택합니다. 두 권한 모두에 대한 상태 열이 <application_name>에 대해 부여됨이라는 녹색 체크로 변경되어야 합니다.

GitLab 구성#

Azure AD를 구성한 후 GitLab이 Azure AD와 통신할 수 있도록 GitLab을 구성해야 합니다.

다음 표는 구성에 대한 GitLab 설정과 해당 Azure AD 필드를 나열합니다:

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

GitLab.com 그룹에 대해 Azure AD를 구성하려면:

상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다. 이 그룹은 최상위 수준이어야 합니다.
설정 > SAML SSO를 선택합니다.
그룹에 대한 SAML SSO를 구성합니다.
Microsoft Azure 통합 섹션에서 이 그룹에 대한 Microsoft Azure 통합 활성화 체크박스를 선택합니다. 이 섹션은 그룹에 SAML SSO가 구성되고 활성화된 경우에만 표시됩니다.
Azure Portal에서 Azure Active Directory를 구성할 때 이전에 얻은 테넌트 ID, 클라이언트 ID, 클라이언트 비밀을 입력합니다.
선택 사항. 미국 정부용 Azure AD 또는 Azure AD 중국을 사용하는 경우 적절한 로그인 API 엔드포인트와 Graph API 엔드포인트를 입력합니다. 기본값은 대부분의 조직에서 작동합니다.
변경사항 저장을 선택합니다.

사전 요구사항:

관리자 액세스.

GitLab Self-Managed에 대해 구성하려면:

인스턴스에 대한 SAML SSO를 구성합니다.
오른쪽 상단 모서리에서 관리자를 선택합니다.
왼쪽 사이드바에서 설정 > 일반을 선택합니다.
Microsoft Azure 통합 섹션에서 이 그룹에 대한 Microsoft Azure 통합 활성화 체크박스를 선택합니다.
Azure Portal에서 Azure Active Directory를 구성할 때 이전에 얻은 테넌트 ID, 클라이언트 ID, 클라이언트 비밀을 입력합니다.
선택 사항. 미국 정부용 Azure AD 또는 Azure AD 중국을 사용하는 경우 적절한 로그인 API 엔드포인트와 Graph API 엔드포인트를 입력합니다. 기본값은 대부분의 조직에서 작동합니다.
변경사항 저장을 선택합니다.

전역 SAML 그룹 멤버십 잠금#

히스토리

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

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

그룹 또는 하위 그룹을 코드 소유자로 설정할 수 없습니다. 자세한 내용은 전역 그룹 멤버십 잠금과의 비호환성을 참조하십시오.
관리자만 그룹 멤버를 관리하고 액세스 수준을 변경할 수 있습니다.
그룹 멤버는:
- 프로젝트를 다른 그룹과 공유할 수 없습니다.
- 그룹에서 생성된 프로젝트에 멤버를 초대할 수 없습니다.
- SAML 그룹 링크 동기화에 구성된 최상위 그룹의 멤버십을 수정할 수 없습니다.

그룹 멤버십 잠금#

사전 요구사항:

GitLab Self-Managed에 대한 SAML SSO가 구성되어 있어야 합니다.
관리자 액세스.

SAML 그룹 링크 동기화에 멤버십을 잠그려면:

오른쪽 상단 모서리에서 관리자를 선택합니다.
왼쪽 사이드바에서 설정 > 일반을 선택합니다.
가시성 및 액세스 제어 섹션을 확장합니다.
SAML 그룹 링크 동기화에 멤버십 잠금 체크박스를 선택합니다.