GitLab에서 SAML 지원 구성
IdP 설정하기
SAML 그룹 멤버십에 따라 사용자 구성
SAML 그룹 동기화를 자동으로 관리
이중 인증 우회
응답 서명 검증
- idp_cert_fingerprint 사용
- idp_cert 사용하기
SAML 설정 사용자 정의
Assertion encryption (optional)
SAML 인증 요청 서명 (선택 사항)
SAML을 통한 사용자 생성 시 비밀번호 생성
기존 사용자에 대한 SAML ID 링크
자체 관리 인스턴스에서 그룹 SAML SSO 구성
SAML 앱에 대한 추가 구성
용어집
문제 해결

self-managed GitLab 인스턴스를 위한 SAML SSO

Tier: Free, Premium, Ultimate

Offering: Self-managed

이 페이지에서는 self-managed GitLab 인스턴스에 대한 인스턴스 전체 SAML 단일 로그인(SSO) 설정 방법을 설명합니다.

GitLab을 SAML 서비스 제공자(SP)로 설정할 수 있습니다. 이를 통해 GitLab은 Okta와 같은 SAML ID 공급자로부터 주장을 수신하여 사용자를 인증할 수 있습니다.

GitLab.com에서 SAML을 설정하려면 GitLab.com 그룹의 SAML SSO를 참조하세요.

다음에 대한 자세한 정보:

OmniAuth 공급자 설정은 OmniAuth 문서를 참조하세요.
일반적으로 사용되는 용어는 용어집를 참조하세요.

GitLab에서 SAML 지원 구성

Linux 패키지 (Omnibus)

GitLab이 HTTPS로 구성되었는지 확인합니다.
공통 설정을 구성하여 saml을 단일 로그인 제공자로 추가합니다. 이렇게 하면 기존 GitLab 계정이 없는 사용자에 대한 Just-In-Time 계정 프로비저닝이 활성화됩니다.
사용자가 SAML을 사용하여 먼저 수동으로 계정을 생성하지 않고 가입할 수 있도록 /etc/gitlab/gitlab.rb를 편집합니다:
```
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
```
선택 사항. 사용자의 이메일 주소가 일치하는 경우 첫 번째 SAML 로그인을 기존 GitLab 사용자와 자동으로 연결할 수 있습니다. 이렇게 하려면 /etc/gitlab/gitlab.rb에 다음 설정을 추가합니다:
```
gitlab_rails['omniauth_auto_link_saml_user'] = true
```
GitLab 계정의 기본 이메일 주소만 SAML 응답의 이메일과 일치합니다.

또는 사용자는 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML ID를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없는 속성을 다음과 같이 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용되는 Email.
사용자가 이러한 속성을 변경할 수 있다면, 다른 인증된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 설정하는 방법은 SAML ID 공급자 문서를 참조하세요.
/etc/gitlab/gitlab.rb를 편집하고 공급자 구성 추가:
```
gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "공급자 이름", # 로그인 버튼의 선택적 레이블, 기본값은 "Saml"
    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"
    }
  }
]
```
여기서:
- assertion_consumer_service_url: GitLab HTTPS 엔드포인트 (귀하의 GitLab 설치의 HTTPS URL에 /users/auth/saml/callback을 추가합니다).
- idp_cert_fingerprint: 귀하의 ID 공급자 값. SHA1 지문이어야 합니다. 이러한 값에 대한 자세한 정보는 OmniAuth SAML 문서를 참조하세요.
  
  다른 구성 설정에 대한 자세한 정보는 귀하의 ID 공급자에서 SAML 구성을 참조하세요.
- idp_sso_target_url: 귀하의 ID 공급자 값입니다.
- issuer: ID 공급자에 응용 프로그램을 식별하는 고유한 이름으로 변경합니다.
- name_identifier_format: 귀하의 ID 공급자 값입니다.
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

GitLab이 HTTPS로 구성되었는지 확인합니다.
공통 설정을 구성하여 saml을 단일 로그인 제공자로 추가합니다. 기존 GitLab 계정이 없는 사용자에 대한 Just-In-Time 계정 프로비저닝이 활성화됩니다.

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

사용자가 SAML을 사용하여 수동으로 계정을 생성하지 않고 가입할 수 있도록 gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      enabled: true
      allowSingleSignOn: ['saml']
      blockAutoCreatedUsers: false

선택 사항. 사용자의 이메일 주소가 일치하는 경우 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다. gitlab_values.yaml에 다음 설정을 추가합니다:
```
global:
  appConfig:
    omniauth:
      autoLinkSamlUser: true
```
또는 사용자는 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML ID를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없는 속성을 다음과 같이 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용되는 Email.
사용자가 이러한 속성을 변경할 수 있다면, 다른 인증된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 설정하는 방법은 SAML ID 공급자 문서를 참조하세요.
다음 콘텐츠를 saml.yaml라는 파일에 넣어 Kubernetes Secret로 사용합니다:
```
name: 'saml'
label: '공급자 이름' # 로그인 버튼의 선택적 레이블, 기본값은 "Saml"
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'
```
여기서:
- assertion_consumer_service_url: GitLab HTTPS 엔드포인트 (귀하의 GitLab 설치의 HTTPS URL에 /users/auth/saml/callback을 추가합니다).
- idp_cert_fingerprint: 귀하의 ID 공급자 값. SHA1 지문이어야 합니다. 이러한 값에 대한 자세한 정보는 OmniAuth SAML 문서를 참조하세요.
  
  다른 구성 설정에 대한 자세한 정보는 귀하의 ID 공급자에서 SAML 구성을 참조하세요.
- idp_sso_target_url: 귀하의 ID 공급자 값입니다.
- issuer: ID 공급자에 응용 프로그램을 식별하는 고유한 이름으로 변경합니다.
- name_identifier_format: 귀하의 ID 공급자 값입니다.

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

gitlab_values.yaml를 편집하고 공급자 구성을 추가합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

GitLab이 HTTPS로 구성되었는지 확인합니다.
공통 설정을 구성하여 saml을 단일 로그인 제공자로 추가합니다. 기존 GitLab 계정이 없는 사용자에 대한 Just-In-Time 계정 프로비저닝이 활성화됩니다.

사용자가 SAML을 사용하여 수동으로 계정을 생성하지 않고 가입할 수 있도록 docker-compose.yml를 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
        gitlab_rails['omniauth_block_auto_created_users'] = false

선택 사항. 사용자의 이메일 주소가 일치하는 경우 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다. docker-compose.yml에 다음 설정을 추가합니다:
```
version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_link_saml_user'] = true
```
또는 사용자는 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML ID를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없는 속성을 다음과 같이 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용되는 Email.
사용자가 이러한 속성을 변경할 수 있다면, 다른 인증된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 설정하는 방법은 SAML ID 공급자 문서를 참조하세요.

docker-compose.yml를 편집하고 공급자 구성을 추가합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          {
            name: "saml",
            label: "공급자 이름", # 로그인 버튼의 선택적 레이블, 기본값은 "Saml"
            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"
            }
          }
        ]

여기서:

assertion_consumer_service_url: GitLab HTTPS 엔드포인트 (귀하의 GitLab 설치의 HTTPS URL에 /users/auth/saml/callback을 추가합니다).
idp_cert_fingerprint: 귀하의 ID 공급자 값. SHA1 지문이어야 합니다. 이러한 값에 대한 자세한 정보는 OmniAuth SAML 문서를 참조하세요.

