SAML SSO 인테그레이션

요약

GitLab.com의 경우 GitLab.com 그룹의 SAML SSO를 참고합니다. 이 페이지에서는 GitLab Self-Managed를 위한 인스턴스 전체 SAML 단일 로그인(SSO) 설정 방법을 설명합니다. GitLab을 SAML 서비스 제공자(SP)로 동작하도록 구성할 수 있습니다.

Note

GitLab.com의 경우 GitLab.com 그룹의 SAML SSO를 참고합니다.

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

GitLab을 SAML 서비스 제공자(SP)로 동작하도록 구성할 수 있습니다. 이렇게 하면 GitLab 이 Okta와 같은 SAML ID 공급자(IdP)의 어설션을 사용하여 사용자를 인증할 수 있습니다.

다음 항목에 대한 자세한 내용은 아래를 참고합니다:

OmniAuth 공급자 설정: OmniAuth 문서를 참고합니다.
자주 사용하는 용어: 용어집을 참고합니다.

GitLab에서 SAML 지원 구성#

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 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

/etc/gitlab/gitlab.rb를 편집하여 공급자 구성을 추가합니다:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml", # This must be lowercase.
    label: "Provider name", # optional label for login button, defaults to "Saml"
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
      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"
    }
  }
]

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

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

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

선택 사항입니다. 이메일 주소가 일치하면 gitlab_values.yaml에 다음 설정을 추가하여 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
```
global:
  appConfig:
    omniauth:
      autoLinkSamlUser: true
```
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

다음 내용을 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 작성합니다:

name: 'saml'
label: 'Provider name' # optional label for login button, defaults to "Saml"
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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'

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

Kubernetes 시크릿을 생성합니다:

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

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

선택 사항입니다. 이메일 주소가 일치하면 docker-compose.yml에 다음 설정을 추가하여 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
```
version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_link_saml_user'] = true
```
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

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

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          {
            name: "saml",
            label: "Provider name", # optional label for login button, defaults to "Saml"
            args: {
              assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
              idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
              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"
            }
          }
        ]

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

파일을 저장하고 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
```
선택 사항입니다. 이메일 주소가 일치하면 /home/git/gitlab/config/gitlab.yml에 다음 설정을 추가하여 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
```
production: &base
  omniauth:
    auto_link_saml_user: true
```
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

/home/git/gitlab/config/gitlab.yml을 편집하여 공급자 구성을 추가합니다:

omniauth:
  providers:
    - {
      name: 'saml',
      label: 'Provider name', # optional label for login button, defaults to "Saml"
      args: {
        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
        idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
        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'
      }
    }

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

SAML IdP에 GitLab 등록#

issuer에 지정한 애플리케이션 이름을 사용하여 SAML IdP에 GitLab SP를 등록합니다.
IdP에 구성 정보를 제공하려면 애플리케이션의 메타데이터 URL을 빌드합니다. GitLab의 메타데이터 URL을 빌드하려면 GitLab 설치 환경의 HTTPS URL 뒤에 users/auth/saml/metadata를 붙입니다. 예를 들면 다음과 같습니다:
```
https://gitlab.example.com/users/auth/saml/metadata
```
IdP는 최소한 email 또는 mail을 사용하여 사용자의 이메일 주소가 담긴 클레임을 제공해야 합니다. 사용 가능한 다른 클레임에 대한 자세한 내용은 어설션 구성을 참고합니다.
이제 로그인 페이지의 일반 로그인 폼 아래에 SAML 아이콘이 표시됩니다. 인증 과정을 시작하려면 아이콘을 선택합니다. 인증에 성공하면 GitLab으로 돌아가 로그인됩니다.

IdP에서 SAML 구성하기#

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

어설션 소비자 서비스 URL.
발급자(Issuer).
NameID.
이메일 주소 클레임.

예시 구성은 ID 공급자 설정을 참고합니다.

IdP에 추가 구성이 필요할 수 있습니다. 자세한 내용은 IdP의 SAML 애플리케이션 추가 구성을 참고합니다.

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

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

각 공급자에 args에 설정된 이름과 일치하는 고유한 이름 세트가 있습니다.
공급자 이름은 다음 용도로 사용됩니다:
- 공급자 이름을 기준으로 하는 속성에 대한 OmniAuth 구성에서 사용됩니다. 예를 들어 allowBypassTwoFactor, allowSingleSignOn, syncProfileFromProvider가 있습니다.
- 각 기존 사용자와 추가 아이덴티티로 연결하는 데 사용됩니다.
assertion_consumer_service_url 이 공급자 이름과 일치합니다.
공급자 이름에서 유추할 수 없으므로 strategy_class를 명시적으로 설정합니다.

Note

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

여러 SAML IdP를 설정하려면:

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

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml', # This must match the following name configuration parameter
    label: 'Provider 1' # Differentiate the two buttons and providers in the UI
    args: {
            name: 'saml', # This is mandatory and must match the provider name
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
            strategy_class: 'OmniAuth::Strategies::SAML',
            # Include all required arguments similar to a single provider
          },
  },
  {
    name: 'saml_2', # This must match the following name configuration parameter
    label: 'Provider 2' # Differentiate the two buttons and providers in the UI
    args: {
            name: 'saml_2', # This is mandatory and must match the provider name
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
            strategy_class: 'OmniAuth::Strategies::SAML',
            # Include all required arguments similar to a single provider
          },
  }
]

사용자가 먼저 두 공급자 중 하나로 수동으로 계정을 만들지 않고도 SAML로 계정을 만들 수 있도록 하려면 다음 값을 구성에 추가합니다:

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

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

다음 내용을 첫 번째 SAML 공급자에 대해 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 작성합니다:

name: 'saml' # At least one provider must be named 'saml'
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
args:
  name: 'saml' # This is mandatory and must match the provider name
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL must match the name of the provider
  strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory
  # Include all required arguments similar to a single provider

다음 내용을 두 번째 SAML 공급자에 대해 Kubernetes 시크릿으로 사용할 saml_2.yaml 파일에 작성합니다:

name: 'saml_2'
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
args:
  name: 'saml_2' # This is mandatory and must match the provider name
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL must match the name of the provider
  strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory
  # Include all required arguments similar to a single provider

선택 사항입니다. 같은 단계를 따라 SAML 공급자를 추가로 설정합니다.

Kubernetes 시크릿을 생성합니다:

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']

Save the file and apply the new values:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

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', # This must match the following name configuration parameter
            label: 'Provider 1' # Differentiate the two buttons and providers in the UI
            args: {
                    name: 'saml', # This is mandatory and must match the provider name
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    # Include all required arguments similar to a single provider
                  },
          },
          {
            name: 'saml_2', # This must match the following name configuration parameter
            label: 'Provider 2' # Differentiate the two buttons and providers in the UI
            args: {
                    name: 'saml_2', # This is mandatory and must match the provider name
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    # Include all required arguments similar to a single provider
                  },
          }
        ]

프로바이더 중 어느 쪽에서도 계정을 수동으로 만들지 않고 사용자가 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', # This must match the following name configuration parameter
        label: 'Provider 1' # Differentiate the two buttons and providers in the UI
        args: {
          name: 'saml', # This is mandatory and must match the provider name
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
          strategy_class: 'OmniAuth::Strategies::SAML',
          # Include all required arguments similar to a single provider
        },
      }
      - {
        name: 'saml_2', # This must match the following name configuration parameter
        label: 'Provider 2' # Differentiate the two buttons and providers in the UI
        args: {
          name: 'saml_2', # This is mandatory and must match the provider name
          strategy_class: 'OmniAuth::Strategies::SAML',
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
          # Include all required arguments similar to a single provider
        },
      }

프로바이더 중 어느 쪽에서도 계정을 수동으로 만들지 않고 사용자가 SAML로 계정을 생성할 수 있도록 하려면 구성에 다음 값을 추가합니다:

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

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

ID 공급자 설정#

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": issuer를 사용합니다.
- 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 account.

Google Workspace를 설정하려면:

다음 정보를 사용해 아래 안내를 따릅니다. Set up your own custom SAML application in Google Workspace.

	일반적인 값	설명
SAML 앱 이름	GitLab	다른 이름도 사용할 수 있습니다.
ACS URL	`https:///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 format	`EMAIL`	필수 값입니다. `name_identifier_format` 라고도 합니다.
Name ID	기본 이메일 주소	이메일 주소입니다. 해당 주소로 발송된 내용을 누군가 수신하는지 확인합니다.
First name	`first_name`	이름입니다. GitLab과 통신하는 데 필요한 값입니다.
Last name	`last_name`	성입니다. GitLab과 통신하는 데 필요한 값입니다.

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

