Self-managed GitLab 인스턴스용 SAML SSO

Tier: Free, Premium, Ultimate Offering: Self-Managed

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

GitLab을 SAML 서비스 제공자 (SP)로 구성할 수 있습니다. 이를 통해 GitLab이 Okta와 같은 SAML 식별 공급자 (IdP)로부터 assertions을 수신하여 사용자를 인증할 수 있습니다.

GitLab.com에서 SAML을 설정하는 방법은 SAML SSO for GitLab.com groups를 참조하십시오.

더 자세한 정보는 다음을 참조하십시오:

GitLab에서 SAML 지원 구성하기

Linux package (Omnibus)
  1. GitLab이 HTTPS로 구성되었는지 확인하십시오.
  2. saml을 단일 로그인 제공자로 추가할 수 있도록 공통 설정을 구성하십시오. 이렇게 함으로써 기존 GitLab 계정이 없는 사용자에 대한 즉시 계정 프로비저닝이 가능해집니다.
  3. 사용자가 수동으로 계정을 만들지 않고도 SAML을 사용하여 가입할 수 있도록 /etc/gitlab/gitlab.rb을 편집하십시오:

    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
    gitlab_rails['omniauth_block_auto_created_users'] = false
    
  4. 선택 사항. 사용자가 SAML로 첫 번째 로그인을 자동으로 기존 GitLab 사용자와 연결되도록 해야 합니다. 이를 위해 /etc/gitlab/gitlab.rb에 다음 설정을 추가하십시오:

    gitlab_rails['omniauth_auto_link_saml_user'] = true
    

    이 설정은 GitLab 계정의 기본 이메일 주소만 SAML 응답의 이메일과 일치시킵니다.

    또는 사용자는 기존 GitLab 계정에 수동으로 SAML ID를 연결하여 사용할 수 있습니다(기존 사용자를 위해 OmniAuth 활성화).

  5. 다음과 같은 속성을 구성하여 SAML 사용자가 이를 변경할 수 없도록 하십시오.

    • NameID.
    • omniauth_auto_link_saml_user를 사용할 때 이메일입니다.

    사용자가 이러한 속성을 변경할 수있는 경우 권한이 있는 사용자로 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록하는 방법에 대해서는 SAML IdP 문서를 참조하십시오.

  6. /etc/gitlab/gitlab.rb을 편집하고 프로바이더 설정을 추가하십시오:

    gitlab_rails['omniauth_providers'] = [
      {
        name: "saml",
        label: "Provider name", # 로그인 버튼에 대한 선택 사항 레이블, 기본값은 "Saml"
        args: {
          assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
          idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
          idp_sso_target_url: "https://login.example.com/idp",
          issuer: "https://gitlab.example.com",
          name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
        }
      }
    ]
    

    여기서:

    • assertion_consumer_service_url: GitLab HTTPS 엔드포인트 (GitLab 설치의 HTTPS URL에 /users/auth/saml/callback을 추가하십시오).
    • idp_cert_fingerprint: IdP 값입니다. 반드시 SHA1 지문이어야 합니다. 이러한 값에 대한 자세한 정보는 OmniAuth SAML 문서를 참조하십시오. 다른 구성 설정에 대한 자세한 내용은 IdP에서 SAML 설정을 참조하십시오.
    • idp_sso_target_url: IdP 값입니다.
    • issuer: IdP에 대한 응용 프로그램을 식별하는 고유한 이름으로 변경하십시오.
    • name_identifier_format: IdP 값입니다.
  7. 파일을 저장하고 GitLab을 다시 구성하십시오:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)

(이하 생략)

Docker

(이하 생략)

Self-compiled (source)

(이하 생략)

SAML IdP에 GitLab 등록하기

  1. 발급자에 지정된 애플리케이션 이름을 사용하여 SAML IdP에 GitLab SP를 등록합니다.

  2. IdP에 구성 정보를 제공하려면 애플리케이션의 메타데이터 URL을 생성합니다. GitLab의 메타데이터 URL을 생성하려면 GitLab 설치의 HTTPS URL에 users/auth/saml/metadata를 추가합니다. 예를 들어:

    https://gitlab.example.com/users/auth/saml/metadata
    

    적어도 IdP는 email 또는 mail을 사용하여 사용자 이메일 주소를 포함한 클레임을 제공해야 합니다. 다른 사용 가능한 클레임에 대한 자세한 정보는 assertions 구성을 참조하십시오.

  3. 로그인 페이지에 일반적인 로그인 양식 아래에 SAML 아이콘이 표시되어야 합니다. 아이콘을 선택하여 인증 프로세스를 시작합니다. 인증에 성공하면 GitLab으로 돌아가서 로그인됩니다.

IdP에서 SAML 구성하기

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

구성 예시는 identity providers 설정을 참조하십시오.