다른 구성 설정에 대한 자세한 정보는 귀하의 ID 공급자에서 SAML 구성을 참조하세요.
idp_sso_target_url: 귀하의 ID 공급자 값입니다.
issuer: ID 공급자에 응용 프로그램을 식별하는 고유한 이름으로 변경합니다.
name_identifier_format: 귀하의 ID 공급자 값입니다.

파일을 저장하고 GitLab을 리스타트합니다:
```
docker compose up -d
```

소스에서 직접 컴파일

GitLab이 HTTPS로 구성되었는지 확인합니다.
공통 설정을 구성하여 saml을 단일 로그인 제공자로 추가합니다. 기존 GitLab 계정이 없는 사용자에 대한 Just-In-Time 계정 프로비저닝이 활성화됩니다.
사용자가 SAML을 사용하여 수동으로 계정을 생성하지 않고 가입할 수 있도록 /home/git/gitlab/config/gitlab.yml를 편집합니다:
```
production: &base
  omniauth:
    enabled: true
    allow_single_sign_on: ["saml"]
    block_auto_created_users: false
```
선택 사항. 사용자의 이메일 주소가 일치하는 경우 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다. /home/git/gitlab/config/gitlab.yml에 다음 설정을 추가합니다:
```
production: &base
  omniauth:
    auto_link_saml_user: true
```
또는 사용자는 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML ID를 기존 GitLab 계정에 수동으로 연결할 수 있습니다.
SAML 사용자가 변경할 수 없는 속성을 다음과 같이 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용되는 Email.
사용자가 이러한 속성을 변경할 수 있다면, 다른 인증된 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 설정하는 방법은 SAML ID 공급자 문서를 참조하세요.
/home/git/gitlab/config/gitlab.yml를 편집하고 공급자 구성을 추가합니다:
```
omniauth:
  providers:
    - {
      name: 'saml',
      label: '공급자 이름', # 로그인 버튼의 선택적 레이블, 기본값은 "Saml"
      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'
      }
    }
```
여기서:
- assertion_consumer_service_url: GitLab HTTPS 엔드포인트 (귀하의 GitLab 설치의 HTTPS URL에 /users/auth/saml/callback을 추가합니다).
- idp_cert_fingerprint: 귀하의 ID 공급자 값. SHA1 지문이어야 합니다. 이러한 값에 대한 자세한 정보는 OmniAuth SAML 문서를 참조하세요.
  
  다른 구성 설정에 대한 자세한 정보는 귀하의 ID 공급자에서 SAML 구성을 참조하세요.
- idp_sso_target_url: 귀하의 ID 공급자 값입니다.
- issuer: ID 공급자에 응용 프로그램을 식별하는 고유한 이름으로 변경합니다.
- name_identifier_format: 귀하의 ID 공급자 값입니다.

파일을 저장하고 GitLab을 리스타트합니다:

# systemd가 실행되는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init이 실행되는 시스템의 경우
sudo service gitlab restart

SAML IdP에 GitLab 등록하기

issuer에 지정된 애플리케이션 이름을 사용하여 SAML IdP에 GitLab SP를 등록합니다.
IdP에 구성 정보를 제공하기 위해 애플리케이션의 메타데이터 URL을 생성합니다. GitLab의 메타데이터 URL을 만들려면 HTTPS URL 끝에 users/auth/saml/metadata를 추가합니다. 예를 들어:
```
https://gitlab.example.com/users/auth/saml/metadata
```
최소한 IdP는 사용자의 이메일 주소를 email 또는 mail을 사용하여 포함하는 클레임을 제공해야 합니다. 다른 사용 가능한 클레임에 대한 정보는 주장 구성을 참조하세요.
로그인 페이지에는 이제 일반 로그인 양식 아래에 SAML 아이콘이 있어야 합니다. 아이콘을 선택하여 인증 프로세스를 시작합니다. 인증이 성공하면 GitLab로 돌아와 로그인됩니다.

IdP에서 SAML 구성하기

IdP에서 SAML 애플리케이션을 구성하려면 최소한 다음 정보를 필요로 합니다:

주장 소비 서비스 URL.
발급자.
NameID.
이메일 주소 클레임.

예시 구성을 보려면 신원 제공자 설정을 참조하세요.

IdP에서 추가 구성이 필요할 수 있습니다. 자세한 내용은 IdP에서 SAML 앱에 대한 추가 구성을 참조하세요.

여러 SAML IdP를 사용하도록 GitLab 구성하기

GitLab을 여러 SAML IdP를 사용하도록 구성할 수 있습니다:

각 제공자는 args에서 설정된 이름 집합과 일치하는 고유한 이름을 가져야 합니다.
제공자의 이름은 다음과 같이 사용됩니다:
- 제공자 이름을 기반으로 한 속성의 OmniAuth 구성에서. 예를 들어, allowBypassTwoFactor, allowSingleSignOn, 및 syncProfileFromProvider.
- 각 기존 사용자와 추가 ID로 연관됩니다.
assertion_consumer_service_url이 제공자 이름과 일치해야 합니다.
strategy_class는 제공자 이름에서 유추될 수 없기 때문에 명시적으로 설정해야 합니다.

여러 SAML IdP를 구성할 때 SAML 그룹 링크가 작동하도록 하려면 모든 SAML IdP를 SAML 응답에 그룹 속성을 포함하도록 구성해야 합니다. 자세한 내용은 SAML 그룹 링크를 참조하세요.

여러 SAML IdP를 설정하려면:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml', # 이 값은 다음 이름 구성 매개변수와 일치해야 합니다
    label: 'Provider 1' # UI에서 두 버튼과 공급자를 구별합니다
    args: {
            name: 'saml', # 이것은 필수이며 제공자 이름과 일치해야 합니다
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL은 제공자의 이름과 일치해야 합니다
            strategy_class: 'OmniAuth::Strategies::SAML',
            ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다
          },
  },
  {
    name: 'saml_2', # 이 값은 다음 이름 구성 매개변수와 일치해야 합니다
    label: 'Provider 2' # UI에서 두 버튼과 공급자를 구별합니다
    args: {
            name: 'saml_2', # 이것은 필수이며 제공자 이름과 일치해야 합니다
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL은 제공자의 이름과 일치해야 합니다
            strategy_class: 'OmniAuth::Strategies::SAML',
            ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다
          },
  }
]

사용자가 두 제공자 중 하나에서 수동으로 계정을 생성하지 않고도 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가합니다:

gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

첫 번째 SAML 제공자를 위한 Kubernetes Secret로 사용될 saml.yaml라는 파일에 다음 내용을 입력합니다:

name: 'saml' # 적어도 하나의 제공자는 'saml'로 이름이 지정되어야 합니다
label: 'Provider 1' # UI에서 두 버튼과 공급자를 구별합니다
args:
  name: 'saml' # 이것은 필수이며 제공자 이름과 일치해야 합니다
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL은 제공자의 이름과 일치해야 합니다
  strategy_class: 'OmniAuth::Strategies::SAML' # 필수
  ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다

두 번째 SAML 제공자를 위한 Kubernetes Secret로 사용될 saml_2.yaml라는 파일에 다음 내용을 입력합니다:

name: 'saml_2'
label: 'Provider 2' # UI에서 두 버튼과 공급자를 구별합니다
args:
  name: 'saml_2' # 이것은 필수이며 제공자 이름과 일치해야 합니다
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL은 제공자의 이름과 일치해야 합니다
  strategy_class: 'OmniAuth::Strategies::SAML' # 필수
  ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다

선택사항입니다. 동일한 단계를 따라 추가 SAML 제공자를 설정합니다.

Kubernetes Secrets를 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml \
   --from-file=saml=saml.yaml \
   --from-file=saml_2=saml_2.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml
          key: saml
        - secret: gitlab-saml
          key: saml_2

사용자가 두 제공자 중 하나에서 수동으로 계정을 생성하지 않고도 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가합니다:

global:
  appConfig:
    omniauth:
      allowSingleSignOn: ['saml', 'saml_2']

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml1']
        gitlab_rails['omniauth_providers'] = [
          {
            name: 'saml', # 이 값은 다음 이름 구성 매개변수와 일치해야 합니다
            label: 'Provider 1' # UI에서 두 버튼과 공급자를 구별합니다
            args: {
                    name: 'saml', # 이것은 필수이며 제공자 이름과 일치해야 합니다
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL은 제공자의 이름과 일치해야 합니다
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다
                  },
          },
          {
            name: 'saml_2', # 이 값은 다음 이름 구성 매개변수와 일치해야 합니다
            label: 'Provider 2' # UI에서 두 버튼과 공급자를 구별합니다
            args: {
                    name: 'saml_2', # 이것은 필수이며 제공자 이름과 일치해야 합니다
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL은 제공자의 이름과 일치해야 합니다
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다
                  },
          }
        ]

사용자가 두 제공자 중 하나에서 수동으로 계정을 생성하지 않고도 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

자가 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml를 편집합니다:

production: &base
  omniauth:
    providers:
      - {
        name: 'saml', # 이 값은 다음 이름 구성 매개변수와 일치해야 합니다
        label: 'Provider 1' # UI에서 두 버튼과 공급자를 구별합니다
        args: {
          name: 'saml', # 이것은 필수이며 제공자 이름과 일치해야 합니다
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL은 제공자의 이름과 일치해야 합니다
          strategy_class: 'OmniAuth::Strategies::SAML',
          ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다
        },
      }
      - {
        name: 'saml_2', # 이 값은 다음 이름 구성 매개변수와 일치해야 합니다
        label: 'Provider 2' # UI에서 두 버튼과 공급자를 구별합니다
        args: {
          name: 'saml_2', # 이것은 필수이며 제공자 이름과 일치해야 합니다
          strategy_class: 'OmniAuth::Strategies::SAML',
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL은 제공자의 이름과 일치해야 합니다
          ... # 단일 공급자와 유사한 모든 필수 인수를 여기에 입력합니다
        },
      }

사용자가 두 제공자 중 하나에서 수동으로 계정을 생성하지 않고도 SAML을 사용하여 가입할 수 있도록 하려면 구성에 다음 값을 추가합니다:

production: &base
  omniauth:
    allow_single_sign_on: ["saml", "saml_2"]

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 실행하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 실행하는 시스템의 경우
sudo service gitlab restart

IdP 설정하기

GitLab에서 SAML을 지원하므로 다양한 IdP를 통해 GitLab에 로그인할 수 있습니다.

GitLab은 Okta와 Google Workspace IdP 설정에 대한 내용을 안내 목적으로 제공합니다. 이들 IdP 구성에 대해 궁금한 점이 있다면, 제공자의 지원팀에 문의하세요.

Okta 설정하기

Okta 관리 섹션에서 Applications를 선택합니다.
앱 화면에서 Create App Integration를 선택한 후 다음 화면에서 SAML 2.0을 선택합니다.
선택 사항. GitLab Press에서 로고를 선택하고 추가합니다.
로고를 잘라내고 크기를 조정해야 합니다.
SAML 일반 구성 설정을 완료합니다. 다음을 입력하세요:
- "Single sign-on URL": Assertion consumer service URL을 사용합니다.
- "Audience URI": 발급자를 사용합니다.
- NameID.
- Assertions.
피드백 섹션에 고객이며 내부용 앱을 생성 중임을 입력합니다.
새 앱 프로필 상단에서 SAML 2.0 configuration instructions를 선택합니다.
Identity Provider Single Sign-On URL을 기록합니다. 이 URL을 GitLab 구성 파일의 idp_sso_target_url에 사용합니다.
Okta에서 로그아웃하기 전에 사용자와 그룹을 추가했는지 확인합니다.

Google Workspace 설정하기

사전 요구 사항:

Google Workspace Super Admin 계정에 액세스할 수 있는지 확인합니다.

Google Workspace를 설정하기 위해:

다음 정보를 사용하고 Google Workspace에서 사용자 지정 SAML 애플리케이션 설정 지침을 따릅니다.

	일반 값	설명
SAML 앱 이름	GitLab	다른 이름도 가능합니다.
ACS URL	`https://<GITLAB_DOMAIN>/users/auth/saml/callback`	Assertion Consumer Service URL.
`GITLAB_DOMAIN`	`gitlab.example.com`	GitLab 인스턴스 도메인입니다.
Entity ID	`https://gitlab.example.com`	SAML 애플리케이션에 고유한 값입니다. GitLab 구성의 `issuer`로 설정합니다.
Name ID 형식	`EMAIL`	필수 값입니다. `name_identifier_format`이라고도 알려져 있습니다.
Name ID	기본 이메일 주소	본인의 이메일 주소입니다. 해당 주소로 보내는 내용이 누군가에게 도달하는지 확인하세요.
이름	`first_name`	이름입니다. GitLab과 통신하기 위해 필수 값입니다.
성	`last_name`	성입니다. GitLab과 통신하기 위해 필수 값입니다.

다음 SAML 속성 매핑을 설정합니다:

Google 디렉토리 속성	앱 속성
기본 정보 > 이메일	`email`
기본 정보 > 이름	`first_name`
기본 정보 > 성	`last_name`

이 정보 중 일부는 GitLab에서 SAML 지원 구성 시 사용할 수 있습니다.

Google Workspace SAML 애플리케이션을 구성할 때 다음 정보를 기록합니다:

	값	설명
SSO URL	달라질 수 있음	Google Identity Provider 세부정보입니다. GitLab `idp_sso_target_url` 설정에 맞게 설정하십시오.
인증서	다운로드 가능	`openssl x509 -in <your_certificate.crt> -noout -fingerprint -sha1`를 실행하여 `idp_cert_fingerprint` 설정에 사용할 수 있는 SHA1 지문을 생성합니다.

Google Workspace 관리자는 또한 IdP 메타데이터, Entity ID 및 SHA-256 지문을 제공합니다. 그러나 GitLab은 Google Workspace SAML 애플리케이션에 연결하는 데 이 정보를 필요로 하지 않습니다.

다른 IdP 설정하기

일부 IdP는 SAML 구성에서 IdP로 사용하는 방법에 대한 문서를 제공합니다.

예를 들어:

SAML 구성에서 IdP를 구성하는 데 질문이 있는 경우 제공업체의 지원에 문의하십시오.

어설션 구성하기

Microsoft Azure/Entra ID 속성 지원이 GitLab 16.7에서 도입되었습니다.

참고: 속성은 대소문자를 구분합니다.