Google Directory attributes App attributes

Basic information > Email email

Basic Information > First name first_name

Basic Information > Last name last_name

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

Google Directory attributes	App attributes
Basic information > Email	`email`
Basic Information > First name	`first_name`
Basic Information > Last name	`last_name`

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

	값	설명
SSO URL	환경에 따라 다름	Google Identity Provider 세부 정보입니다. GitLab `idp_sso_target_url` 설정으로 지정합니다.
Certificate	다운로드 가능	Google SAML 인증서입니다.
SHA256 fingerprint	환경에 따라 다름	인증서를 다운로드하면 확인할 수 있습니다. 인증서에서 SHA256 fingerprint를 생성하는 방법은 fingerprint 계산을 참고합니다.

Google Workspace 관리자는 IdP 메타데이터, Entity ID, SHA-256 fingerprint도 제공합니다. 다만 GitLab 이 Google Workspace SAML 애플리케이션에 연결하는 데 이 정보가 필요하지는 않습니다.

Microsoft Entra ID 설정#

Microsoft Entra admin center에 로그인합니다.
비 갤러리 애플리케이션을 생성합니다.

해당 애플리케이션에 SSO를 구성합니다.

gitlab.rb 파일의 다음 설정은 Microsoft Entra ID 필드에 대응합니다:

`gitlab.rb` setting	Microsoft Entra ID field
`issuer`	Identifier (Entity ID)
`assertion_consumer_service_url`	Reply URL (Assertion Consumer Service URL)
`idp_sso_target_url`	Login URL
`idp_cert_fingerprint`	Thumbprint

다음 속성을 설정합니다:
- **Unique User Identifier (Name ID)**를 user.objectID로 설정합니다.
  - Name identifier format을 persistent로 설정합니다. 자세한 내용은 사용자 SAML ID 관리 방법을 참고합니다.
- Additional claims는 지원되는 속성으로 설정합니다.

자세한 내용은 구성 예시 페이지를 참고합니다.

기타 IdP 설정#

일부 IdP는 SAML 구성에서 IdP로 사용하는 방법에 관한 문서를 제공합니다. 예를 들면 다음과 같습니다:

SAML 구성에서 IdP를 구성하는 데 관해 궁금한 점이 있으면 해당 프로바이더의 지원팀에 문의합니다.

Assertion 구성#

Note

이 속성은 대소문자를 구분합니다.

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

GitLab은 SAML SSO 프로바이더로부터 SAML 응답을 받으면 속성의 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

GitLab 이 SAML 응답을 파싱할 수 있도록 속성의 Name 필드에 이 값을 정확히 포함해야 합니다. 예를 들어 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를 참고합니다:

커스텀 assertion 구성 예시입니다.
커스텀 사용자 이름 속성을 구성하는 방법입니다.

지원되는 assertion 전체 목록은 OmniAuth SAML gem을 참고합니다.

SAML 그룹 멤버십을 기준으로 사용자 구성#

다음을 수행할 수 있습니다:

사용자가 특정 그룹의 구성원이어야 하도록 요구합니다.
그룹 멤버십을 기준으로 사용자에게 외부, 관리자, 또는 감사자 권한을 할당합니다.

GitLab은 SAML 로그인할 때마다 이 그룹을 확인하고 필요에 따라 사용자 속성을 갱신합니다. 이 기능은 사용자를 GitLab 그룹에 자동으로 추가하지는 않습니다.

이 그룹 지원 여부는 다음에 따라 달라집니다:

구독 등급입니다.
GitLab Enterprise Edition (EE) 설치 여부입니다.

Group	Tier	GitLab Enterprise Edition (EE) Only?
필수	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: 요소를 추가합니다. 이 속성은 대소문자를 구분합니다.

groups_attribute는 SAML 설정의 프로바이더 레벨에서 name 및 label과 형제 관계로 추가하며, 프로바이더의 args 내부에 넣지 않습니다. args 내부에 있으면 GitLab은 오류 없이 무시하며 이 페이지의 그룹 기반 구성이 전혀 적용되지 않습니다. required_groups, external_groups, admin_groups, auditor_groups에도 동일하게 적용됩니다.

필수 그룹#

IdP는 SAML 응답으로 GitLab에 그룹 정보를 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치입니다.
그룹 설정을 사용한 그룹 또는 사용자에 관한 정보입니다.

required_groups 설정을 사용해 로그인에 필요한 그룹 멤버십을 GitLab 이 식별하도록 구성합니다.

required_groups를 설정하지 않거나 비워두면 올바르게 인증된 사용자는 누구나 서비스를 이용할 수 있습니다.

groups_attribute에 지정한 속성이 잘못되었거나 없으면 모든 사용자가 차단됩니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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 Secret로 사용할 saml.yaml 파일에 넣습니다:

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

외부 그룹#

IdP는 SAML 응답에 그룹 정보를 담아 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치를 지정합니다.
그룹 설정을 사용해 그룹 또는 사용자에 대한 정보를 지정합니다.

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

Note

groups_attribute에 지정한 속성이 잘못되었거나 없으면 해당 사용자는 표준 사용자 권한으로 액세스합니다.

구성 예시:

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