IdP에서 추가 구성이 필요할 수 있습니다. 자세한 정보는 IdP에서 SAML 앱을 위한 추가 구성을 참조하십시오.

GitLab에서 여러 SAML IdP 사용 설정하기

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

  • 각 제공 업체에는 args와 일치하는 고유한 이름 집합이 있어야 합니다. 최소한 하나의 제공 업체는 GitLab 14.6 이후의 알려진 문제를 완화하기 위해 saml 이름을 가져야 합니다.
  • 제공 업체의 이름은 다음과 같이 사용됩니다:
    • 공급 업체 이름을 기반으로 한 OmniAuth 구성에 대한 속성. 예: allowBypassTwoFactor, allowSingleSignOn, 및 syncProfileFromProvider.
    • 각 기존 사용자에 대한 추가 식별 정보로서의 연관성.
  • assertion_consumer_service_url이 제공자 이름과 일치해야 합니다.
  • strategy_class는 공급자 이름에서 추론할 수 없기 때문에 명시적으로 설정되어 있어야 합니다.

여러 SAML IdP를 설정하려면:

Linux 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb를 편집합니다:

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

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

    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. 첫 번째 SAML 제공자에 대한 Kubernetes Secret로 사용할 saml.yaml이라는 파일에 다음 내용을 넣습니다:

    name: 'saml' # 적어도 하나의 제공자는 'saml'로 지정되어야 함
    label: '제공자 1' # UI에서 두 개의 버튼과 제공자를 구분합니다
    args:
      name: 'saml' # 이것은 필수이며 제공자 이름과 일치해야 합니다
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback' # URL은 제공자 이름과 일치해야 합니다
      strategy_class: 'OmniAuth::Strategies::SAML' # 필수
      ... # 단일 제공자와 유사한 모든 필수 매개변수를 여기에 추가합니다
    
  2. 두 번째 SAML 제공자에 대한 Kubernetes Secret로 사용할 saml_2.yaml이라는 파일에 다음 내용을 넣습니다:

    name: 'saml_2'
    label: '제공자 2' # UI에서 두 개의 버튼과 제공자를 구분합니다
    args:
      name: 'saml_2' # 이것은 필수이며 제공자 이름과 일치해야 합니다
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL은 제공자 이름과 일치해야 합니다
      strategy_class: 'OmniAuth::Strategies::SAML' # 필수
      ... # 단일 제공자와 유사한 모든 필수 매개변수를 여기에 추가합니다
    
  3. 필요한 경우 동일한 단계를 따라 추가 SAML 제공자를 설정합니다.
  4. Kubernetes 시크릿을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml \
       --from-file=saml=saml.yaml \
       --from-file=saml_2=saml_2.yaml
    
  5. Helm 값들을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  6. 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']
    
  7. 파일을 저장하고 새 값을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml을 편집합니다:

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

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

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'saml_2']
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다:

    docker compose up -d
    
자체 컴파일 (소스)
  1. /home/git/gitlab/config/gitlab.yml을 편집합니다:

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

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

    production: &base
      omniauth:
        allow_single_sign_on: ["saml", "saml_2"]
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다:

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

신원 공급자 설정

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

GitLab은 오직 안내 목적으로 Okta 및 Google Workspace IdP를 설정하는 방법에 관한 다음 컨텐츠를 제공합니다. 이 중 어떤 IdP의 구성에 대한 질문이 있으면 해당 IdP의 고객 지원팀에 문의하십시오.

Okta 설정

  1. Okta 관리자 섹션에서 애플리케이션을 선택합니다.
  2. 앱 화면에서 앱 통합 생성을 선택한 후 다음 화면에서 SAML 2.0을 선택합니다.
  3. 선택 사항. GitLab Press에서 로고를 선택하고 추가합니다. 로고는 자르고 크기를 조정해야 합니다.
  4. SAML 일반 구성을 완료합니다. 다음을 입력합니다.
    • "단일 로그인 URL": 단일 로그인 URL을 사용합니다.
    • "대상 URI": 발급자를 사용합니다.
    • NameID.
    • Assertions.
  5. 피드백 섹션에서 고객이며 내부 사용용 앱을 생성하고 있다고 입력합니다.
  6. 새로운 앱 프로필 상단에서 SAML 2.0 구성 지침을 선택합니다.
  7. Identity Provider Single Sign-On URL을 확인합니다. 이 URL을 GitLab 구성 파일의 idp_sso_target_url로 사용합니다.
  8. Okta에서 로그아웃하기 전에 사용자 및 그룹(있는 경우)을 추가했는지 확인합니다.

Google Workspace 설정

전제 조건:

Google Workspace 설정 방법:

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

      일반 값 설명
    SAML 앱 이름 GitLab 다른 이름도 가능합니다.
    ACS URL https://<GITLAB_DOMAIN>/users/auth/saml/callback Assertion Consumer Service URL.
    GITLAB_DOMAIN gitlab.example.com GitLab 인스턴스 도메인.
    엔터티 ID https://gitlab.example.com 여러분의 SAML 애플리케이션에 고유한 값. 이것을 GitLab 구성의 발급자로 설정합니다.
    이름 ID 형식 이메일 필수 값입니다. name_identifier_format로도 알려져 있습니다.
    이름 ID 주 이메일 주소 여러분의 이메일 주소입니다. 해당 주소로 보낸 콘텐츠를 누군가가 받을 수 있는지 확인하세요.
    이름 first_name 이름. GitLab과의 커뮤니케이션을 위한 필수 값입니다.
    last_name 성. GitLab과의 커뮤니케이션을 위한 필수 값입니다.
  2. 다음과 같이 SAML 속성 매핑을 설정합니다.

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

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

Google Workspace SAML 애플리케이션을 구성할 때 다음 정보를 기록하세요.

  설명
SSO URL 다름 Google Identity Provider 세부 정보. GitLab의 idp_sso_target_url 설정에 대한 값입니다.
인증서 다운로드 가능 openssl x509 -in <your_certificate.crt> -noout -fingerprint -sha1을 실행하여 idp_cert_fingerprint 설정에 사용할 수 있는 SHA1 지문을 생성합니다.

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

기타 IdP 설정

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

SAML 구성에서 여러분의 IdP를 구성하는 데 질문이 있으면 해당 제공업체의 지원팀에 문의하십시오.

단언 구성

  • Microsoft Azure/Entra ID 속성 지원은 GitLab 16.7에서 소개되었습니다.

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

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

attribute_statements을 참조하여:

  • 사용자 지정 단언 구성 예제.
  • 사용자 지정 사용자 이름 속성을 구성하는 방법.

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

SAML 그룹 멤버십에 기반한 사용자 구성

다음을 할 수 있습니다:

  • 특정 그룹의 구성원으로 사용자를 요구합니다.
  • 그룹 멤버십에 기반하여 사용자를 외부, 관리자 또는 감사자 역할로 지정합니다.

GitLab은 각 SAML 로그인에서 이러한 그룹을 확인하고 필요에 따라 사용자 속성을 업데이트합니다. 이 기능을 사용하면 사용자를 GitLab에 자동으로 추가할 수 없습니다. 그룹에 대한 지원입니다.

이러한 그룹에 대한 지원은 다음에 달려 있습니다:

그룹 등급 GitLab Enterprise Edition (EE) 전용?
필수 Free, Premium, Ultimate
외부 Free, Premium, Ultimate 아니요
관리자 Free, Premium, Ultimate
감사자 Premium, Ultimate

전제 조건:

  • GitLab에서 그룹 정보를 찾을 위치를 알려주어야 합니다. 이를 위해 IdP 서버가 일반 SAML 응답과 함께 특정 AttributeStatement을 보내도록 해야 합니다. 예를 들어:

    <saml:AttributeStatement>
      <saml:Attribute Name="그룹">
        <saml:AttributeValue xsi:type="xs:string">개발자</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">프리랜서</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">관리자</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">감사자</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
    

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

외부 그룹

당신의 IdP는 SAML 응답에서 GitLab으로 그룹 정보를 전달합니다. 이 응답을 이용하려면 GitLab을 다음과 같이 구성하세요:

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

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

구성 예시:

Linux 패키지 (Omnibus)
  1. /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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. 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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
    
  2. Kubernetes Secret을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장한 후 새 값들을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. 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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                        idp_sso_target_url: 'https://login.example.com/idp',
                        issuer: 'https://gitlab.example.com',
                        name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                }
              }
            ]
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

    docker compose up -d
    
소스로 직접 컴파일한 경우
  1. /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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                       idp_sso_target_url: 'https://login.example.com/idp',
                       issuer: 'https://gitlab.example.com',
                       name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
               }
             }
    
  2. 파일을 저장한 후 GitLab을 재시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 실행 중인 시스템의 경우
    sudo service gitlab restart
    

관리자 그룹

당신의 IdP는 SAML 응답에서 그룹 정보를 GitLab으로 전달합니다. 이 응답을 사용하려면 GitLab을 다음과 같이 구성하여야합니다:

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

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

구성 예시:

리눅스 패키지 (Omnibus)
  1. /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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. 다음 내용을 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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
    
  2. Kubernetes 시크릿을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새로운 값을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. 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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

    docker compose up -d
    
직접 컴파일 (소스)
  1. /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: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
              }
            }
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

    # systemd를 실행 중인 시스템인 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 실행 중인 시스템인 경우
    sudo service gitlab restart
    

감사자 그룹

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

GitLab 11.4에서 소개되었습니다.

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

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

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

구성 예시:

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다.

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        groups_attribute: 'Groups',
        auditor_groups: ['Auditors'],
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다.

    sudo gitlab-ctl reconfigure
    