필드	지원되는 기본 키
이메일(필수)	`email`, `mail`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/emailaddress`
전체 이름	`name`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/name`
이름	`first_name`, `firstname`, `firstName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/givenname`
성	`last_name`, `lastname`, `lastName`, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`, `http://schemas.microsoft.com/ws/2008/06/identity/claims/surname`

GitLab이 SAML SSO 제공자로부터 SAML 응답을 수신하면 다음 값을 attribute name 필드에서 찾습니다:

"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
firstname
lastname
email

이 값을 attribute Name 필드에 정확하게 포함해야 GitLab이 SAML 응답을 구문 분석할 수 있습니다. 예를 들어, GitLab은 다음 SAML 응답 조각을 구문 분석할 수 있습니다:

이것은 Name 속성이 이전 테이블의 필수 값 중 하나로 설정되어 있기 때문에 수락됩니다.

         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
             <AttributeValue>Alvin</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
             <AttributeValue>Test</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
             <AttributeValue>alvintest@example.com</AttributeValue>
         </Attribute>

이것은 Name 속성이 이전 테이블의 값 중 하나와 일치하기 때문에 수락됩니다.

         <Attribute Name="firstname">
             <AttributeValue>Alvin</AttributeValue>
         </Attribute>
         <Attribute Name="lastname">
             <AttributeValue>Test</AttributeValue>
         </Attribute>
         <Attribute Name="email">
             <AttributeValue>alvintest@example.com</AttributeValue>
         </Attribute>

그러나 GitLab은 다음 SAML 응답 조각을 구문 분석할 수 없습니다:

이것은 Name 속성의 값이 이전 테이블의 지원되는 값 중 하나가 아니기 때문에 수락되지 않습니다.

         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/firstname">
             <AttributeValue>Alvin</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/lastname">
             <AttributeValue>Test</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mail">
             <AttributeValue>alvintest@example.com</AttributeValue>
         </Attribute>

이것은 FriendlyName에 지원되는 값이 있더라도 Name 속성이 그렇지 않기 때문에 실패합니다.

         <Attribute FriendlyName="firstname" Name="urn:oid:2.5.4.42">
             <AttributeValue>Alvin</AttributeValue>
         </Attribute>
         <Attribute FriendlyName="lastname" Name="urn:oid:2.5.4.4">
             <AttributeValue>Test</AttributeValue>
         </Attribute>
         <Attribute FriendlyName="email" Name="urn:oid:0.9.2342.19200300.100.1.3">
             <AttributeValue>alvintest@example.com</AttributeValue>
         </Attribute>

attribute_statements에 대해:

사용자 정의 어설션 구성 예시.
사용자 정의 사용자 이름 속성 구성 방법.

지원되는 어설션의 전체 목록은 OmniAuth SAML gem을 참조하십시오.

SAML 그룹 멤버십에 따라 사용자 구성

다음과 같은 작업을 수행할 수 있습니다:

특정 그룹의 구성원이 되도록 사용자 요구.
그룹 멤버십에 따라 사용자를 외부, 관리자 또는 감사자 역할로 지정.

GitLab은 각 SAML 로그인 시 이러한 그룹을 확인하고 필요에 따라 사용자 속성을 업데이트합니다.

이 기능은 사용자를 GitLab 그룹에 자동으로 추가할 수 없습니다.

이러한 그룹에 대한 지원은 다음에 따라 다릅니다:

귀하의 구독.
GitLab Enterprise Edition (EE)가 설치되었는지 여부.

그룹	Tier	GitLab Enterprise Edition (EE) 전용?
필수	Free, Premium, Ultimate	Yes
외부	Free, Premium, Ultimate	No
관리자	Free, Premium, Ultimate	Yes
감사자	Premium, Ultimate	Yes

사전 요구 사항:

GitLab에 그룹 정보를 어디에서 찾을지 알려야 합니다. 이를 위해 IdP 서버가 일반 SAML 응답과 함께 특정 AttributeStatement를 전송하도록 설정하세요. 예를 들어:

<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

속성의 이름은 사용자가 속한 그룹을 포함해야 합니다. 이러한 그룹을 GitLab에서 찾도록 하려면 SAML 설정에 groups_attribute: 요소를 추가하십시오.

필수 그룹

IdP가 SAML 응답으로 그룹 정보를 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab을 구성하여 다음을 확인하세요:

SAML 응답에서 그룹을 찾을 위치를 groups_attribute 설정을 사용하여 지정.
그룹 또는 사용자에 대한 정보, 그룹 설정을 사용하여 지정.

required_groups 설정을 사용하여 GitLab이 로그인에 필요한 그룹 멤버십을 식별하도록 구성하십시오.

required_groups를 설정하지 않거나 설정을 비워 두면 적절한 인증을 가진 누구나 서비스를 사용할 수 있습니다.

groups_attribute에 지정된 속성이 잘못되었거나 누락된 경우 모든 사용자가 차단됩니다.

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
    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을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

saml.yaml이라는 파일에 다음 내용을 넣어 Kubernetes 비밀로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
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'

Kubernetes 비밀을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

도커

docker-compose.yml를 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             groups_attribute: 'Groups',
             required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
             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을 재시작합니다:
```
docker compose up -d
```

소스에서 직접 컴파일

/home/git/gitlab/config/gitlab.yml를 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: 'Our SAML Provider',
          groups_attribute: 'Groups',
          required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
          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을 재시작합니다:

# systemd를 실행하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 실행하는 시스템의 경우
sudo service gitlab restart

외부 그룹

귀하의 IdP는 SAML 응답에서 그룹 정보를 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab을 구성하여 다음을 식별하십시오:

groups_attribute 설정을 사용하여 SAML 응답에서 그룹을 찾을 위치.
그룹 또는 사용자에 대한 정보, 그룹 설정을 사용하여.

SAML은 external_groups 설정을 기반으로 사용자를 외부 사용자로 자동 식별할 수 있습니다.

노트: groups_attribute에 지정된 속성이 올바르지 않거나 누락되면 사용자는 표준 사용자로 액세스하게 됩니다.