gitlab_rails['omniauth_providers'] = [

  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    external_groups: ['Freelancers'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            # or
            # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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
```

다음 내용을 saml.yaml 파일에 저장해 Kubernetes Secret로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
external_groups: ['Freelancers']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  # or
  # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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-compose.yml 파일을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          { name: 'saml',
            label: 'Our SAML Provider',
            groups_attribute: 'Groups',
            external_groups: ['Freelancers'],
            args: {
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                    idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                    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',
           external_groups: ['Freelancers'],
           args: {
                   assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                   idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                   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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

관리자 그룹#

IdP는 SAML 응답에 그룹 정보를 담아 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치를 지정합니다.
그룹 설정을 사용해 그룹 또는 사용자에 대한 정보를 지정합니다.

admin_groups 설정을 사용해 어느 그룹이 사용자에게 관리자 액세스 권한을 부여할지 GitLab 이 식별하도록 구성합니다.

groups_attribute에 지정한 속성이 잘못되었거나 없으면 사용자는 관리자 액세스 권한을 잃습니다.

구성 예시:

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

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    admin_groups: ['Admins'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            # or
            # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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
```

다음 내용을 saml.yaml 파일에 저장해 Kubernetes Secret로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
admin_groups: ['Admins']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-compose.yml 파일을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             groups_attribute: 'Groups',
             admin_groups: ['Admins'],
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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',
          admin_groups: ['Admins'],
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

감사자 그룹#

IdP는 SAML 응답에 그룹 정보를 담아 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치를 지정합니다.
그룹 설정을 사용해 그룹 또는 사용자에 대한 정보를 지정합니다.

auditor_groups 설정을 사용해 어느 그룹에 감사자 액세스 권한을 가진 사용자가 포함되는지 GitLab 이 식별하도록 구성합니다.

groups_attribute에 지정한 속성이 잘못되었거나 없으면 사용자는 감사자 액세스 권한을 잃습니다.

구성 예시:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

다음 내용을 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

SAML 그룹 동기화 자동 관리#

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

SAML 세션 타임아웃 사용자 지정#

히스토리

GitLab 18.2에서 saml_timeout_supplied_by_idp_override라는 이름의 기능 플래그와 함께 도입되었습니다.
GitLab 18.3에서 활성화되었습니다.

기본적으로 GitLab은 24시간 후 SAML 세션을 종료합니다. SAML2 AuthnStatement의 SessionNotOnOrAfter 속성으로 이 기간을 사용자 지정할 수 있습니다. 이 속성에는 사용자 세션을 언제 종료할지 나타내는 ISO 8601 타임스탬프 값이 포함됩니다. 값을 지정하면 기본 SAML 세션 타임아웃인 24시간을 재정의합니다.

인스턴스에 SessionNotOnOrAfter 타임스탬프보다 이른 사용자 지정 세션 기간이 구성되어 있으면, GitLab 사용자 세션이 종료될 때 사용자는 다시 인증해야 합니다.

2단계 인증 우회#

히스토리

2FA 적용 우회 기능이 GitLab 16.1에서 by_pass_two_factor_current_session이라는 이름의 기능 플래그와 함께 도입되었습니다.
GitLab 17.8에서 활성화되었습니다.

SAML 인증 방법을 세션 단위로 2단계 인증(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 목록에 등록하도록 설치 구성을 편집합니다. SAML 응답의 AuthnContext를 입력해야 합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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 Secret으로 사용할 saml.yaml이라는 이름의 파일에 저장합니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 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',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

응답 서명 검증#

IdP는 어설션이 변조되지 않도록 SAML 응답에 서명해야 합니다.

이렇게 하면 특정 그룹 멤버십이 필요한 경우 사용자 가장 및 권한 상승을 방지할 수 있습니다.

`idp_cert_fingerprint` 사용#

idp_cert_fingerprint를 사용하여 응답 서명 검증을 구성할 수 있습니다. 구성 예시는 다음과 같습니다:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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 Secret으로 사용할 saml.yaml이라는 이름의 파일에 저장합니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

`idp_cert` 사용#

idp_cert를 사용하여 GitLab을 직접 구성할 수도 있습니다. 구성 예시는 다음과 같습니다:

/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: '-----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
```

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

name: 'saml'
label: 'Our SAML Provider'
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-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: '-----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: 'Our SAML Provider',
          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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

응답 서명 검증을 잘못 설정한 경우, 다음과 같은 오류 메시지가 나타날 수 있습니다:

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

이러한 오류를 해결하는 방법에 대한 자세한 내용은 SAML 문제 해결 가이드를 참고합니다.

SAML 설정 사용자 지정#

인증을 위해 사용자를 SAML 서버로 리디렉션#

GitLab 설정에 auto_sign_in_with_provider 설정을 추가하면 인증을 위해 SAML 서버로 자동으로 리디렉션할 수 있습니다. 이렇게 하면 실제로 로그인하기 전에 요소를 선택해야 하는 절차가 사라집니다.

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

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

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

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-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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

로그인을 시도할 때마다 SAML 서버로 리디렉션되므로 로컬 자격 증명으로는 로그인할 수 없습니다. SAML 사용자 중 최소 한 명은 관리자 액세스 권한을 갖도록 합니다.

Note

자동 로그인 설정을 건너뛰려면 로그인 URL에 ?auto_sign_in=false를 추가합니다. 예: https://gitlab.example.com/users/sign_in?auto_sign_in=false.

SAML 응답 속성 이름 매핑#

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

Note

이 설정은 OmniAuth info 해시 스키마에 포함된 속성을 매핑하는 용도로만 사용합니다.

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

이 설정을 사용하면 계정을 생성하는 데 필요한 특정 속성을 GitLab이 어디에서 찾아야 하는지 알려줄 수 있습니다. 예를 들어 IdP(ID 공급자)가 사용자의 이메일 주소를 email 대신 EmailAddress로 전송하는 경우, 설정에서 이를 GitLab에 알려줍니다:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

다음 내용을 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 넣습니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

사용자 이름 설정#

기본적으로 SAML 응답에 포함된 이메일 주소의 로컬 부분을 사용해 사용자의 GitLab 사용자 이름을 생성합니다.

사용자가 원하는 사용자 이름이 담긴 속성을 하나 이상 지정하려면 attribute_statements에서 username 또는 nickname을 구성합니다:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

다음 내용을 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 넣습니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 시크릿을 생성합니다.

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

이렇게 하면 SAML 응답의 username 속성도 GitLab의 사용자 이름으로 설정됩니다.

프로필 속성 매핑#

히스토리

GitLab 17.8에서 job_title 및 organization 속성을 도입했습니다.
GitLab 19.4에서 location 속성을 도입했습니다.

SAML 공급자에서 프로필 정보를 동기화하려면 이 속성을 매핑하도록 attribute_statements를 구성해야 합니다.

지원되는 프로필 속성은 다음과 같습니다.

address
job_title
location
organization

이 속성에는 기본 매핑이 없으며, 명시적으로 구성하지 않으면 동기화되지 않습니다.

Note

address와 location은 모두 사용자 프로필의 위치(location)로 매핑됩니다. 둘 다 정의된 경우 GitLab은 address 값을 사용합니다.

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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: {
              organization: ['organization'],
              job_title: ['job_title'],
              location: ['location']
            }
    }
  }
]

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

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

다음 YAML 내용을 Kubernetes Secret으로 사용할 saml.yaml이라는 파일에 저장합니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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:
    organization: ['organization']
    job_title: ['job_title']
    location: ['location']

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

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: {
                       organization: ['organization'],
                       job_title: ['job_title'],
                       location: ['location']
                     }
             }
           }
        ]

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

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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: {
                    organization: ['organization'],
                    job_title: ['job_title'],
                    location: ['location']
                  }
          }
        }

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

시계 드리프트 허용#

IdP의 시계가 시스템 시계보다 약간 앞서갈 수 있습니다. 약간의 시계 드리프트를 허용하려면 설정에서 allowed_clock_drift를 사용합니다. 이 매개변수의 값은 초 단위의 숫자와 소수로 입력해야 합니다. 지정한 값은 응답을 검증하는 현재 시각에 더해집니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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  # for one second clock drift
    }
  }
]

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

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

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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  # for one second clock drift

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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  # for one second clock drift
             }
           }
        ]

파일을 저장하고 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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  # for one second clock drift
          }
        }

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running 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로 설정합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

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

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

어설션 암호화(선택 사항)#

SAML 어설션 암호화는 선택 사항이지만 사용을 권장합니다. 이 설정은 암호화되지 않은 데이터가 로깅되거나 악의적인 행위자에게 가로채이는 것을 방지하는 추가 보호 계층을 제공합니다.

Note

이 통합에서는 어설션 암호화와 요청 서명 모두에 certificate 및 private_key 설정을 사용합니다.

SAML 어설션을 암호화하려면 GitLab SAML 설정에서 개인 키와 공개 인증서를 정의합니다. IdP는 공개 인증서로 어설션을 암호화하고 GitLab은 개인 키로 어설션을 복호화합니다.

키와 인증서를 정의할 때는 키 파일의 모든 줄바꿈 문자를 \n으로 바꿉니다. 이렇게 하면 키 파일이 줄바꿈 없는 하나의 긴 문자열이 됩니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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-----
            <redacted>
            -----END CERTIFICATE-----,
            private_key:|
            -----BEGIN PRIVATE KEY-----
            <redacted>
            -----END PRIVATE KEY-----
    }
  }
]

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

다음 내용을 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-----
  <redacted>
  ----END CERTIFICATE-----,
  private_key:|
  -----BEGIN PRIVATE KEY-----
  <redacted>
  -----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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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-----
                     <redacted>
                     -----END CERTIFICATE-----,
                     private_key:|
                     -----BEGIN PRIVATE KEY-----
                     <redacted>
                     -----END PRIVATE KEY-----
             }
           }
        ]

파일을 저장하고 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

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

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

서명을 구현하려면 다음과 같이 합니다.

GitLab 인스턴스가 SAML에 사용할 개인 키와 공개 인증서 쌍을 생성합니다.
구성의 security 섹션에서 서명 설정을 구성합니다. 예를 들면 다음과 같습니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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,  # enable signature on AuthNRequest
              want_assertions_signed: true,  # enable the requirement of signed assertion
              want_assertions_encrypted: false,  # enable the requirement of encrypted assertion
              metadata_signed: false,  # enable signature on Metadata
              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
```

다음 내용을 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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  # enable signature on AuthNRequest
    want_assertions_signed: true  # enable the requirement of signed assertion
    want_assertions_encrypted: false  # enable the requirement of encrypted assertion
    metadata_signed: false  # enable signature on Metadata
    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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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,  # enable signature on AuthNRequest
                       want_assertions_signed: true,  # enable the requirement of signed assertion
                       want_assertions_encrypted: false,  # enable the requirement of encrypted assertion
                       metadata_signed: false,  # enable signature on Metadata
                       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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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,  # enable signature on AuthNRequest
                    want_assertions_signed: true,  # enable the requirement of signed assertion
                    want_assertions_encrypted: false,  # enable the requirement of encrypted assertion
                    metadata_signed: false,  # enable signature on Metadata
                    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                  }
          }
        }

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그러면 GitLab은 다음을 수행합니다.