Helm chart (Kubernetes)
  1. saml.yaml이라는 파일에 다음 내용을 넣어 Kubernetes Secret로 사용합니다.

    name: 'saml'
    label: 'Our SAML Provider'
    groups_attribute: 'Groups'
    auditor_groups: ['Auditors']
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
    
  2. Kubernetes 시크릿을 생성합니다.

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다.

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새 값들을 적용합니다.

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다.

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 groups_attribute: 'Groups',
                 auditor_groups: ['Auditors'],
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다.

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다.

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              groups_attribute: 'Groups',
              auditor_groups: ['Auditors'],
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
              }
            }
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다.

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

SAML 그룹 동기화 자동 관리

SAML 그룹 멤버십을 자동으로 관리하는 정보는 SAML 그룹 동기화를 참조하십시오.

이중 인증 우회

세션당 SAML 인증 방법을 2단계 인증(2FA)으로 계산하도록 구성하려면 해당 방법을 upstream_two_factor_authn_contexts 목록에 등록하십시오.

  1. IdP가 AuthnContext을 반환하는지 확인하십시오. 예:

    <saml:AuthnStatement>
        <saml:AuthnContext>
            <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:MediumStrongCertificateProtectedTransport</saml:AuthnContextClassRef>
        </saml:AuthnContext>
    </saml:AuthnStatement>
    
  2. 설치 구성을 편집하여 SAML 인증 방법을 upstream_two_factor_authn_contexts 목록에 등록하십시오.

    Linux package (Omnibus)
    1. /etc/gitlab/gitlab.rb 파일을 편집하십시오.:

      gitlab_rails['omniauth_providers'] = [
        { name: 'saml',
          label: 'Our SAML Provider',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                  idp_sso_target_url: 'https://login.example.com/idp',
                  issuer: 'https://gitlab.example.com',
                  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                  upstream_two_factor_authn_contexts:
                    %w(
                      urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
                      urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
                      urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
                    ),
          }
        }
      ]
      
    2. 파일을 저장하고 GitLab을 다시 구성하십시오.:

      sudo gitlab-ctl reconfigure
      
    Helm chart (Kubernetes)
    1. saml.yaml이라는 파일에 다음 내용을 넣어 Kubernetes Secret로 사용하십시오:

      name: 'saml'
      label: 'Our SAML Provider'
      args:
        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
        idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
        idp_sso_target_url: 'https://login.example.com/idp'
        issuer: 'https://gitlab.example.com'
        name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
        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'
      
    2. Kubernetes Secret를 생성하십시오:

      kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
      
    3. Helm 값을 내보내십시오:

      helm get values gitlab > gitlab_values.yaml
      
    4. gitlab_values.yaml을 편집하십시오.:

      global:
        appConfig:
          omniauth:
            providers:
              - secret: gitlab-saml
      
    5. 파일을 저장하고 새 값들을 적용하십시오.:

      helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
      
    Docker
    1. docker-compose.yml 파일을 편집하십시오.:

      version: "3.6"
      services:
        gitlab:
          environment:
            GITLAB_OMNIBUS_CONFIG: |
              gitlab_rails['omniauth_providers'] = [
                 { name: 'saml',
                   label: 'Our SAML Provider',
                   args: {
                           assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                           idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                           idp_sso_target_url: 'https://login.example.com/idp',
                           issuer: 'https://gitlab.example.com',
                           name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                           upstream_two_factor_authn_contexts:
                             %w(
                               urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport
                               urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS
                               urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN
                             )
                   }
                 }
              ]
      
    2. 파일을 저장하고 GitLab을 다시 시작하십시오.:

      docker compose up -d
      
    자체 컴파일(소스)
    1. /home/git/gitlab/config/gitlab.yml 파일을 편집하십시오.:

      production: &base
        omniauth:
          providers:
            - { name: 'saml',
                label: 'Our SAML Provider',
                args: {
                        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                        idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                        idp_sso_target_url: 'https://login.example.com/idp',
                        issuer: 'https://gitlab.example.com',
                        name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                        upstream_two_factor_authn_contexts:
                          [
                            'urn:oasis:names:tc:SAML:2.0:ac:classes:CertificateProtectedTransport',
                            'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorOTPSMS',
                            'urn:oasis:names:tc:SAML:2.0:ac:classes:SecondFactorIGTOKEN'
                          ]
                }
              }
      
    2. 파일을 저장하고 GitLab을 다시 시작하십시오.:

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

응답 서명 유효성 검사

IdP는 SAML 응답에 서명을 해야 합니다. 이를 통해 주장이 조작되지 않도록 보장합니다.

특정 그룹 멤버십이 필요할 때 사용자 위장 및 권한 상승을 방지합니다.

idp_cert_fingerprint 사용

idp_cert_fingerprint를 사용하여 응답 서명 유효성을 구성합니다. 구성 예시:

Linux 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
        }
      }
    ]
    
  2. 파일을 저장한 후 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. saml.yaml이라는 파일에 다음 내용을 넣고 Kubernetes Secret로 사용합니다:

    name: 'saml'
    label: 'Our SAML Provider'
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
    
  2. Kubernetes 시크릿을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새 값들을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
                 }
               }
            ]
    
  2. 파일을 저장한 후 GitLab을 다시 시작합니다:

    docker compose up -d
    
자체 컴파일(소스)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
              }
            }
    
  2. 파일을 저장한 후 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

idp_cert 사용

만약 당신의 IdP가 idp_cert_fingerprint를 사용하여 구성하는 것을 지원하지 않는다면, 대신 idp_cert를 사용하여 GitLab을 직접 구성할 수 있습니다. 예시 구성:

리눅스 패키지 (Omnibus)
  1. /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'
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (쿠버네티스)
  1. 다음 내용을 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: |
        -----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'
    
  2. Kubernetes Secret을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새 값들을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
도커
  1. 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'
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

    docker compose up -d
    
Self-compiled (소스)
  1. /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'
              }
            }
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

    # systemd가 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init가 실행 중인 시스템의 경우
    sudo service gitlab restart
    

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

  • 키 유효성 오류
  • 다이제스트 불일치
  • 지문 불일치

이러한 오류를 해결하기 위한 자세한 정보는 SAML 문제 해결 가이드를 참조하세요.

SAML 설정 사용자 정의

SAML 서버로 사용자 리디렉션을 위한 설정

GiLab 구성에 auto_sign_in_with_provider 설정을 추가하여 SAML 서버로의 자동 리디렉션을 할 수 있습니다. 이렇게 하면 요소를 선택하기 전에 실제로 로그인할 수 있어 선택 과정을 제거할 수 있습니다.

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
    
  2. 파일을 저장한 후 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm chart (Kubernetes)
  1. Helm 값들을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  2. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          autoSignInWithProvider: 'saml'
    
  3. 파일을 저장한 후 새로운 값을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
    
  2. 파일을 저장한 후 GitLab을 재시작합니다:

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

    production: &base
      omniauth:
        auto_sign_in_with_provider: 'saml'
    
  2. 파일을 저장한 후 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 실행 중인 시스템의 경우
    sudo service gitlab restart
    

모든 로그인 시도는 SAML 서버로 리디렉트되므로 로컬 자격 증명을 사용하여 로그인할 수 없습니다. 적어도 하나의 SAML 사용자가 관리자 액세스 권한을 갖도록 확인하세요.

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

SAML 응답 속성 이름 매핑

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

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

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

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

이 설정을 사용하여 계정을 만드는 데 필요한 특정 속성을 어디서 찾을지 GitLab에 알리세요. 예를 들어, IdP가 사용자의 이메일 주소를 email 대신에 EmailAddress로 보내는 경우, 해당 구성으로 GitLab에 알릴 수 있습니다.

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                attribute_statements: { email: ['EmailAddress'] }
        }
      }
    ]
    
  2. 파일을 저장한 후 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm chart (Kubernetes)
  1. saml.yaml이라는 이름의 파일에 다음 내용을 넣어 Kubernetes Secret로 사용합니다:

    name: 'saml'
    label: 'Our SAML Provider'
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
      attribute_statements:
        email: ['EmailAddress']
    
  2. Kubernetes Secret을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장한 후 새로운 값을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                         attribute_statements: { email: ['EmailAddress'] }
                 }
               }
            ]
    
  2. 파일을 저장한 후 GitLab을 재시작합니다:

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                      attribute_statements: { email: ['EmailAddress'] }
              }
            }
    
  2. 파일을 저장한 후 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 실행 중인 시스템의 경우
    sudo service gitlab restart
    

사용자 이름 설정

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

username 또는 nicknameattribute_statements에서 구성하여 사용자의 원하는 사용자 이름을 포함하는 하나 이상의 속성을 지정합니다.

Linux 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                attribute_statements: { nickname: ['username'] }
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. 다음 내용을 saml.yaml이라는 파일에 넣어 쿠버네티스 시크릿으로 사용할 수 있도록합니다:

    name: 'saml'
    label: 'Our SAML Provider'
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
      attribute_statements:
        nickname: ['username']
    
  2. 쿠버네티스 시크릿을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새로운 값들을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 groups_attribute: 'Groups',
                 required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                         attribute_statements: { nickname: ['username'] }
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

    docker compose up -d
    
자체 컴파일 (소스)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              groups_attribute: 'Groups',
              required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                      attribute_statements: { nickname: ['username'] }
              }
            }
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

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

시계 드리프트 허용

IdP의 시계는 귀하의 시스템 시계보다 약간 앞서거나 후퇴할 수 있습니다. 작은 양의 시계 드리프트를 허용하려면 설정에서 allowed_clock_drift를 사용하십시오. 파라미터 값은 초 단위의 숫자와 분수로 입력해야 합니다. 주어진 값은 응답을 유효화하는 현재 시간에 추가됩니다.

