SAML 그룹 동기화

요약

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

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 IdP가 SAML 응답에 그룹 속성을 포함하도록 구성해야 합니다. 즉 GitLab은 로그인에 사용된 IdP와 관계없이 SAML 응답의 그룹을 일치시킬 수 있습니다.

예를 들어 SAML1과 SAML2라는 IdP 2 개가 있습니다.

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 그룹의 멤버라면, 그 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 Group Name과 일치합니다.
그룹 동기화를 비활성화하기 위해 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"
    }
  }
]
```
이 예시에서 groups_attribute는 name과 label과 같은 수준에 있는 공급자 해시의 키이며, args 안에 있지 않습니다. args 안에 있으면 그룹 동기화가 실행되지 않습니다. 사용자는 여전히 로그인하고 SAML 응답도 그룹을 담고 있지만, GitLab은 멤버십을 전혀 변경하지 않고 오류도 기록하지 않습니다. 자세한 내용은 SAML 그룹 링크는 있으나 멤버십이 변경되지 않음을 참고합니다.

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 권한이 있는 사용자에게 그룹 Settings > SAML Group Links에 새 메뉴 항목이 표시됩니다.

SAML Group Links를 하나 이상 구성해 SAML IdP 그룹 이름을 GitLab 권한에 매핑할 수 있습니다.
SAML IdP 그룹의 멤버는 다음 SAML 로그인 시 GitLab 그룹의 멤버로 추가됩니다.
그룹 멤버십은 사용자가 SAML로 로그인할 때마다 평가됩니다.
SAML Group Links는 최상위 그룹이나 모든 하위 그룹에 구성할 수 있습니다.
SAML 그룹 링크를 만든 뒤 제거했을 때는 다음과 같습니다.
- 다른 SAML 그룹 링크가 구성돼 있으면, 제거된 그룹 링크에 있던 사용자는 동기화 중에 그룹에서 자동으로 제거됩니다.
- 다른 SAML 그룹 링크가 구성돼 있지 않으면, 사용자는 동기화 중에도 그룹에 남습니다. 그 사용자는 그룹에서 직접 제거해야 합니다.

SAML 그룹을 연결하려면 다음과 같이 합니다.

SAML Group Name에 해당 saml:AttributeValue의 값을 입력합니다. SAML Group Name은 대소문자를 구분하며 SAML 응답에서 전송되는 값과 정확히 일치해야 합니다.
Access Level에서 기본 권한 또는 커스텀 멤버 권한을 선택합니다.
Save를 선택합니다.
필요하다면 반복해서 그룹 링크를 더 추가합니다.

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 그룹 링크를 구성할 때 Assign GitLab Duo seats to users in this group 체크박스를 선택합니다.
Save를 선택합니다.
GitLab Duo Pro 또는 GitLab Duo Enterprise 시트를 배정해야 하는 모든 SAML 사용자에 대해 반복해서 그룹 링크를 더 추가합니다. 이 설정이 활성화된 그룹 링크와 ID 공급자 그룹 멤버십이 일치하지 않는 사용자는 GitLab Duo 시트 배정이 해제됩니다.

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

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

Note

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

Microsoft Azure를 사용한 그룹 동기화 데모는 데모: SAML Group Sync를 참고합니다.

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

이 문제를 피하려면 Azure AD 통합을 사용할 수 있습니다. 이 통합은 다음과 같습니다.

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

또는 그룹 클레임을 Groups assigned to the application 옵션을 사용하도록 변경할 수 있습니다.

Azure AD 구성#

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

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를 선택합니다.
**Grant admin consent for <application_name>**을 선택한 다음 확인 대화 상자에서 Yes를 선택합니다. 두 권한의 Status 칼럼이 **Granted for <application_name>**이라는 녹색 체크로 바뀌어야 합니다.

GitLab 구성#

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

이 구성에서는 사용자가 SAML로 로그인하고 Azure가 응답에 group 클레임을 전송하면, GitLab 이 Microsoft Graph API를 호출해 사용자의 그룹 멤버십을 가져오는 그룹 동기화 job을 시작합니다. 그런 다음 SAML Group Links에 따라 GitLab 그룹 멤버십이 업데이트됩니다.

다음 표는 구성에 사용하는 GitLab 설정과 대응하는 Azure AD 필드입니다.

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

GitLab.com 그룹에 Azure AD를 구성하려면 다음과 같이 합니다.

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다. 이 그룹은 최상위 그룹이어야 합니다.
Settings > SAML SSO를 선택합니다.
그룹의 SAML SSO를 구성합니다.
Microsoft Azure integration 섹션에서 Enable Microsoft Azure integration for this group 체크박스를 선택합니다. 이 섹션은 그룹에 SAML SSO가 구성되고 활성화된 경우에만 표시됩니다.
Azure Portal에서 Azure Active Directory를 구성할 때 앞서 얻은 Tenant ID, Client ID, Client secret을 입력합니다.
선택 사항. 미국 정부용 Azure AD 나 Azure AD 중국을 사용한다면 적절한 Login API endpoint와 Graph API endpoint를 입력합니다. 기본값은 대부분의 조직에서 동작합니다.
Save changes를 선택합니다.

사전 요구 사항:

관리자 접근 권한.

GitLab Self-Managed에서 구성하려면 다음과 같이 합니다.

인스턴스의 SAML SSO를 구성합니다.
오른쪽 위에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Microsoft Azure integration 섹션에서 Enable Microsoft Azure integration for this group 체크박스를 선택합니다.
Azure Portal에서 Azure Active Directory를 구성할 때 앞서 얻은 Tenant ID, Client ID, Client secret을 입력합니다.
선택 사항. 미국 정부용 Azure AD 나 Azure AD 중국을 사용한다면 적절한 Login API endpoint와 Graph API endpoint를 입력합니다. 기본값은 대부분의 조직에서 동작합니다.
Save changes를 선택합니다.

전역 SAML 그룹 멤버십 잠금#

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

전역 그룹 멤버십 잠금이 활성화되면 다음과 같습니다.

그룹이나 하위 그룹을 Code Owner로 사용하려면 전역 그룹 멤버십 잠금과의 비호환성을 참고합니다.
관리자만 그룹 멤버를 관리하고 액세스 수준을 변경할 수 있습니다.
그룹 멤버는 다음을 할 수 없습니다.
- 프로젝트를 다른 그룹과 공유
- 그룹에서 만든 프로젝트에 멤버 초대
- SAML Group Links 동기화를 구성한 최상위 그룹의 멤버십 수정

그룹 멤버십 잠금#

사전 요구 사항:

GitLab Self-Managed 용 SAML SSO가 구성돼 있어야 합니다.
관리자 접근 권한.

SAML Group Links 동기화에 멤버십을 잠그려면 다음과 같이 합니다.

오른쪽 위에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility and access controls 섹션을 확장합니다.
Lock memberships to SAML Group Links synchronization 체크박스를 선택합니다.

SAML 그룹 동기화

GitLab v19.5

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

원문 보기

번역일: 2026-10-15

요약

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

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

권한 우선순위#

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

다중 SAML IdP#

사용자가 로그인하면 GitLab은 다음을 수행합니다.

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

예를 들어 SAML1과 SAML2라는 IdP 2 개가 있습니다.

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

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

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 Group Name과 일치합니다.
그룹 동기화를 비활성화하기 위해 GitLab에서 모든 그룹을 제거합니다.

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"
    }
  }
]
```
이 예시에서 groups_attribute는 name과 label과 같은 수준에 있는 공급자 해시의 키이며, args 안에 있지 않습니다. args 안에 있으면 그룹 동기화가 실행되지 않습니다. 사용자는 여전히 로그인하고 SAML 응답도 그룹을 담고 있지만, GitLab은 멤버십을 전혀 변경하지 않고 오류도 기록하지 않습니다. 자세한 내용은 SAML 그룹 링크는 있으나 멤버십이 변경되지 않음을 참고합니다.