제공된 개인 키로 요청에 서명합니다.
IdP가 수신한 요청의 서명을 검증할 수 있도록 구성된 공개 x500 인증서를 메타데이터에 포함합니다.

이 옵션에 대한 자세한 내용은 Ruby SAML gem 문서를 참고합니다.

Ruby SAML gem은 OmniAuth SAML gem이 SAML 인증의 클라이언트 측을 구현하는 데 사용됩니다.

Note

SAML 리다이렉트 바인딩은 SAML POST 바인딩과 다릅니다. POST 바인딩에서는 중간자가 요청을 변조하지 못하도록 서명이 필요합니다.

SAML로 생성된 사용자의 비밀번호 생성#

GitLab은 SAML로 생성된 사용자의 비밀번호를 생성하고 설정합니다.

SSO 또는 SAML로 인증한 사용자는 HTTPS를 통한 Git 작업에 비밀번호를 사용해서는 안 됩니다. 대신 다음을 사용할 수 있습니다.

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

기존 사용자에 SAML ID 연결#

관리자는 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결하도록 GitLab을 구성할 수 있습니다. 자세한 내용은 GitLab에서 SAML 지원 구성을 참고합니다.

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

GitLab Self-Managed에서 그룹 SAML SSO 구성#

GitLab Self-Managed 인스턴스에서 여러 SAML IdP를 통한 액세스를 허용해야 하는 경우 그룹 SAML SSO를 사용합니다.

그룹 SAML SSO를 구성하려면 다음과 같이 합니다.

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
```

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로 구성되어 있는지 확인합니다.

docker-compose.yml을 편집해 OmniAuth와 group_saml 공급자를 활성화합니다:

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
```

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

/home/git/gitlab/config/gitlab.yml을 편집해 OmniAuth와 group_saml 공급자를 활성화합니다:

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

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

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

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

멀티 테넌트 솔루션이므로 GitLab Self-Managed의 그룹 SAML은 권장되는 인스턴스 전체 SAML에 비해 제한적입니다. 다음을 활용하려면 인스턴스 전체 SAML을 사용합니다:

IdP의 SAML 앱에 대한 추가 구성#

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

필드	값	참고
SAML profile	Web browser SSO profile	GitLab은 SAML을 사용해 브라우저를 통해 사용자를 로그인시킵니다. IdP로 직접 요청을 보내지 않습니다.
SAML request binding	HTTP Redirect	GitLab(SP)은 base64로 인코딩된 `SAMLRequest` HTTP 매개변수와 함께 사용자를 IdP로 리디렉션합니다.
SAML response binding	HTTP POST	IdP가 SAML 토큰을 전송하는 방식을 지정합니다. 사용자의 브라우저가 GitLab으로 다시 제출하는 `SAMLResponse`를 포함합니다.
Sign SAML response	필수	변조를 방지합니다.
X.509 certificate in response	필수	응답에 서명하고 제공된 지문과 응답을 대조합니다.
Fingerprint algorithm	SHA-1	GitLab은 인증서의 SHA-1 해시를 사용해 SAML Response에 서명합니다.
Signature algorithm	SHA-1/SHA-256/SHA-384/SHA-512	응답이 서명되는 방식을 결정합니다. 다이제스트 방법(digest method)이라고도 하며, SAML 응답에서 지정할 수 있습니다.
Encrypt SAML assertion	선택	ID 공급자, 사용자의 브라우저, GitLab 간에 TLS를 사용합니다.
Sign SAML assertion	선택	SAML assertion의 무결성을 검증합니다. 활성화하면 전체 응답에 서명합니다.
Check SAML request signature	선택	SAML 응답의 서명을 확인합니다.
Default RelayState	선택	IdP에서 SAML로 로그인에 성공한 후 사용자가 도달해야 하는 기본 URL의 하위 경로를 지정합니다.
NameID format	Persistent	NameID format 세부 정보를 참고합니다.
Additional URLs	선택	일부 공급자에서는 다른 필드에 issuer, identifier 또는 assertion consumer service URL 이 포함될 수 있습니다.

예시 구성은 특정 공급자에 대한 참고 사항을 참고합니다.

Geo에서 SAML 구성#

Geo에서 SAML을 구성하려면 인스턴스 전체 SAML 구성을 참고합니다.

자세한 내용은 Geo와 Single Sign On(SSO)를 참고합니다.

문제 해결#

SAML 문제 해결 가이드를 참고합니다.

SAML SSO 인테그레이션

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

Note

GitLab.com의 경우 GitLab.com 그룹의 SAML SSO를 참고합니다.

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

다음 항목에 대한 자세한 내용은 아래를 참고합니다:

OmniAuth 공급자 설정: OmniAuth 문서를 참고합니다.
자주 사용하는 용어: 용어집을 참고합니다.

GitLab에서 SAML 지원 구성#

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 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

/etc/gitlab/gitlab.rb를 편집하여 공급자 구성을 추가합니다:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml", # This must be lowercase.
    label: "Provider name", # optional label for login button, defaults to "Saml"
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
      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"
    }
  }
]

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

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

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

선택 사항입니다. 이메일 주소가 일치하면 gitlab_values.yaml에 다음 설정을 추가하여 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
```
global:
  appConfig:
    omniauth:
      autoLinkSamlUser: true
```
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

다음 내용을 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 작성합니다:

name: 'saml'
label: 'Provider name' # optional label for login button, defaults to "Saml"
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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'

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

Kubernetes 시크릿을 생성합니다:

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

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

선택 사항입니다. 이메일 주소가 일치하면 docker-compose.yml에 다음 설정을 추가하여 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
```
version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_auto_link_saml_user'] = true
```
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

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

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          {
            name: "saml",
            label: "Provider name", # optional label for login button, defaults to "Saml"
            args: {
              assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
              idp_cert_fingerprint: "2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6",
              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"
            }
          }
        ]

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