Linux 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다.

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        groups_attribute: 'Groups',
        required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                allowed_clock_drift: 1  # 1초의 시계 드리프트 허용
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다.

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. saml.yaml이라는 파일에 다음 내용을 넣어 Kubernetes 비밀로 사용합니다.

    name: 'saml'
    label: 'Our SAML Provider'
    groups_attribute: 'Groups'
    required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
      allowed_clock_drift: 1  # 1초의 시계 드리프트 허용
    
  2. Kubernetes 비밀을 생성합니다.

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다.

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새 값들을 적용합니다.

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다.

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 groups_attribute: 'Groups',
                 required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                         allowed_clock_drift: 1  # 1초의 시계 드리프트 허용
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다.

    docker compose up -d
    
자체 컴파일(소스)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다.

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              groups_attribute: 'Groups',
              required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                      allowed_clock_drift: 1  # 1초의 시계 드리프트 허용
              }
            }
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다.

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

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

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

uid를 고유한 속성으로 설정하기 전에 SAML 사용자가 다음과 같은 속성을 구성했는지 확인하세요. 이렇게 하지 않으면 SAML 사용자가 이러한 속성을 변경할 수 있습니다.

  • NameID.
  • omniauth_auto_link_saml_user와 함께 사용될 때 이메일.

사용자가 이러한 속성을 변경할 수 있다면, 이들을 다른 인가된 사용자로서 로그인할 수 있습니다. 이러한 속성을 변경할 수 없도록 만드는 방법에 대한 정보는 SAML IdP 문서를 참조하십시오. 다음 예에서 SAML 응닑에서 uid 속성의 값이 uid_attribute로 설정됩니다.

Linux package (Omnibus)
  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                uid_attribute: 'uid'
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm chart (Kubernetes)
  1. saml.yaml이라는 파일에 다음 콘텐츠를 넣어 Kubernetes Secret로 사용합니다:

    name: 'saml'
    label: 'Our SAML Provider'
    groups_attribute: 'Groups'
    required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
      uid_attribute: 'uid'
    
  2. Kubernetes Secret을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml 파일을 편집합니다:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새 값들을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. docker-compose.yml 파일을 편집합니다:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 groups_attribute: 'Groups',
                 required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                         uid_attribute: 'uid'
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다:

    docker compose up -d
    
Self-compiled (source)
  1. /home/git/gitlab/config/gitlab.yml 파일을 편집합니다:

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              groups_attribute: 'Groups',
              required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                      uid_attribute: 'uid'
              }
            }
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init을 실행 중인 시스템의 경우
    sudo service gitlab restart
    

단언 암호화 (옵션)

GitLab은 SAML 2.0과 TLS 암호화 사용을 요구합니다. 때때로 GitLab은 추가 단언 암호화가 필요합니다. 예를 들어:

  • 로드 밸런서에서 TLS 암호화를 일찍 종료하는 경우
  • 로그에 나타나길 원치 않는 단언에 민감한 세부 정보가 포함된 경우

대부분의 조직에서는 이 계층에서 추가 암호화가 필요하지 않을 것입니다.

당신의 IdP(Identity Provider)는 GitLab의 공개 인증서로 단언을 암호화합니다. GitLab은 EncryptedAssertion를 자체 개인 키로 복호화합니다.

참고: 이 통합은 단언 암호화와 요청 서명을 위해 certificateprivate_key 설정을 사용합니다.

SAML 통합은 EncryptedAssertion를 지원합니다. 당신의 단언을 암호화하려면 GitLab 인스턴스의 개인 키와 공개 인증서를 SAML 설정에 정의하세요.

키와 인증서를 정의할 때 키 파일의 모든 개행 문자를 \n으로 대체하세요. 이렇게 하면 키 파일이 모든 개행 문자 없는 긴 문자열이 됩니다.

Linux 패키지 (Omnibus)
  1. /etc/gitlab/gitlab.rb를 편집하세요:

    gitlab_rails['omniauth_providers'] = [
      { name: 'saml',
        label: 'Our SAML Provider',
        groups_attribute: 'Groups',
        required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
        args: {
                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                idp_sso_target_url: 'https://login.example.com/idp',
                issuer: 'https://gitlab.example.com',
                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
        }
      }
    ]
    
  2. 파일을 저장하고 GitLab을 다시 구성하세요:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. 다음 내용을 담은 saml.yaml 파일을 만들어 Kubernetes Secret로 사용하세요:

    name: 'saml'
    label: 'Our SAML Provider'
    groups_attribute: 'Groups'
    required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors']
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
      certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----'
      private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
    
  2. Kubernetes Secret을 생성하세요:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값들을 내보내세요:

    helm get values gitlab > gitlab_values.yaml
    
  4. gitlab_values.yaml을 편집하세요:

    global:
      appConfig:
        omniauth:
          providers:
            - secret: gitlab-saml
    
  5. 파일을 저장하고 새로운 값을 적용하세요:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