<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 권한이 있는 사용자에게 그룹 Settings > SAML Group Links에 새 메뉴 항목이 표시됩니다.

SAML Group Links를 하나 이상 구성해 SAML IdP 그룹 이름을 GitLab 권한에 매핑할 수 있습니다.
SAML IdP 그룹의 멤버는 다음 SAML 로그인 시 GitLab 그룹의 멤버로 추가됩니다.
그룹 멤버십은 사용자가 SAML로 로그인할 때마다 평가됩니다.
SAML Group Links는 최상위 그룹이나 모든 하위 그룹에 구성할 수 있습니다.
SAML 그룹 링크를 만든 뒤 제거했을 때는 다음과 같습니다.
- 다른 SAML 그룹 링크가 구성돼 있으면, 제거된 그룹 링크에 있던 사용자는 동기화 중에 그룹에서 자동으로 제거됩니다.
- 다른 SAML 그룹 링크가 구성돼 있지 않으면, 사용자는 동기화 중에도 그룹에 남습니다. 그 사용자는 그룹에서 직접 제거해야 합니다.

SAML 그룹을 연결하려면 다음과 같이 합니다.

SAML Group Name에 해당 saml:AttributeValue의 값을 입력합니다. SAML Group Name은 대소문자를 구분하며 SAML 응답에서 전송되는 값과 정확히 일치해야 합니다.
Access Level에서 기본 권한 또는 커스텀 멤버 권한을 선택합니다.
Save를 선택합니다.
필요하다면 반복해서 그룹 링크를 더 추가합니다.

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 그룹 링크를 구성할 때 Assign GitLab Duo seats to users in this group 체크박스를 선택합니다.
Save를 선택합니다.
GitLab Duo Pro 또는 GitLab Duo Enterprise 시트를 배정해야 하는 모든 SAML 사용자에 대해 반복해서 그룹 링크를 더 추가합니다. 이 설정이 활성화된 그룹 링크와 ID 공급자 그룹 멤버십이 일치하지 않는 사용자는 GitLab Duo 시트 배정이 해제됩니다.

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

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