파일을 저장하고 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
```
선택 사항입니다. 이메일 주소가 일치하면 /home/git/gitlab/config/gitlab.yml에 다음 설정을 추가하여 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결할 수 있습니다:
```
production: &base
  omniauth:
    auto_link_saml_user: true
```
또는 사용자가 기존 사용자에 대해 OmniAuth 활성화를 통해 SAML 아이덴티티를 기존 GitLab 계정에 수동으로 연결할 수도 있습니다.
SAML 사용자가 다음 속성을 변경할 수 없도록 구성합니다:
- NameID.
- omniauth_auto_link_saml_user와 함께 사용하는 경우 Email.
사용자가 이러한 속성을 변경할 수 있으면 다른 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법은 사용 중인 SAML IdP 문서를 참고합니다.

/home/git/gitlab/config/gitlab.yml을 편집하여 공급자 구성을 추가합니다:

omniauth:
  providers:
    - {
      name: 'saml',
      label: 'Provider name', # optional label for login button, defaults to "Saml"
      args: {
        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
        idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
        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'
      }
    }

Argument	Description
`assertion_consumer_service_url`	GitLab HTTPS 엔드포인트입니다(GitLab 설치 환경의 HTTPS URL 뒤에 `/users/auth/saml/callback`을 붙입니다).
`idp_cert_fingerprint`	IdP 값입니다. 인증서에서 SHA256 지문을 생성하려면 지문 계산을 참고합니다.
`idp_sso_target_url`	IdP 값입니다.
`issuer`	애플리케이션을 IdP에 식별시키는 고유한 이름으로 변경합니다.
`name_identifier_format`	IdP 값입니다.

이러한 값에 대한 자세한 내용은 OmniAuth SAML 문서를 참고합니다. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 구성하기를 참고합니다.

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

SAML IdP에 GitLab 등록#

issuer에 지정한 애플리케이션 이름을 사용하여 SAML IdP에 GitLab SP를 등록합니다.
IdP에 구성 정보를 제공하려면 애플리케이션의 메타데이터 URL을 빌드합니다. GitLab의 메타데이터 URL을 빌드하려면 GitLab 설치 환경의 HTTPS URL 뒤에 users/auth/saml/metadata를 붙입니다. 예를 들면 다음과 같습니다:
```
https://gitlab.example.com/users/auth/saml/metadata
```
IdP는 최소한 email 또는 mail을 사용하여 사용자의 이메일 주소가 담긴 클레임을 제공해야 합니다. 사용 가능한 다른 클레임에 대한 자세한 내용은 어설션 구성을 참고합니다.
이제 로그인 페이지의 일반 로그인 폼 아래에 SAML 아이콘이 표시됩니다. 인증 과정을 시작하려면 아이콘을 선택합니다. 인증에 성공하면 GitLab으로 돌아가 로그인됩니다.

IdP에서 SAML 구성하기#

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

어설션 소비자 서비스 URL.
발급자(Issuer).
NameID.
이메일 주소 클레임.

예시 구성은 ID 공급자 설정을 참고합니다.

IdP에 추가 구성이 필요할 수 있습니다. 자세한 내용은 IdP의 SAML 애플리케이션 추가 구성을 참고합니다.

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

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

각 공급자에 args에 설정된 이름과 일치하는 고유한 이름 세트가 있습니다.
공급자 이름은 다음 용도로 사용됩니다:
- 공급자 이름을 기준으로 하는 속성에 대한 OmniAuth 구성에서 사용됩니다. 예를 들어 allowBypassTwoFactor, allowSingleSignOn, syncProfileFromProvider가 있습니다.
- 각 기존 사용자와 추가 아이덴티티로 연결하는 데 사용됩니다.
assertion_consumer_service_url 이 공급자 이름과 일치합니다.
공급자 이름에서 유추할 수 없으므로 strategy_class를 명시적으로 설정합니다.

Note

여러 SAML IdP를 설정하려면:

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

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml', # This must match the following name configuration parameter
    label: 'Provider 1' # Differentiate the two buttons and providers in the UI
    args: {
            name: 'saml', # This is mandatory and must match the provider name
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
            strategy_class: 'OmniAuth::Strategies::SAML',
            # Include all required arguments similar to a single provider
          },
  },
  {
    name: 'saml_2', # This must match the following name configuration parameter
    label: 'Provider 2' # Differentiate the two buttons and providers in the UI
    args: {
            name: 'saml_2', # This is mandatory and must match the provider name
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
            strategy_class: 'OmniAuth::Strategies::SAML',
            # Include all required arguments similar to a single provider
          },
  }
]

사용자가 먼저 두 공급자 중 하나로 수동으로 계정을 만들지 않고도 SAML로 계정을 만들 수 있도록 하려면 다음 값을 구성에 추가합니다:

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

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

다음 내용을 첫 번째 SAML 공급자에 대해 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 작성합니다:

name: 'saml' # At least one provider must be named 'saml'
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
args:
  name: 'saml' # This is mandatory and must match the provider name
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL must match the name of the provider
  strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory
  # Include all required arguments similar to a single provider

다음 내용을 두 번째 SAML 공급자에 대해 Kubernetes 시크릿으로 사용할 saml_2.yaml 파일에 작성합니다:

name: 'saml_2'
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
args:
  name: 'saml_2' # This is mandatory and must match the provider name
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL must match the name of the provider
  strategy_class: 'OmniAuth::Strategies::SAML' # Mandatory
  # Include all required arguments similar to a single provider

선택 사항입니다. 같은 단계를 따라 SAML 공급자를 추가로 설정합니다.

Kubernetes 시크릿을 생성합니다:

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']

Save the file and apply the new values:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

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', # This must match the following name configuration parameter
            label: 'Provider 1' # Differentiate the two buttons and providers in the UI
            args: {
                    name: 'saml', # This is mandatory and must match the provider name
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    # Include all required arguments similar to a single provider
                  },
          },
          {
            name: 'saml_2', # This must match the following name configuration parameter
            label: 'Provider 2' # Differentiate the two buttons and providers in the UI
            args: {
                    name: 'saml_2', # This is mandatory and must match the provider name
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
                    strategy_class: 'OmniAuth::Strategies::SAML',
                    # Include all required arguments similar to a single provider
                  },
          }
        ]

프로바이더 중 어느 쪽에서도 계정을 수동으로 만들지 않고 사용자가 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', # This must match the following name configuration parameter
        label: 'Provider 1' # Differentiate the two buttons and providers in the UI
        args: {
          name: 'saml', # This is mandatory and must match the provider name
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL must match the name of the provider
          strategy_class: 'OmniAuth::Strategies::SAML',
          # Include all required arguments similar to a single provider
        },
      }
      - {
        name: 'saml_2', # This must match the following name configuration parameter
        label: 'Provider 2' # Differentiate the two buttons and providers in the UI
        args: {
          name: 'saml_2', # This is mandatory and must match the provider name
          strategy_class: 'OmniAuth::Strategies::SAML',
          assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
          # Include all required arguments similar to a single provider
        },
      }

프로바이더 중 어느 쪽에서도 계정을 수동으로 만들지 않고 사용자가 SAML로 계정을 생성할 수 있도록 하려면 구성에 다음 값을 추가합니다:

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

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

ID 공급자 설정#

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

Okta 설정#

Okta 관리자 섹션에서 Applications를 선택합니다.
앱 화면에서 Create App Integration을 선택하고 다음 화면에서 SAML 2.0을 선택합니다.
선택 사항입니다. GitLab Press에서 로고를 선택해 추가합니다. 로고는 자르고 크기를 조정해야 합니다.
SAML 일반 구성을 완료합니다. 다음을 입력합니다:
- "Single sign-on URL": assertion consumer service URL을 사용합니다.
- "Audience URI": issuer를 사용합니다.
- 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 account.

Google Workspace를 설정하려면:

다음 정보를 사용해 아래 안내를 따릅니다. Set up your own custom SAML application in Google Workspace.

	일반적인 값	설명
SAML 앱 이름	GitLab	다른 이름도 사용할 수 있습니다.
ACS URL	`https:///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 format	`EMAIL`	필수 값입니다. `name_identifier_format` 라고도 합니다.
Name ID	기본 이메일 주소	이메일 주소입니다. 해당 주소로 발송된 내용을 누군가 수신하는지 확인합니다.
First name	`first_name`	이름입니다. GitLab과 통신하는 데 필요한 값입니다.
Last name	`last_name`	성입니다. GitLab과 통신하는 데 필요한 값입니다.

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