도커
  1. docker-compose.yml을 편집하세요:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
               { name: 'saml',
                 label: 'Our SAML Provider',
                 groups_attribute: 'Groups',
                 required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
                 args: {
                         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                         idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                         idp_sso_target_url: 'https://login.example.com/idp',
                         issuer: 'https://gitlab.example.com',
                         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                         certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                         private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
                 }
               }
            ]
    
  2. 파일을 저장하고 GitLab을 재시작하세요:

    docker compose up -d
    
직접 컴파일 (소스)
  1. /home/git/gitlab/config/gitlab.yml을 편집하세요:

    production: &base
      omniauth:
        providers:
          - { name: 'saml',
              label: 'Our SAML Provider',
              groups_attribute: 'Groups',
              required_groups: ['Developers', 'Freelancers', 'Admins', 'Auditors'],
              args: {
                      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                      idp_sso_target_url: 'https://login.example.com/idp',
                      issuer: 'https://gitlab.example.com',
                      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                      certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                      private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
              }
            }
    
  2. 파일을 저장하고 GitLab을 재시작하세요:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

SAML 인증 요청에 서명하기(옵션)

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

서명하는 방법:

  1. GitLab 인스턴스에서 SAML을 사용할 개인 키 및 공개 인증서 쌍을 생성합니다.
  2. 구성에서 security 섹션에 서명 설정을 구성합니다. 예:

    Linux 패키지 (Omnibus)
    1. /etc/gitlab/gitlab.rb를 편집합니다.

      gitlab_rails['omniauth_providers'] = [
        { name: 'saml',
          label: 'Our SAML Provider',
          args: {
                  assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                  idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                  idp_sso_target_url: 'https://login.example.com/idp',
                  issuer: 'https://gitlab.example.com',
                  name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                  certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                  private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                  security: {
                    authn_requests_signed: true,
                    want_assertions_signed: true,
                    metadata_signed: false,
                    signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                    digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                  }
          }
        }
      ]
      
    2. 파일을 저장하고 GitLab을 다시 구성합니다.

      sudo gitlab-ctl reconfigure
      
    Helm 차트 (Kubernetes)
    1. 다음 내용을 saml.yaml이라는 파일에 넣어 Kubernetes Secret로 사용합니다.

      name: 'saml'
      label: 'Our SAML Provider'
      args:
        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
        idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
        idp_sso_target_url: 'https://login.example.com/idp'
        issuer: 'https://gitlab.example.com'
        name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
        certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----'
        private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----'
        security:
          authn_requests_signed: true
          want_assertions_signed: true
          metadata_signed: false
          signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256'
          digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256'
      
    2. Kubernetes 시크릿을 생성합니다.

      kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
      
    3. Helm 값을 내보냅니다.

      helm get values gitlab > gitlab_values.yaml
      
    4. gitlab_values.yaml을 편집합니다.

      global:
        appConfig:
          omniauth:
            providers:
              - secret: gitlab-saml
      
    5. 파일을 저장하고 새 값들을 적용합니다.

      helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
      
    Docker
    1. docker-compose.yml을 편집합니다.

      version: "3.6"
      services:
        gitlab:
          environment:
            GITLAB_OMNIBUS_CONFIG: |
              gitlab_rails['omniauth_providers'] = [
                 { name: 'saml',
                   label: 'Our SAML Provider',
                   args: {
                           assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                           idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                           idp_sso_target_url: 'https://login.example.com/idp',
                           issuer: 'https://gitlab.example.com',
                           name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                           certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                           private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                           security: {
                             authn_requests_signed: true,
                             want_assertions_signed: true,
                             metadata_signed: false,
                             signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                             digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                           }
                   }
                 }
              ]
      
    2. 파일을 저장하고 GitLab을 다시 시작합니다.

      docker compose up -d
      
    Self-compiled (소스)
    1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

      production: &base
        omniauth:
          providers:
            - { name: 'saml',
                label: 'Our SAML Provider',
                args: {
                        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
                        idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                        idp_sso_target_url: 'https://login.example.com/idp',
                        issuer: 'https://gitlab.example.com',
                        name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                        certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                        private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                        security: {
                          authn_requests_signed: true,
                          want_assertions_signed: true,
                          metadata_signed: false,
                          signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                          digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
                        }
                }
              }
      
    2. 파일을 저장하고 GitLab을 다시 시작합니다.

      # systemd를 실행 중인 시스템의 경우
      sudo systemctl restart gitlab.target
      
      # SysV init을 실행 중인 시스템의 경우
      sudo service gitlab restart
      