예제 구성:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [

  { name: 'saml',
    label: '우리의 SAML 제공자',
    groups_attribute: 'Groups',
    external_groups: ['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'
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

다음 내용을 saml.yaml라는 파일에 넣어 Kubernetes Secret로 사용합니다:

name: 'saml'
label: '우리의 SAML 제공자'
groups_attribute: 'Groups'
external_groups: ['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'

Kubernetes Secret를 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          { name: 'saml',
            label: '우리의 SAML 제공자',
            groups_attribute: 'Groups',
            external_groups: ['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'
            }
          }
        ]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

직접 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  omniauth:
    providers:
       - { name: 'saml',
           label: '우리의 SAML 제공자',
           groups_attribute: 'Groups',
           external_groups: ['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'
           }
         }

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV 초기화를 사용하는 시스템의 경우
sudo service gitlab restart

관리자 그룹

귀하의 IdP는 SAML 응답에서 그룹 정보를 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab을 구성하여 다음을 식별하십시오:

groups_attribute 설정을 사용하여 SAML 응답에서 그룹을 찾을 위치.
그룹 또는 사용자에 대한 정보, 그룹 설정 사용.

admin_groups 설정을 사용하여 GitLab이 사용자에게 관리자 액세스를 부여하는 그룹을 식별하도록 구성하십시오.

groups_attribute에서 지정된 속성이 잘못되었거나 누락된 경우 사용자는 관리자 액세스를 잃게 됩니다.

예제 구성:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집하십시오:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '우리의 SAML 공급자',
    groups_attribute: 'Groups',
    admin_groups: ['Admins'],
    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을 재구성하십시오:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

다음 내용을 saml.yaml라는 파일에 넣어 Kubernetes Secret로 사용하십시오:

name: 'saml'
label: '우리의 SAML 공급자'
groups_attribute: 'Groups'
admin_groups: ['Admins']
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'

Kubernetes Secret를 생성하십시오:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보내십시오:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집하십시오:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용하십시오:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml를 편집하십시오:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '우리의 SAML 공급자',
             groups_attribute: 'Groups',
             admin_groups: ['Admins'],
             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을 재시작하십시오:
```
docker compose up -d
```

소스 컴파일 (자체)

/home/git/gitlab/config/gitlab.yml를 편집하십시오:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '우리의 SAML 공급자',
          groups_attribute: 'Groups',
          admin_groups: ['Admins'],
          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을 재시작하십시오:

# 시스템이 systemd를 사용하는 경우
sudo systemctl restart gitlab.target

# 시스템이 SysV init을 사용하는 경우
sudo service gitlab restart

감사자 그룹

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

귀하의 IdP는 SAML 응답에 그룹 정보를 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab을 구성하여 다음을 확인하세요:

groups_attribute 설정을 사용하여 SAML 응답에서 그룹을 찾을 위치.
그룹 또는 사용자에 대한 정보, 그룹 설정을 사용하여.

auditor_groups 설정을 사용하여 GitLab이 감사자 액세스가 있는 사용자를 포함하는 그룹을 식별하도록 구성합니다.

groups_attribute에 지정된 속성이 잘못되었거나 누락되면 사용자는 감사자 액세스를 잃게 됩니다.

예시 구성:

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [  
  { name: 'saml',  
    label: 'Our SAML Provider',  
    groups_attribute: 'Groups',  
    auditor_groups: ['Auditors'],  
    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을 재구성합니다:
```
sudo gitlab-ctl reconfigure  
```

헬름 차트 (Kubernetes)

saml.yaml라는 이름의 파일에 다음 내용을 넣어 Kubernetes Secret으로 사용합니다:

name: 'saml'  
label: 'Our SAML Provider'  
groups_attribute: 'Groups'  
auditor_groups: ['Auditors']  
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'  

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml  

헬름 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집합니다:

global:  
  appConfig:  
    omniauth:  
      providers:  
        - secret: gitlab-saml  

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

도커

docker-compose.yml을 편집합니다:

version: "3.6"  
services:  
  gitlab:  
    environment:  
      GITLAB_OMNIBUS_CONFIG: |  
        gitlab_rails['omniauth_providers'] = [  
           { name: 'saml',  
             label: 'Our SAML Provider',  
             groups_attribute: 'Groups',  
             auditor_groups: ['Auditors'],  
             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을 재시작합니다:
```
docker compose up -d  
```

소스에서 컴파일한 경우

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base  
  omniauth:  
    providers:  
      - { name: 'saml',  
          label: 'Our SAML Provider',  
          groups_attribute: 'Groups',  
          auditor_groups: ['Auditors'],  
          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을 재시작합니다:

# systemd를 사용하는 시스템의 경우  
sudo systemctl restart gitlab.target  

# SysV init을 사용하는 시스템의 경우  
sudo service gitlab restart  

SAML 그룹 동기화를 자동으로 관리

GitLab 그룹 멤버십을 자동으로 관리하는 방법에 대한 정보는 SAML 그룹 동기화를 참조하세요.

이중 인증 우회

세션별로 SAML 인증 방법이 이중 인증(2FA)으로 간주되도록 구성하려면, 해당 방법을 upstream_two_factor_authn_contexts 목록에 등록하세요.

IdP가 AuthnContext를 반환하는지 확인합니다. 예를 들면:

<saml:AuthnStatement>
    <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef>
    </saml:AuthnContext>
</saml:AuthnStatement>

설치 구성을 편집하여 SAML 인증 방법을 upstream_two_factor_authn_contexts 목록에 등록합니다.

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    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'
            upstream_two_factor_authn_contexts:
              %w(
                urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
                urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
                urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
              ),
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

헬름 차트 (Kubernetes)

saml.yaml라는 이름의 파일에 다음 내용을 넣어 Kubernetes 비밀로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
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'
  upstream_two_factor_authn_contexts:
    - 'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport'
    - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS'
    - 'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'

Kubernetes 비밀을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

헬름 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

도커

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             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'
                     upstream_two_factor_authn_contexts:
                       %w(
                         urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
                         urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
                         urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
                       )
             }
           }
        ]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

자체 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: 'Our SAML Provider',
          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'
                  upstream_two_factor_authn_contexts:
                    [
                      'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport',
                      'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS',
                      'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'
                    ]
          }
        }

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

응답 서명 검증

IdPs는 서명이 있는 SAML 응답을 제공해야 하며, 이는 어설션이 변조되지 않았음을 보장합니다.

이는 특정 그룹 구성원이 필요할 때 사용자 사칭 및 권한 상승을 방지합니다.

`idp_cert_fingerprint` 사용

응답 서명 검증을 idp_cert_fingerprint를 사용하여 구성할 수 있습니다.

예제 구성:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '우리의 SAML 제공자',
    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을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

saml.yaml이라는 이름의 파일에 다음 내용을 넣어 Kubernetes Secret으로 사용합니다:

name: 'saml'
label: '우리의 SAML 제공자'
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'

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '우리의 SAML 제공자',
             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을 재시작합니다:
```
docker compose up -d
```

직접 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml를 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '우리의 SAML 제공자',
          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을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

`idp_cert` 사용하기

IdP가 idp_cert_fingerprint를 사용하여 구성하는 것을 지원하지 않는 경우,

대신 idp_cert를 사용하여 GitLab을 직접 구성할 수 있습니다.

예제 구성:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '우리 SAML 공급자',
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert: '-----BEGIN CERTIFICATE-----
              <redacted>
              -----END CERTIFICATE-----',
            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을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

saml.yaml이라는 이름의 파일에 다음 내용을 넣어

Kubernetes Secret로 사용합니다:

name: 'saml'
label: '우리 SAML 공급자'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert: |
    -----BEGIN CERTIFICATE-----
    <redacted>
    -----END CERTIFICATE-----
  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'

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 파일을 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml 파일을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '우리 SAML 공급자',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert: '-----BEGIN CERTIFICATE-----
                       <redacted>
                       -----END CERTIFICATE-----',
                     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을 재시작합니다:
```
docker compose up -d
```

소스에서 직접 컴파일

/home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '우리 SAML 공급자',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert: '-----BEGIN CERTIFICATE-----
                    <redacted>
                    -----END CERTIFICATE-----',
                  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을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

응답 서명 검증을 잘못 구성한 경우 다음과 같은 오류 메시지가 표시될 수 있습니다:

키 검증 오류.
다이제스트 불일치.
지문 불일치.

이 오류를 해결하는 방법에 대한 자세한 내용은 SAML 문제 해결 가이드를 참조하세요.

SAML 설정 사용자 정의

사용자 인증을 위한 SAML 서버로 리디렉션

auto_sign_in_with_provider 설정을 GitLab 구성에 추가하여 사용자 인증을 위해 SAML 서버로 자동으로 리디렉션할 수 있습니다. 이렇게 하면 실제로 로그인하기 전에 요소를 선택할 필요가 없습니다.

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집하세요:

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

파일을 저장하고 GitLab을 재구성하세요:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

Helm 값을 내보내세요:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집하세요:

global:
  appConfig:
    omniauth:
      autoSignInWithProvider: 'saml'

파일을 저장하고 새로운 값을 적용하세요:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집하세요:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

파일을 저장하고 GitLab을 재시작하세요:
```
docker compose up -d
```

자체 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml을 편집하세요:

production: &base
  omniauth:
    auto_sign_in_with_provider: 'saml'

파일을 저장하고 GitLab을 재시작하세요:

# 시스템이 systemd를 사용 중인 경우
sudo systemctl restart gitlab.target

# 시스템이 SysV init을 사용 중인 경우
sudo service gitlab restart

모든 로그인 시도는 SAML 서버로 리디렉션되므로 로컬 자격 증명으로 로그인할 수 없습니다. SAML 사용자 중 최소한 한 명은 관리자 권한을 가져야 합니다.

참고: 자동 로그인 설정을 우회하려면 로그인 URL에 ?auto_sign_in=false를 추가하세요. 예: https://gitlab.example.com/users/sign_in?auto_sign_in=false.

SAML 응답 속성 이름 매핑

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

attribute_statements를 사용하여 SAML 응답의 속성 이름을 OmniAuth info 해시 항목에 매핑할 수 있습니다.

참고: 이 설정은 OmniAuth info 해시 스키마의 일부인 속성을 매핑하는 데만 사용하세요.

예를 들어, SAMLResponse에 EmailAddress라는 속성이 포함되어 있다면 { email: ['EmailAddress'] }를 지정하여 속성을 info 해시의 해당 키에 매핑하세요. URI 이름 속성도 지원됩니다. 예를 들어, { email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'] }.

이 설정을 사용하여 GitLab이 계정 생성에 필요한 특정 속성을 찾는 위치를 알려주세요. 사용자의 이메일 주소가 email 대신 EmailAddress로 IdP에서 전송되는 경우, 구성을 통해 GitLab에 알려주세요:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집하세요:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    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',
            attribute_statements: { email: ['EmailAddress'] }
    }
  }
]

파일을 저장하고 GitLab을 재구성하세요:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

다음 내용을 saml.yaml라는 파일에 작성하여 Kubernetes 비밀로 사용하세요:

name: 'saml'
label: 'Our SAML Provider'
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'
  attribute_statements:
    email: ['EmailAddress']

Kubernetes 비밀을 생성하세요:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보내세요:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집하세요:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새로운 값을 적용하세요:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집하세요:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             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',
                     attribute_statements: { email: ['EmailAddress'] }
             }
           }
        ]