Note

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

Microsoft Azure를 사용한 그룹 동기화 데모는 데모: SAML Group Sync를 참고합니다.

이 문제를 피하려면 Azure AD 통합을 사용할 수 있습니다. 이 통합은 다음과 같습니다.

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

또는 그룹 클레임을 Groups assigned to the application 옵션을 사용하도록 변경할 수 있습니다.

Azure AD 구성#

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

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를 선택합니다.
**Grant admin consent for <application_name>**을 선택한 다음 확인 대화 상자에서 Yes를 선택합니다. 두 권한의 Status 칼럼이 **Granted for <application_name>**이라는 녹색 체크로 바뀌어야 합니다.

GitLab 구성#

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

다음 표는 구성에 사용하는 GitLab 설정과 대응하는 Azure AD 필드입니다.

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

GitLab.com 그룹에 Azure AD를 구성하려면 다음과 같이 합니다.

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다. 이 그룹은 최상위 그룹이어야 합니다.
Settings > SAML SSO를 선택합니다.
그룹의 SAML SSO를 구성합니다.
Microsoft Azure integration 섹션에서 Enable Microsoft Azure integration for this group 체크박스를 선택합니다. 이 섹션은 그룹에 SAML SSO가 구성되고 활성화된 경우에만 표시됩니다.
Azure Portal에서 Azure Active Directory를 구성할 때 앞서 얻은 Tenant ID, Client ID, Client secret을 입력합니다.
선택 사항. 미국 정부용 Azure AD 나 Azure AD 중국을 사용한다면 적절한 Login API endpoint와 Graph API endpoint를 입력합니다. 기본값은 대부분의 조직에서 동작합니다.
Save changes를 선택합니다.

사전 요구 사항:

관리자 접근 권한.

GitLab Self-Managed에서 구성하려면 다음과 같이 합니다.

인스턴스의 SAML SSO를 구성합니다.
오른쪽 위에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Microsoft Azure integration 섹션에서 Enable Microsoft Azure integration for this group 체크박스를 선택합니다.
Azure Portal에서 Azure Active Directory를 구성할 때 앞서 얻은 Tenant ID, Client ID, Client secret을 입력합니다.
선택 사항. 미국 정부용 Azure AD 나 Azure AD 중국을 사용한다면 적절한 Login API endpoint와 Graph API endpoint를 입력합니다. 기본값은 대부분의 조직에서 동작합니다.
Save changes를 선택합니다.

전역 SAML 그룹 멤버십 잠금#

전역 그룹 멤버십 잠금이 활성화되면 다음과 같습니다.

그룹이나 하위 그룹을 Code Owner로 사용하려면 전역 그룹 멤버십 잠금과의 비호환성을 참고합니다.
관리자만 그룹 멤버를 관리하고 액세스 수준을 변경할 수 있습니다.
그룹 멤버는 다음을 할 수 없습니다.
- 프로젝트를 다른 그룹과 공유
- 그룹에서 만든 프로젝트에 멤버 초대
- SAML Group Links 동기화를 구성한 최상위 그룹의 멤버십 수정

그룹 멤버십 잠금#

사전 요구 사항:

GitLab Self-Managed 용 SAML SSO가 구성돼 있어야 합니다.
관리자 접근 권한.

SAML Group Links 동기화에 멤버십을 잠그려면 다음과 같이 합니다.

오른쪽 위에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility and access controls 섹션을 확장합니다.
Lock memberships to SAML Group Links synchronization 체크박스를 선택합니다.