Google Directory attributes App attributes

Basic information > Email email

Basic Information > First name first_name

Basic Information > Last name last_name

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

Google Directory attributes	App attributes
Basic information > Email	`email`
Basic Information > First name	`first_name`
Basic Information > Last name	`last_name`

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

	값	설명
SSO URL	환경에 따라 다름	Google Identity Provider 세부 정보입니다. GitLab `idp_sso_target_url` 설정으로 지정합니다.
Certificate	다운로드 가능	Google SAML 인증서입니다.
SHA256 fingerprint	환경에 따라 다름	인증서를 다운로드하면 확인할 수 있습니다. 인증서에서 SHA256 fingerprint를 생성하는 방법은 fingerprint 계산을 참고합니다.

Microsoft Entra ID 설정#

Microsoft Entra admin center에 로그인합니다.
비 갤러리 애플리케이션을 생성합니다.

해당 애플리케이션에 SSO를 구성합니다.

gitlab.rb 파일의 다음 설정은 Microsoft Entra ID 필드에 대응합니다:

`gitlab.rb` setting	Microsoft Entra ID field
`issuer`	Identifier (Entity ID)
`assertion_consumer_service_url`	Reply URL (Assertion Consumer Service URL)
`idp_sso_target_url`	Login URL
`idp_cert_fingerprint`	Thumbprint

다음 속성을 설정합니다:
- **Unique User Identifier (Name ID)**를 user.objectID로 설정합니다.
  - Name identifier format을 persistent로 설정합니다. 자세한 내용은 사용자 SAML ID 관리 방법을 참고합니다.
- Additional claims는 지원되는 속성으로 설정합니다.

자세한 내용은 구성 예시 페이지를 참고합니다.

기타 IdP 설정#

일부 IdP는 SAML 구성에서 IdP로 사용하는 방법에 관한 문서를 제공합니다. 예를 들면 다음과 같습니다:

SAML 구성에서 IdP를 구성하는 데 관해 궁금한 점이 있으면 해당 프로바이더의 지원팀에 문의합니다.

Assertion 구성#

Note

이 속성은 대소문자를 구분합니다.

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

GitLab은 SAML SSO 프로바이더로부터 SAML 응답을 받으면 속성의 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

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를 참고합니다:

커스텀 assertion 구성 예시입니다.
커스텀 사용자 이름 속성을 구성하는 방법입니다.

지원되는 assertion 전체 목록은 OmniAuth SAML gem을 참고합니다.

SAML 그룹 멤버십을 기준으로 사용자 구성#

다음을 수행할 수 있습니다:

사용자가 특정 그룹의 구성원이어야 하도록 요구합니다.
그룹 멤버십을 기준으로 사용자에게 외부, 관리자, 또는 감사자 권한을 할당합니다.

이 그룹 지원 여부는 다음에 따라 달라집니다:

구독 등급입니다.
GitLab Enterprise Edition (EE) 설치 여부입니다.

Group	Tier	GitLab Enterprise Edition (EE) Only?
필수	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: 요소를 추가합니다. 이 속성은 대소문자를 구분합니다.

groups_attribute는 SAML 설정의 프로바이더 레벨에서 name 및 label과 형제 관계로 추가하며, 프로바이더의 args 내부에 넣지 않습니다. args 내부에 있으면 GitLab은 오류 없이 무시하며 이 페이지의 그룹 기반 구성이 전혀 적용되지 않습니다. required_groups, external_groups, admin_groups, auditor_groups에도 동일하게 적용됩니다.

필수 그룹#

IdP는 SAML 응답으로 GitLab에 그룹 정보를 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치입니다.
그룹 설정을 사용한 그룹 또는 사용자에 관한 정보입니다.

required_groups 설정을 사용해 로그인에 필요한 그룹 멤버십을 GitLab 이 식별하도록 구성합니다.

required_groups를 설정하지 않거나 비워두면 올바르게 인증된 사용자는 누구나 서비스를 이용할 수 있습니다.

groups_attribute에 지정한 속성이 잘못되었거나 없으면 모든 사용자가 차단됩니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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 Secret로 사용할 saml.yaml 파일에 넣습니다:

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

외부 그룹#

IdP는 SAML 응답에 그룹 정보를 담아 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치를 지정합니다.
그룹 설정을 사용해 그룹 또는 사용자에 대한 정보를 지정합니다.

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

Note

groups_attribute에 지정한 속성이 잘못되었거나 없으면 해당 사용자는 표준 사용자 권한으로 액세스합니다.

구성 예시:

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