파일을 저장하고 GitLab을 재시작하세요:
```
docker compose up -d
```

자체 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml을 편집하세요:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: 'Our SAML Provider',
          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',
                  attribute_statements: { email: ['EmailAddress'] }
          }
        }

파일을 저장하고 GitLab을 재시작하세요:

# 시스템이 systemd를 사용 중인 경우
sudo systemctl restart gitlab.target

# 시스템이 SysV init을 사용 중인 경우
sudo service gitlab restart

사용자 이름 설정

기본적으로 SAML 응답의 이메일 주소의 로컬 부분이 사용자의 GitLab 사용자 이름을 생성하는 데 사용됩니다.

attribute_statements에서 username 또는 nickname를 구성하여 사용자가 원하는 사용자 이름을 포함하는 하나 이상의 속성을 지정하십시오:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '우리의 SAML 공급자',
    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',
            attribute_statements: { nickname: ['username'] }
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

다음 내용을 saml.yaml이라는 파일에 넣어 Kubernetes Secret으로 사용합니다: Kubernetes Secret:

name: 'saml'
label: '우리의 SAML 공급자'
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'
  attribute_statements:
    nickname: ['username']

Kubernetes Secret를 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '우리의 SAML 공급자',
             groups_attribute: 'Groups',
             required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
             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',
                     attribute_statements: { nickname: ['username'] }
             }
           }
        ]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

소스에서 컴파일된 것 (Self-compiled)

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '우리의 SAML 공급자',
          groups_attribute: 'Groups',
          required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
          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',
                  attribute_statements: { nickname: ['username'] }
          }
        }

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

이는 또한 SAML 응답에서 username 속성을 GitLab의 사용자 이름으로 설정합니다.

시계 드리프트 허용

IdP의 시계가 시스템 시계보다 약간 빠르게 이동할 수 있습니다.

약간의 시계 드리프트를 허용하려면 설정에서 allowed_clock_drift를 사용하세요.

매개변수의 값은 초의 숫자와 분수로 입력해야 합니다.

주어진 값은 응답이 검증되는 현재 시간에 추가됩니다.

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 수정합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
    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',
            allowed_clock_drift: 1  # 1초 시계 드리프트 허용
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

saml.yaml라는 이름의 파일에 다음 내용을 넣어 Kubernetes Secret로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
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'
  allowed_clock_drift: 1  # 1초 시계 드리프트 허용

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 수정합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

도커

docker-compose.yml을 수정합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             groups_attribute: 'Groups',
             required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
             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',
                     allowed_clock_drift: 1  # 1초 시계 드리프트 허용
             }
           }
        ]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

소스에서 직접 컴파일 (Self-compiled)

/home/git/gitlab/config/gitlab.yml 파일을 수정합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: 'Our SAML Provider',
          groups_attribute: 'Groups',
          required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
          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',
                  allowed_clock_drift: 1  # 1초 시계 드리프트 허용
          }
        }

파일을 저장하고 GitLab을 재시작합니다:

# systemd로 실행되는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init로 실행되는 시스템의 경우
sudo service gitlab restart

`uid`에 대한 고유 속성을 지정합니다 (선택 사항)

기본적으로 사용자의 uid는 SAML 응답에서 NameID 속성으로 설정됩니다. uid에 대한 다른 속성을 지정하려면 uid_attribute를 설정할 수 있습니다.

uid를 고유 속성으로 설정하기 전에 SAML 사용자가 다음 속성을 변경할 수 없도록 구성했는지 확인하세요:

NameID.
omniauth_auto_link_saml_user와 함께 사용할 때의 Email.

사용자가 이러한 속성을 변경할 수 있다면, 다른 권한이 있는 사용자로 로그인할 수 있습니다.

이러한 속성을 변경할 수 없도록 만드는 방법에 대한 정보는 SAML IdP 문서를 참조하세요.

다음 예제에서 SAML 응답의 uid 속성 값은 uid_attribute로 설정됩니다.

리눅스 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: '우리의 SAML 공급자',
    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',
            uid_attribute: 'uid'
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

saml.yaml이라는 파일에 다음 내용을 넣어 Kubernetes Secret으로 사용합니다:

name: 'saml'
label: '우리의 SAML 공급자'
groups_attribute: 'Groups'
required_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'
  uid_attribute: 'uid'

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 파일을 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새로운 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml 파일을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: '우리의 SAML 공급자',
             groups_attribute: 'Groups',
             required_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',
                     uid_attribute: 'uid'
             }
           }
        ]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

소스에서 직접 컴파일 (Self-compiled)