그럼 GitLab은:

  • 제공된 개인 키로 요청에 서명합니다.
  • 구성된 공개 x500 인증서를 IdP의 메타데이터에 포함하여 수신된 요청의 서명을 확인합니다.

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

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

참고: SAML 리디렉트 바인딩은 SAML POST 바인딩과 다릅니다. POST 바인딩에서는 중개자가 요청을 변조하지 못하게 서명이 필요합니다.

SAML을 통해 생성된 사용자의 암호 생성

GitLab은 SAML을 통해 생성된 사용자의 암호를 생성하고 설정합니다.

SSO 또는 SAML로 인증된 사용자는 HTTPS를 통한 Git 작업에 암호를 사용해서는 안 됩니다. 대신, 이러한 사용자는 다음을 할 수 있습니다:

기존 사용자를 위한 SAML 식별 정보 링크

관리자는 GitLab을 구성하여 자동으로 기존의 GitLab 사용자와 SAML 사용자를 연결할 수 있습니다. 자세한 정보는 GitLab에서 SAML 지원 구성을 참조하십시오.

사용자는 직접 SAML 식별 정보를 기존의 GitLab 계정에 링크할 수 있습니다. 자세한 내용은 기존 사용자를 위한 OmniAuth 활성화를 참조하십시오.

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

Tier: 프리미엄, 얼티밋 Offering: Self-managed, GitLab Dedicated

자체 관리 인스턴스에서 여러 SAML IdP를 통해 액세스를 허용해야 하는 경우 그룹 SAML SSO를 사용합니다.

그룹 SAML SSO를 구성하려면:

Linux 패키지 (Omnibus)
  1. GitLab이 HTTPS로 구성되었는지 확인합니다.
  2. /etc/gitlab/gitlab.rb를 편집하여 OmniAuth 및 group_saml 공급자를 활성화합니다:

    gitlab_rails['omniauth_enabled'] = true
    gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]
    
  3. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
Helm 차트 (Kubernetes)
  1. GitLab이 HTTPS로 구성되었는지 확인합니다.
  2. Kubernetes Secret로 사용될 group_saml.yaml이라는 파일에 다음 내용을 넣습니다:

    name: 'group_saml'
    
  3. Kubernetes Secret을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-group-saml --from-file=provider=group_saml.yaml
    
  4. Helm 값(Values)을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  5. gitlab_values.yaml을 편집하여 OmniAuth와 group_saml 공급자를 활성화합니다:

    global:
      appConfig:
        omniauth:
          enabled: true
          providers:
            - secret: gitlab-group-saml
    
  6. 파일을 저장하고 새 값(Values)을 적용합니다:

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. GitLab이 HTTPS로 구성되었는지 확인합니다.
  2. 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' }]
    
  3. 파일을 저장하고 GitLab을 다시 시작합니다:

    docker compose up -d
    
자체 컴파일 (소스)
  1. GitLab이 HTTPS로 구성되었는지 확인합니다.
  2. /home/git/gitlab/config/gitlab.yml를 편집하여 OmniAuth와 group_saml 공급자를 활성화합니다:

    production: &base
      omniauth:
        enabled: true
        providers:
          - { name: 'group_saml' }
    
  3. 파일을 저장하고 GitLab을 다시 시작합니다:

    # systemd를 실행 중인 시스템의 경우
    sudo systemctl restart gitlab.target
    
    # SysV init를 실행 중인 시스템의 경우
    sudo service gitlab restart
    

자체 호스팅된 인스턴스의 그룹 SAML은 인스턴스 전체 SAML에 비해 제약이 있습니다. 다음을 활용하려면 인스턴스 전체 SAML을 권장합니다:

추가 구성 사항: IdP에서 SAML 앱을 위한

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

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

예제 구성에 대한 자세한 내용은 특정 제공자에 대한 참고 사항을 참조하세요.

용어 사전

용어 설명
식별 제공자 (IdP) Okta 또는 OneLogin과 같은 사용자 ID를 관리하는 서비스입니다.
서비스 제공자 (SP) Okta와 같은 SAML IdP로부터 주장을 소비하여 사용자를 인증하는 서비스입니다. GitLab을 SAML 2.0 SP로 구성할 수 있습니다.
주장 사용자의 신원에 관한 정보로, 이름이나 역할 등이 있습니다. 주장 또는 속성으로도 알려져 있습니다.
단일 로그인 (SSO) 인증 계획의 이름입니다.
주장 사용자 서비스 URL 사용자가 IdP로 성공적으로 인증한 후 GitLab으로 리디렉션되는 콜백입니다.
발행자 GitLab이 IdP에 자신을 식별하는 방식으로 “신뢰 당사 식별자”로도 알려져 있습니다.
인증서 지문 SAML을 통한 통신이 안전한지 확인하기 위해 서버가 올바른 인증서로 통신을 서명하는지 확인합니다. 인증서 썸프린트로도 알려져 있습니다.

문제 해결

SAML 문제 해결 가이드를 참조하십시오.