gitlab_rails['omniauth_providers'] = [

  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    external_groups: ['Freelancers'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            # or
            # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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
```

다음 내용을 saml.yaml 파일에 저장해 Kubernetes Secret로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
external_groups: ['Freelancers']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  # or
  # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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-compose.yml 파일을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
          { name: 'saml',
            label: 'Our SAML Provider',
            groups_attribute: 'Groups',
            external_groups: ['Freelancers'],
            args: {
                    assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                    idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                    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',
           external_groups: ['Freelancers'],
           args: {
                   assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                   idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                   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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

관리자 그룹#

IdP는 SAML 응답에 그룹 정보를 담아 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치를 지정합니다.
그룹 설정을 사용해 그룹 또는 사용자에 대한 정보를 지정합니다.

admin_groups 설정을 사용해 어느 그룹이 사용자에게 관리자 액세스 권한을 부여할지 GitLab 이 식별하도록 구성합니다.

groups_attribute에 지정한 속성이 잘못되었거나 없으면 사용자는 관리자 액세스 권한을 잃습니다.

구성 예시:

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

gitlab_rails['omniauth_providers'] = [
  { name: 'saml',
    label: 'Our SAML Provider',
    groups_attribute: 'Groups',
    admin_groups: ['Admins'],
    args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            # or
            # idp_cert: '-----BEGIN CERTIFICATE-----\n ... \n-----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
```

다음 내용을 saml.yaml 파일에 저장해 Kubernetes Secret로 사용합니다:

name: 'saml'
label: 'Our SAML Provider'
groups_attribute: 'Groups'
admin_groups: ['Admins']
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-compose.yml 파일을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_providers'] = [
           { name: 'saml',
             label: 'Our SAML Provider',
             groups_attribute: 'Groups',
             admin_groups: ['Admins'],
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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',
          admin_groups: ['Admins'],
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

감사자 그룹#

IdP는 SAML 응답에 그룹 정보를 담아 GitLab에 전달합니다. 이 응답을 사용하려면 GitLab 이 다음을 식별하도록 구성합니다:

groups_attribute 설정을 사용해 SAML 응답에서 그룹을 찾을 위치를 지정합니다.
그룹 설정을 사용해 그룹 또는 사용자에 대한 정보를 지정합니다.

auditor_groups 설정을 사용해 어느 그룹에 감사자 액세스 권한을 가진 사용자가 포함되는지 GitLab 이 식별하도록 구성합니다.

groups_attribute에 지정한 속성이 잘못되었거나 없으면 사용자는 감사자 액세스 권한을 잃습니다.

구성 예시:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

다음 내용을 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

SAML 그룹 동기화 자동 관리#

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

SAML 세션 타임아웃 사용자 지정#

히스토리

GitLab 18.2에서 saml_timeout_supplied_by_idp_override라는 이름의 기능 플래그와 함께 도입되었습니다.
GitLab 18.3에서 활성화되었습니다.

2단계 인증 우회#

히스토리

2FA 적용 우회 기능이 GitLab 16.1에서 by_pass_two_factor_current_session이라는 이름의 기능 플래그와 함께 도입되었습니다.
GitLab 17.8에서 활성화되었습니다.

SAML 인증 방법을 세션 단위로 2단계 인증(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 목록에 등록하도록 설치 구성을 편집합니다. SAML 응답의 AuthnContext를 입력해야 합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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 Secret으로 사용할 saml.yaml이라는 이름의 파일에 저장합니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 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',
             args: {
                     assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                     idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

응답 서명 검증#

IdP는 어설션이 변조되지 않도록 SAML 응답에 서명해야 합니다.

이렇게 하면 특정 그룹 멤버십이 필요한 경우 사용자 가장 및 권한 상승을 방지할 수 있습니다.

`idp_cert_fingerprint` 사용#

idp_cert_fingerprint를 사용하여 응답 서명 검증을 구성할 수 있습니다. 구성 예시는 다음과 같습니다:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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 Secret으로 사용할 saml.yaml이라는 이름의 파일에 저장합니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

`idp_cert` 사용#

idp_cert를 사용하여 GitLab을 직접 구성할 수도 있습니다. 구성 예시는 다음과 같습니다:

/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: '-----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
```

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

name: 'saml'
label: 'Our SAML Provider'
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-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: '-----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: 'Our SAML Provider',
          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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

응답 서명 검증을 잘못 설정한 경우, 다음과 같은 오류 메시지가 나타날 수 있습니다:

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

이러한 오류를 해결하는 방법에 대한 자세한 내용은 SAML 문제 해결 가이드를 참고합니다.

SAML 설정 사용자 지정#

인증을 위해 사용자를 SAML 서버로 리디렉션#

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

gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

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

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-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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

Note

자동 로그인 설정을 건너뛰려면 로그인 URL에 ?auto_sign_in=false를 추가합니다. 예: https://gitlab.example.com/users/sign_in?auto_sign_in=false.

SAML 응답 속성 이름 매핑#

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

Note

이 설정은 OmniAuth info 해시 스키마에 포함된 속성을 매핑하는 용도로만 사용합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

다음 내용을 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 넣습니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

사용자 이름 설정#

기본적으로 SAML 응답에 포함된 이메일 주소의 로컬 부분을 사용해 사용자의 GitLab 사용자 이름을 생성합니다.

사용자가 원하는 사용자 이름이 담긴 속성을 하나 이상 지정하려면 attribute_statements에서 username 또는 nickname을 구성합니다:

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

다음 내용을 Kubernetes 시크릿으로 사용할 saml.yaml 파일에 넣습니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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 시크릿을 생성합니다.

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

이렇게 하면 SAML 응답의 username 속성도 GitLab의 사용자 이름으로 설정됩니다.

프로필 속성 매핑#

히스토리

GitLab 17.8에서 job_title 및 organization 속성을 도입했습니다.
GitLab 19.4에서 location 속성을 도입했습니다.

SAML 공급자에서 프로필 정보를 동기화하려면 이 속성을 매핑하도록 attribute_statements를 구성해야 합니다.

지원되는 프로필 속성은 다음과 같습니다.

address
job_title
location
organization

이 속성에는 기본 매핑이 없으며, 명시적으로 구성하지 않으면 동기화되지 않습니다.

Note

address와 location은 모두 사용자 프로필의 위치(location)로 매핑됩니다. 둘 다 정의된 경우 GitLab은 address 값을 사용합니다.

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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: {
              organization: ['organization'],
              job_title: ['job_title'],
              location: ['location']
            }
    }
  }
]

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

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

다음 YAML 내용을 Kubernetes Secret으로 사용할 saml.yaml이라는 파일에 저장합니다:

name: 'saml'
label: 'Our SAML Provider'
args:
  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
  idp_cert_fingerprint: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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:
    organization: ['organization']
    job_title: ['job_title']
    location: ['location']

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

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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: {
                       organization: ['organization'],
                       job_title: ['job_title'],
                       location: ['location']
                     }
             }
           }
        ]

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

원하는 속성을 동기화하도록 OmniAuth를 구성합니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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: {
                    organization: ['organization'],
                    job_title: ['job_title'],
                    location: ['location']
                  }
          }
        }

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

시계 드리프트 허용#

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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  # for one second clock drift
    }
  }
]

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

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

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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  # for one second clock drift

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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  # for one second clock drift
             }
           }
        ]

파일을 저장하고 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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  # for one second clock drift
          }
        }

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

`uid`에 대한 고유 속성 지정(선택 사항)#

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

uid를 고유 속성으로 설정하기 전에, SAML 사용자가 변경할 수 없도록 다음 속성이 구성되어 있는지 확인합니다:

NameID.
omniauth_auto_link_saml_user와 함께 사용하는 경우의 Email.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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
```

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

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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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
```

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

어설션 암호화(선택 사항)#

Note

이 통합에서는 어설션 암호화와 요청 서명 모두에 certificate 및 private_key 설정을 사용합니다.

키와 인증서를 정의할 때는 키 파일의 모든 줄바꿈 문자를 \n으로 바꿉니다. 이렇게 하면 키 파일이 줄바꿈 없는 하나의 긴 문자열이 됩니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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-----
            <redacted>
            -----END CERTIFICATE-----,
            private_key:|
            -----BEGIN PRIVATE KEY-----
            <redacted>
            -----END PRIVATE KEY-----
    }
  }
]

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

다음 내용을 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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-----
  <redacted>
  ----END CERTIFICATE-----,
  private_key:|
  -----BEGIN PRIVATE KEY-----
  <redacted>
  -----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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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-----
                     <redacted>
                     -----END CERTIFICATE-----,
                     private_key:|
                     -----BEGIN PRIVATE KEY-----
                     <redacted>
                     -----END PRIVATE KEY-----
             }
           }
        ]

파일을 저장하고 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

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

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

서명을 구현하려면 다음과 같이 합니다.

GitLab 인스턴스가 SAML에 사용할 개인 키와 공개 인증서 쌍을 생성합니다.
구성의 security 섹션에서 서명 설정을 구성합니다. 예를 들면 다음과 같습니다.

/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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
            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,  # enable signature on AuthNRequest
              want_assertions_signed: true,  # enable the requirement of signed assertion
              want_assertions_encrypted: false,  # enable the requirement of encrypted assertion
              metadata_signed: false,  # enable signature on Metadata
              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
```

다음 내용을 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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6'
  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  # enable signature on AuthNRequest
    want_assertions_signed: true  # enable the requirement of signed assertion
    want_assertions_encrypted: false  # enable the requirement of encrypted assertion
    metadata_signed: false  # enable signature on Metadata
    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-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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                     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,  # enable signature on AuthNRequest
                       want_assertions_signed: true,  # enable the requirement of signed assertion
                       want_assertions_encrypted: false,  # enable the requirement of encrypted assertion
                       metadata_signed: false,  # enable signature on Metadata
                       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: '2f:cb:19:57:68:c3:9e:9a:94:ce:c2:c2:e3:2c:59:c0:aa:d7:a3:36:5c:10:89:2e:81:16:b5:d8:3d:40:96:b6',
                  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,  # enable signature on AuthNRequest
                    want_assertions_signed: true,  # enable the requirement of signed assertion
                    want_assertions_encrypted: false,  # enable the requirement of encrypted assertion
                    metadata_signed: false,  # enable signature on Metadata
                    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                  }
          }
        }

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

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그러면 GitLab은 다음을 수행합니다.

제공된 개인 키로 요청에 서명합니다.
IdP가 수신한 요청의 서명을 검증할 수 있도록 구성된 공개 x500 인증서를 메타데이터에 포함합니다.

이 옵션에 대한 자세한 내용은 Ruby SAML gem 문서를 참고합니다.

Ruby SAML gem은 OmniAuth SAML gem이 SAML 인증의 클라이언트 측을 구현하는 데 사용됩니다.

Note

SAML 리다이렉트 바인딩은 SAML POST 바인딩과 다릅니다. POST 바인딩에서는 중간자가 요청을 변조하지 못하도록 서명이 필요합니다.

SAML로 생성된 사용자의 비밀번호 생성#

GitLab은 SAML로 생성된 사용자의 비밀번호를 생성하고 설정합니다.

SSO 또는 SAML로 인증한 사용자는 HTTPS를 통한 Git 작업에 비밀번호를 사용해서는 안 됩니다. 대신 다음을 사용할 수 있습니다.

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

기존 사용자에 SAML ID 연결#

관리자는 SAML 사용자를 기존 GitLab 사용자와 자동으로 연결하도록 GitLab을 구성할 수 있습니다. 자세한 내용은 GitLab에서 SAML 지원 구성을 참고합니다.

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

GitLab Self-Managed에서 그룹 SAML SSO 구성#

GitLab Self-Managed 인스턴스에서 여러 SAML IdP를 통한 액세스를 허용해야 하는 경우 그룹 SAML SSO를 사용합니다.

그룹 SAML SSO를 구성하려면 다음과 같이 합니다.

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
```

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로 구성되어 있는지 확인합니다.

docker-compose.yml을 편집해 OmniAuth와 group_saml 공급자를 활성화합니다:

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
```

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

/home/git/gitlab/config/gitlab.yml을 편집해 OmniAuth와 group_saml 공급자를 활성화합니다:

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

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

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

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

IdP의 SAML 앱에 대한 추가 구성#

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

필드	값	참고
SAML profile	Web browser SSO profile	GitLab은 SAML을 사용해 브라우저를 통해 사용자를 로그인시킵니다. IdP로 직접 요청을 보내지 않습니다.
SAML request binding	HTTP Redirect	GitLab(SP)은 base64로 인코딩된 `SAMLRequest` HTTP 매개변수와 함께 사용자를 IdP로 리디렉션합니다.
SAML response binding	HTTP POST	IdP가 SAML 토큰을 전송하는 방식을 지정합니다. 사용자의 브라우저가 GitLab으로 다시 제출하는 `SAMLResponse`를 포함합니다.
Sign SAML response	필수	변조를 방지합니다.
X.509 certificate in response	필수	응답에 서명하고 제공된 지문과 응답을 대조합니다.
Fingerprint algorithm	SHA-1	GitLab은 인증서의 SHA-1 해시를 사용해 SAML Response에 서명합니다.
Signature algorithm	SHA-1/SHA-256/SHA-384/SHA-512	응답이 서명되는 방식을 결정합니다. 다이제스트 방법(digest method)이라고도 하며, SAML 응답에서 지정할 수 있습니다.
Encrypt SAML assertion	선택	ID 공급자, 사용자의 브라우저, GitLab 간에 TLS를 사용합니다.
Sign SAML assertion	선택	SAML assertion의 무결성을 검증합니다. 활성화하면 전체 응답에 서명합니다.
Check SAML request signature	선택	SAML 응답의 서명을 확인합니다.
Default RelayState	선택	IdP에서 SAML로 로그인에 성공한 후 사용자가 도달해야 하는 기본 URL의 하위 경로를 지정합니다.
NameID format	Persistent	NameID format 세부 정보를 참고합니다.
Additional URLs	선택	일부 공급자에서는 다른 필드에 issuer, identifier 또는 assertion consumer service URL 이 포함될 수 있습니다.

예시 구성은 특정 공급자에 대한 참고 사항을 참고합니다.

Geo에서 SAML 구성#

Geo에서 SAML을 구성하려면 인스턴스 전체 SAML 구성을 참고합니다.

자세한 내용은 Geo와 Single Sign On(SSO)를 참고합니다.

문제 해결#

SAML 문제 해결 가이드를 참고합니다.

SAML SSO 인테그레이션

GitLab에서 SAML 지원 구성#

SAML IdP에 GitLab 등록#

IdP에서 SAML 구성하기#

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

ID 공급자 설정#

Okta 설정#

Google Workspace 설정#

Microsoft Entra ID 설정#

기타 IdP 설정#

Assertion 구성#

SAML 그룹 멤버십을 기준으로 사용자 구성#

필수 그룹#

외부 그룹#

관리자 그룹#

감사자 그룹#

SAML 그룹 동기화 자동 관리#

SAML 세션 타임아웃 사용자 지정#

2단계 인증 우회#

응답 서명 검증#

idp_cert_fingerprint 사용#

idp_cert 사용#

SAML 설정 사용자 지정#

인증을 위해 사용자를 SAML 서버로 리디렉션#

SAML 응답 속성 이름 매핑#

사용자 이름 설정#

프로필 속성 매핑#

시계 드리프트 허용#

uid에 대한 고유 속성 지정(선택 사항)#

어설션 암호화(선택 사항)#

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

SAML로 생성된 사용자의 비밀번호 생성#

기존 사용자에 SAML ID 연결#

GitLab Self-Managed에서 그룹 SAML SSO 구성#

IdP의 SAML 앱에 대한 추가 구성#

Geo에서 SAML 구성#

문제 해결#

SAML SSO 인테그레이션

GitLab에서 SAML 지원 구성#

SAML IdP에 GitLab 등록#

IdP에서 SAML 구성하기#

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

ID 공급자 설정#

Okta 설정#

Google Workspace 설정#

Microsoft Entra ID 설정#

기타 IdP 설정#

Assertion 구성#

SAML 그룹 멤버십을 기준으로 사용자 구성#

필수 그룹#

외부 그룹#

관리자 그룹#

감사자 그룹#

SAML 그룹 동기화 자동 관리#

SAML 세션 타임아웃 사용자 지정#

2단계 인증 우회#

응답 서명 검증#

idp_cert_fingerprint 사용#

idp_cert 사용#

SAML 설정 사용자 지정#

인증을 위해 사용자를 SAML 서버로 리디렉션#

SAML 응답 속성 이름 매핑#

사용자 이름 설정#

프로필 속성 매핑#

시계 드리프트 허용#

uid에 대한 고유 속성 지정(선택 사항)#

어설션 암호화(선택 사항)#

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

SAML로 생성된 사용자의 비밀번호 생성#

기존 사용자에 SAML ID 연결#

GitLab Self-Managed에서 그룹 SAML SSO 구성#

IdP의 SAML 앱에 대한 추가 구성#

Geo에서 SAML 구성#

문제 해결#

`idp_cert_fingerprint` 사용#

`idp_cert` 사용#

`uid`에 대한 고유 속성 지정(선택 사항)#

`idp_cert_fingerprint` 사용#

`idp_cert` 사용#

`uid`에 대한 고유 속성 지정(선택 사항)#