/home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: '우리의 SAML 공급자',
          groups_attribute: 'Groups',
          required_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',
                  uid_attribute: 'uid'
          }
        }

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 사용하는 시스템
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템
sudo service gitlab restart

Assertion encryption (optional)

GitLab은 SAML 2.0과 함께 TLS 암호화의 사용을 요구합니다. 때때로, GitLab은 추가적인 어설션 암호화가 필요합니다. 예를 들어, 만약 당신이:

로드 밸런서에서 TLS 암호화를 조기에 종료했습니다.
로그에 표시되지 않기를 원하는 민감한 세부정보를 어설션에 포함했습니다.

대부분의 조직은 이 레이어에서 추가적인 암호화가 필요하지 않습니다.

귀하의 IdP는 GitLab의 공개 인증서로 어설션을 암호화합니다. GitLab은 비공개 키로 EncryptedAssertion을 복호화합니다.

이 통합은 어설션 암호화 및 요청 서명을 위해 certificate와 private_key 설정을 사용합니다.

SAML 통합은 EncryptedAssertion을 지원합니다. 어설션을 암호화하려면, SAML 설정에서 귀하의 GitLab 인스턴스의 비공개 키와 공개 인증서를 정의하세요.

키 및 인증서를 정의할 때, 키 파일의 모든 줄 바꿈을 \n으로 교체하세요. 이렇게 하면 키 파일이 줄 바꿈 없이 하나의 긴 문자열이 됩니다.

Linux package (Omnibus)

/etc/gitlab/gitlab.rb를 수정하세요:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
    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',
            certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
            private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
    }
  }
]

파일을 저장하고 GitLab을 재구성하세요:
```
sudo gitlab-ctl reconfigure
```

Helm chart (Kubernetes)

saml.yaml이라는 이름의 파일에 다음 내용을 저장하여 Kubernetes Secret으로 사용하세요:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
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'
  certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----'
  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'

Kubernetes Secret를 생성하세요:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보내세요:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml를 수정하세요:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새로운 값을 적용하세요:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml를 수정하세요:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             groups_attribute: 'Groups',
             required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
             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',
                     certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                     private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
             }
           }
        ]

파일을 저장하고 GitLab을 재시작하세요:
```
docker compose up -d
```

Self-compiled (source)

/home/git/gitlab/config/gitlab.yml를 수정하세요:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: 'Our SAML Provider',
          groups_attribute: 'Groups',
          required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
          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',
                  certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
          }
        }

파일을 저장하고 GitLab을 재시작하세요:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

SAML 인증 요청 서명 (선택 사항)

GitLab에서 SAML 인증 요청에 서명하도록 구성할 수 있습니다. 이 구성은 GitLab SAML 요청이 SAML 리디렉션 바인딩을 사용하기 때문에 선택 사항입니다.

서명을 구현하려면 다음 단계를 따릅니다:

GitLab 인스턴스에서 SAML에 사용할 개인 키와 공개 인증서 쌍을 생성합니다.

구성의 security 섹션에서 서명 설정을 구성합니다. 예를 들어:

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집합니다:

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    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',
            certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
            private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
            security: {
              authn_requests_signed: true,  # AuthNRequest에 서명 활성화
              want_assertions_signed: true,  # 서명된 어설션 요구 사항 활성화
              want_assertions_encrypted: false,  # 암호화된 어설션 요구 사항 활성화
              metadata_signed: false,  # 메타데이터에 서명 활성화
              signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
              digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
            }
    }
  }
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

saml.yaml이라는 파일에 다음 내용을 추가하여 Kubernetes Secret으로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
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'
  certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----'
  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
  security:
    authn_requests_signed: true  # AuthNRequest에 서명 활성화
    want_assertions_signed: true  # 서명된 어설션 요구 사항 활성화
    want_assertions_encrypted: false  # 암호화된 어설션 요구 사항 활성화
    metadata_signed: false  # 메타데이터에 서명 활성화
    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256'

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다:

global:
  appConfig:
    omniauth:
      providers:
        - secret: gitlab-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             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',
                     certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                     private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                     security: {
                       authn_requests_signed: true,  # AuthNRequest에 서명 활성화
                       want_assertions_signed: true,  # 서명된 어설션 요구 사항 활성화
                       want_assertions_encrypted: false,  # 암호화된 어설션 요구 사항 활성화
                       metadata_signed: false,  # 메타데이터에 서명 활성화
                       signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                       digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                     }
             }
           }
        ]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

자체 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  omniauth:
    providers:
      - { name: 'saml',
          label: 'Our SAML Provider',
          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',
                  certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                  security: {
                    authn_requests_signed: true,  # AuthNRequest에 서명 활성화
                    want_assertions_signed: true,  # 서명된 어설션 요구 사항 활성화
                    want_assertions_encrypted: false,  # 암호화된 어설션 요구 사항 활성화
                    metadata_signed: false,  # 메타데이터에 서명 활성화
                    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                  }
          }
        }

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init를 사용하는 시스템의 경우
sudo service gitlab restart

GitLab은 다음과 같이 처리합니다:

주어진 개인 키로 요청에 서명합니다.
메타데이터에서 서명을 검증할 수 있도록 x500 공개 인증서를 IdP에 포함합니다.

이 옵션에 대한 자세한 내용은 Ruby SAML gem 문서를 참조하세요.

Ruby SAML gem은 SAML 인증의 클라이언트 측을 구현하기 위해 OmniAuth SAML gem에서 사용됩니다.

참고: SAML 리디렉션 바인딩은 SAML POST 바인딩과 다릅니다. POST 바인딩에서는 요청을 중간에서 변조하는 것을 방지하기 위해 서명이 필요합니다.

SAML을 통한 사용자 생성 시 비밀번호 생성

GitLab은 SAML을 통해 생성된 사용자에 대한 비밀번호를 생성하고 설정합니다.

SSO 또는 SAML로 인증된 사용자는 HTTPS를 통한 Git 작업에 비밀번호를 사용해서는 안 됩니다.

이러한 사용자는 대신에:

개인, 프로젝트, 또는 그룹 액세스 토큰을 설정합니다.
OAuth 자격 증명 도우미를 사용합니다.

기존 사용자에 대한 SAML ID 링크

관리자는 GitLab을 구성하여 기존 GitLab 사용자와 SAML 사용자를 자동으로 연결할 수 있습니다.

자세한 내용은 GitLab에서 SAML 지원 구성을 참조하십시오.

사용자는 기존 GitLab 계정에 자신의 SAML ID를 수동으로 연결할 수 있습니다. 자세한 내용은 기존 사용자에 대한 OmniAuth 활성화를 참조하십시오.

자체 관리 인스턴스에서 그룹 SAML SSO 구성

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

여러 SAML IdP를 통해 액세스를 허용해야 하는 경우 그룹 SAML SSO를 사용하세요.

그룹 SAML SSO를 구성하려면:

Linux 패키지 (Omnibus)

GitLab이 HTTPS로 구성되어 있는지 확인합니다.

OmniAuth 및 group_saml 공급자를 활성화하려면 /etc/gitlab/gitlab.rb를 편집합니다:

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

GitLab이 HTTPS로 구성되어 있는지 확인합니다.
group_saml.yaml라는 이름의 파일에 다음 내용을 넣어 Kubernetes Secret로 사용합니다:
```
name: 'group_saml'
```

Kubernetes Secret을 생성합니다:

kubectl create secret generic -n <namespace> gitlab-group-saml --from-file=provider=group_saml.yaml

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

OmniAuth 및 group_saml 공급자를 활성화하려면 gitlab_values.yaml를 편집합니다:

global:
  appConfig:
    omniauth:
      enabled: true
      providers:
        - secret: gitlab-group-saml

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

도커

GitLab이 HTTPS로 구성되어 있는지 확인합니다.

OmniAuth 및 group_saml 공급자를 활성화하려면 docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_enabled'] = true
        gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

소스에서 컴파일 (Self-compiled)

GitLab이 HTTPS로 구성되어 있는지 확인합니다.

OmniAuth 및 group_saml 공급자를 활성화하려면 /home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  omniauth:
    enabled: true
    providers:
      - { name: 'group_saml' }

파일을 저장하고 GitLab을 재시작합니다:

# systemd를 사용하는 시스템의 경우
sudo systemctl restart gitlab.target

# SysV init을 사용하는 시스템의 경우
sudo service gitlab restart

멀티 테넌트 솔루션으로서, 자체 관리 인스턴스의 그룹 SAML은 추천되는 인스턴스 전역 SAML과 비교하여 제한적입니다.

인스턴스 전역 SAML을 사용하여 다음의 이점을 누리십시오:

SAML 앱에 대한 추가 구성

IdP에서 SAML 앱을 구성할 때, IdP는 다음과 같은 추가 구성이 필요할 수 있습니다:

필드	값	비고
SAML 프로필	웹 브라우저 SSO 프로필	GitLab은 사용자를 브라우저를 통해 로그인시키기 위해 SAML을 사용합니다. IdP에 직접 요청을 하지 않습니다.
SAML 요청 바인딩	HTTP Redirect	GitLab(SP)은 base64로 인코딩된 `SAMLRequest` HTTP 매개변수와 함께 사용자를 IdP로 리디렉션합니다.
SAML 응답 바인딩	HTTP POST	IdP에 의해 SAML 토큰이 전송되는 방식을 명시합니다. 사용자의 브라우저가 GitLab에 제출하는 `SAMLResponse`를 포함합니다.
SAML 응답 서명	필수	변조를 방지합니다.
응답의 X.509 인증서	필수	응답을 서명하고 제공된 지문에 대해 응답을 확인합니다.
지문 알고리즘	SHA-1	GitLab은 SAML 응답을 서명하기 위해 인증서의 SHA-1 해시를 사용합니다.
서명 알고리즘	SHA-1/SHA-256/SHA-384/SHA-512	응답이 서명되는 방식을 결정합니다. 다이제스트 방법이라고도 하며, SAML 응답에서 지정될 수 있습니다.
SAML 주장 암호화	선택적	사용자 신원 공급자, 사용자의 브라우저 및 GitLab 간의 TLS를 사용합니다.
SAML 주장 서명	선택적	SAML 주장의 무결성을 검증합니다. 활성화 시 전체 응답을 서명합니다.
SAML 요청 서명 확인	선택적	SAML 응답의 서명을 확인합니다.
기본 RelayState	선택적	사용자가 IdP에서 SAML을 통해 성공적으로 로그인한 후 도달해야 할 기본 URL의 하위 경로를 지정합니다.
NameID 형식	Persistent	NameID 형식 세부정보를 참조하세요.
추가 URL	선택적	일부 공급자의 다른 필드에서 발급자, 식별자 또는 주장 소비 서비스 URL을 포함할 수 있습니다.

예제 구성은 특정 공급자에 대한 노트를 참조하세요.

용어집

용어	설명
신원 공급자(IdP)	Okta 또는 OneLogin과 같은 사용자 신원을 관리하는 서비스입니다.
서비스 공급자(SP)	사용자를 인증하기 위해 Okta와 같은 SAML IdP에서 주장을 소모합니다. GitLab을 SAML 2.0 SP로 구성할 수 있습니다.
주장	사용자의 신원에 대한 정보 조각, 예: 이름 또는 역할. 주장 또는 속성으로도 알려져 있습니다.
싱글 사인온(SSO)	인증 방식의 이름입니다.
주장 소비 서비스 URL	IdP에서 성공적으로 인증한 후 사용자가 리디렉션되는 GitLab의 콜백입니다.
발급자	GitLab이 IdP에 자신을 식별하는 방법입니다. “Relying party trust identifier”라고도 알려져 있습니다.
인증서 지문	서버가 올바른 인증서로 통신을 서명하고 있는지 확인하여 SAML을 통한 통신이 안전함을 확인합니다. 인증서 엄지지문이라고도 알려져 있습니다.

문제 해결

문제 해결 SAML 가이드를 참조하세요.

self-managed GitLab 인스턴스를 위한 SAML SSO

GitLab에서 SAML 지원 구성

SAML IdP에 GitLab 등록하기

IdP에서 SAML 구성하기

여러 SAML IdP를 사용하도록 GitLab 구성하기

IdP 설정하기

Okta 설정하기

Google Workspace 설정하기

다른 IdP 설정하기

어설션 구성하기

SAML 그룹 멤버십에 따라 사용자 구성

필수 그룹

외부 그룹

관리자 그룹

감사자 그룹

SAML 그룹 동기화를 자동으로 관리

이중 인증 우회

응답 서명 검증

`idp_cert_fingerprint` 사용

`idp_cert` 사용하기

SAML 설정 사용자 정의

사용자 인증을 위한 SAML 서버로 리디렉션

SAML 응답 속성 이름 매핑

사용자 이름 설정

시계 드리프트 허용

`uid`에 대한 고유 속성을 지정합니다 (선택 사항)

Assertion encryption (optional)

SAML 인증 요청 서명 (선택 사항)

SAML을 통한 사용자 생성 시 비밀번호 생성

기존 사용자에 대한 SAML ID 링크

자체 관리 인스턴스에서 그룹 SAML SSO 구성

SAML 앱에 대한 추가 구성

용어집

문제 해결

도움말

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

도움받기

self-managed GitLab 인스턴스를 위한 SAML SSO

GitLab에서 SAML 지원 구성

SAML IdP에 GitLab 등록하기

IdP에서 SAML 구성하기

여러 SAML IdP를 사용하도록 GitLab 구성하기

IdP 설정하기

Okta 설정하기

Google Workspace 설정하기

다른 IdP 설정하기

어설션 구성하기

SAML 그룹 멤버십에 따라 사용자 구성

필수 그룹

외부 그룹

관리자 그룹

감사자 그룹

SAML 그룹 동기화를 자동으로 관리

이중 인증 우회

응답 서명 검증

idp_cert_fingerprint 사용

idp_cert 사용하기

SAML 설정 사용자 정의

사용자 인증을 위한 SAML 서버로 리디렉션

SAML 응답 속성 이름 매핑

사용자 이름 설정

시계 드리프트 허용

uid에 대한 고유 속성을 지정합니다 (선택 사항)

Assertion encryption (optional)

SAML 인증 요청 서명 (선택 사항)

SAML을 통한 사용자 생성 시 비밀번호 생성

기존 사용자에 대한 SAML ID 링크

자체 관리 인스턴스에서 그룹 SAML SSO 구성

SAML 앱에 대한 추가 구성

용어집

문제 해결

도움말

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

도움받기

`idp_cert_fingerprint` 사용

`idp_cert` 사용하기

`uid`에 대한 고유 속성을 지정합니다 (선택 사항)