자체 호스팅 GitLab 인스턴스용 SAML SSO

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

이 페이지에서는 자체 호스팅 GitLab 인스턴스에 대한 인스턴스 전체 SAML 단일 로그인(SSO) 설정 방법에 대해 설명합니다.

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

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

다음 정보에 대한 자세한 내용은 아래를 참조하세요.

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

GitLab에서 SAML 지원 구성

Linux 패키지 (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
    

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

    또는 사용자는 기존 GitLab 계정에 대해 SAML 식별을 매뉴얼으로 링크할 수 있습니다. 사용자는 이를 통해 기존 사용자에 대한 OmniAuth 활성화를 할 수 있습니다.

  5. SAML 사용자가 이러한 속성을 변경할 수 없도록 다음 속성을 구성하세요.

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 이메일.

    사용자가 이러한 속성을 변경할 수 있으면 다른 권한 부여 된 사용자로 로그인 할 수 있습니다. 이러한 속성을 변경할 수 없게하려면 SAML IdP 설명서를 참조하십시오.

  6. /etc/gitlab/gitlab.rb을 편집하고 공급자 구성을 추가하세요.

    gitlab_rails['omniauth_providers'] = [
      {
        name: "saml",
        label: "공급자 이름", 
        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)
  1. GitLab이 HTTPS로 구성되었는지 확인하세요.
  2. 일반 설정을 구성하여 saml을 단일 로그인 제공자로 추가하세요. 이렇게 하면 기존 GitLab 계정이없는 사용자를위한 즉시 계정 프로비저닝을 가능하게 합니다.
  3. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml
    
  4. 사용자가 계정을 매뉴얼으로 만들지 않아도 SAML을 사용하여 가입할 수 있도록하려면 gitlab_values.yaml을 편집하세요:

    global:
      appConfig:
        omniauth:
          enabled: true
          allowSingleSignOn: ['saml']
          blockAutoCreatedUsers: false
    
  5. 선택 사항. SAML 사용자가 기존 GitLab 사용자와 이메일 주소가 일치하는 경우 다음 설정을 gitlab_values.yaml에 추가하여 SAML 사용자를 자동으로 연결할 수 있습니다.

    global:
      appConfig:
        omniauth:
          autoLinkSamlUser: true
    

    또는 사용자는 기존 GitLab 계정에 대해 SAML 식별을 매뉴얼으로 링크할 수 있습니다. 사용자는 이를 통해 기존 사용자에 대한 OmniAuth 활성화를 할 수 있습니다.

  6. 사용자가 계정을 변경할 수 없도록 다음 속성을 구성하세요:

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 이메일.

    사용자가 이러한 속성을 변경할 수 있으면 다른 권한 부여 된 사용자로 로그인 할 수 있습니다. 이러한 속성을 변경할 수 없게하려면 SAML IdP 설명서를 참조하십시오.

  7. saml.yaml이라는 파일에 다음 내용을 넣어 Kubernetes Secret로 사용하세요:

    name: 'saml'
    label: '공급자 이름' # 선택적인 로그인 버튼의 레이블. 기본값은 "Saml"입니다.
    args:
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback'
      idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8'
      idp_sso_target_url: 'https://login.example.com/idp'
      issuer: 'https://gitlab.example.com'
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
    

    여기서:

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

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  9. gitlab_values.yaml을 편집하고 공급자 구성을 추가하세요:

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    
Docker
  1. GitLab이 HTTPS로 구성되었는지 확인하세요.
  2. 일반 설정을 구성하여 saml을 단일 로그인 제공자로 추가하세요. 이렇게 하면 기존 GitLab 계정이없는 사용자를위한 즉시 계정 프로비저닝을 가능하게 합니다.
  3. 사용자가 계정을 매뉴얼으로 만들지 않아도 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
    
  4. 선택 사항. SAML 사용자가 기존 GitLab 사용자와 이메일 주소가 일치하는 경우 docker-compose.yml에 다음 설정을 추가하여 SAML 사용자를 자동으로 연결할 수 있습니다.

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_auto_link_saml_user'] = true
    

    또는 사용자는 기존 GitLab 계정에 대해 SAML 식별을 매뉴얼으로 링크할 수 있습니다. 사용자는 이를 통해 기존 사용자에 대한 OmniAuth 활성화를 할 수 있습니다.

  5. 사용자가 계정을 변경할 수 없도록 다음 속성을 구성하세요:

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 이메일.

    사용자가 이러한 속성을 변경할 수 있으면 다른 권한 부여 된 사용자로 로그인 할 수 있습니다. 이러한 속성을 변경할 수 없게하려면 SAML IdP 설명서를 참조하십시오.

  6. docker-compose.yml을 편집하고 공급자 구성을 추가하세요:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
              {
                name: "saml",
                label: "공급자 이름", 
                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을 다시 시작하세요:

    docker compose up -d
    
자체 컴파일 (소스)
  1. GitLab이 HTTPS로 구성되었는지 확인하세요.
  2. 일반 설정을 구성하여 saml을 단일 로그인 제공자로 추가하세요. 이렇게 하면 기존 GitLab 계정이없는 사용자를위한 즉시 계정 프로비저닝을 가능하게 합니다.
  3. 사용자가 계정을 매뉴얼으로 만들지 않아도 SAML을 사용하여 가입할 수 있도록하려면 /home/git/gitlab/config/gitlab.yml을 편집하세요:

    production: &base
      omniauth:
        enabled: true
        allow_single_sign_on: ["saml"]
        block_auto_created_users: false
    
  4. 선택 사항. SAML 사용자가 기존 GitLab 사용자와 이메일 주소가 일치하는 경우 다음 설정을 /home/git/gitlab/config/gitlab.yml에 추가하여 SAML 사용자를 자동으로 연결할 수 있습니다.

    production: &base
      omniauth:
        auto_link_saml_user: true
    

    또는 사용자는 기존 GitLab 계정에 대해 SAML 식별을 매뉴얼으로 링크할 수 있습니다. 사용자는 이를 통해 기존 사용자에 대한 OmniAuth 활성화를 할 수 있습니다.

  5. 사용자가 계정을 변경할 수 없도록 다음 속성을 구성하세요:

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 이메일.

    사용자가 이러한 속성을 변경할 수 있으면 다른 권한 부여 된 사용자로 로그인 할 수 있습니다. 이러한 속성을 변경할 수 없게하려면 SAML IdP 설명서를 참조하십시오.

  6. /home/git/gitlab/config/gitlab.yml을 편집하고 공급자 구성을 추가하세요:

    ```yaml omniauth: providers: - { name: ‘saml’, label: ‘공급자 이름’, args: { assertion_consumer_service_url: ‘https://gitlab.example.com/users/auth/saml/callback’,

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을 사용합니다. 다른 사용 가능한 클레임에 대한 자세한 정보는 assertion 구성을 참조하세요.

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

IdP에서 SAML 구성

IdP에서 SAML 응용프로그램을 구성하려면 다음 정보가 필요합니다:

구성 예시는 아이덴티티 제공자 설정을 참조하세요.

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

다중 SAML IdP를 사용하도록 GitLab 구성

GitLab을 다중 SAML IdP를 사용하도록 구성할 수 있습니다. 다음 조건을 충족해야 합니다:

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

다중 SAML IdP를 설정하려면:

::Tabs

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

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

    사용자가 두 제공자 중 하나에서 매뉴얼으로 계정을 만들 필요 없이 SAML을 사용하여 가입할 수 있도록 하려면 다음 값을 구성에 추가하세요:

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

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

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

    name: 'saml_2'
    label: 'Provider 2' # UI에서 두 개의 버튼과 프로바이더를 구분합니다
    args:
      name: 'saml_2' # 이것은 필수이며 프로바이더 이름과 일치해야 합니다.
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback' # URL은 프로바이더의 이름과 일치해야 합니다
      strategy_class: 'OmniAuth::Strategies::SAML' # 필수사항
      ... # 단일 제공자와 유사한 필수 매개변수를 여기에 추가합니다.
    
  3. 동일한 단계를 따라 추가 SAML 제공자를 설정하세요.
  4. Kubernetes Secrets를 만듭니다:

    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: 'Provider 1' # UI에서 두 개의 버튼과 프로바이더를 구분합니다
                args: {
                        name: 'saml', # 이것은 필수이며 프로바이더 이름과 일치해야 합니다.
                        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', # URL은 프로바이더의 이름과 일치해야 합니다
                        strategy_class: 'OmniAuth::Strategies::SAML',
                        ... # 단일 제공자와 유사한 필수 매개변수를 여기에 추가합니다.
                      },
              },
              {
                name: 'saml_2', # 다음 이름 구성 매개변수와 일치해야 함
                label: 'Provider 2' # UI에서 두 개의 버튼과 프로바이더를 구분합니다
                args: {
                        name: 'saml_2', # 이것은 필수이며 프로바이더 이름과 일치해야 합니다.
                        assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL은 프로바이더의 이름과 일치해야 합니다
                        strategy_class: 'OmniAuth::Strategies::SAML',
                        ... # 단일 제공자와 유사한 필수 매개변수를 여기에 추가합니다.
                      },
              }
            ]
    

    사용자가 두 제공자 중 하나에서 매뉴얼으로 계정을 만들 필요 없이 SAML을 사용하여 가입할 수 있도록 하려면 다음 값을 구성에 추가하세요:

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

    docker compose up -d
    
직접 컴파일된 사이트 (소스)
  1. /home/git/gitlab/config/gitlab.yml을 편집합니다:

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

    사용자가 두 제공자 중 하나에서 매뉴얼으로 계정을 만들 필요 없이 SAML을 사용하여 가입할 수 있도록 하려면 다음 값을 구성에 추가하세요:

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

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

신원 공급자 설정

GitLab의 SAML 지원은 다양한 IdP를 통해 GitLab에 로그인할 수 있음을 의미합니다.

GitLab은 Okta 및 Google Workspace IdP를 설정하는 방법에 대한 내용을 제공합니다. 이 설정은 참고용이며 이러한 IdP 중 하나를 구성하는 데 대한 궁금한 사항이 있으면 해당 공급자 지원팀에 문의하십시오.

Okta 설정

  1. Okta 관리자 섹션에서 Applications(애플리케이션)을 선택합니다.
  2. 앱 화면에서 Create App Integration(앱 통합 생성)을 선택한 다음, 다음 화면에서 SAML 2.0을 선택합니다.
  3. (옵션) GitLab Press에서 로고를 선택하고 추가합니다. 로고를 잘라내고 크기를 조정해야 합니다.
  4. SAML 일반 구성을 완료합니다. 다음을 입력합니다:
    • “단일 로그인 URL”: 단일 로그인 URL을 사용합니다.
    • “Audience URI”: 발급자를 사용합니다.
    • NameID.
    • Assertions.
  5. 피드백 섹션에서 내부 사용을 위한 앱을 생성 중임을 입력합니다.
  6. 새 앱 프로필 상단에서 SAML 2.0 구성 지침을 선택합니다.
  7. IdP 단일 로그인 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 구성의 issuer로 설정합니다.
    이름 ID 형식 EMAIL 필수 값입니다. 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를 구성하는 데 문제가 있으면 해당 공급자의 지원팀에 문의하십시오.

Assertions 구성

note
이러한 속성은 대소문자를 구분합니다.
필드 지원되는 기본 키들
이메일 (필수) 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)를 설치했는지 여부.
  • GitLab에서 SAML 지원을 구성하는 SAML 제공자의 이름. 그룹 멤버십은 ‘saml’이라는 단일 SAML 제공자에서만 지원됩니다.
그룹 계층 GitLab Enterprise Edition (EE) 전용?
필수 Free, Premium, Ultimate
외부 Free, Premium, Ultimate 아니요
관리자 Free, Premium, Ultimate
감사자 Premium, Ultimate

전제 조건:

  • GitLab에 그룹 정보를 어디서 찾을지 알려야 합니다. 이를 위해 IdP 서버가 일반 SAML 응답과 함께 특정한 AttributeStatement을 보냄을 확인하십시오. 예:
<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Freelancers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Admins</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Auditors</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

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

필수 그룹

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

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

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

만약 required_groups를 설정하지 않거나 빈 채로 둔다면, 적절한 인증을 받은 누구라도 서비스를 사용할 수 있습니다.

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'
        }
      }
    ]
    
  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'
    
  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'
                 }
               }
            ]
    
  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'
              }
            }
    
  2. 파일을 저장하고 GitLab을 재시작합니다:

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

외부 그룹

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

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

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

예시 구성:

Linux package (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 chart (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
    
Self-compiled (source)
  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 설정을 사용하여 사용자에게 관리자 액세스를 부여하는 그룹을 구성합니다.

예시 구성:

Linux package (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 chart (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 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',
                 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
    
Self-compiled (source)
  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 패키지 (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 차트 (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 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',
                 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 (소스)
  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 그룹 동기화 자동 관리

GitLab 그룹 멤버십을 자동으로 관리하는 정보는 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. 설치 구성을 편집하여 upstream_two_factor_authn_contexts 디렉터리에 SAML 인증 방법을 등록합니다.

    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'
                  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 차트 (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
      
    도커
    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
      
    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'
                        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 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'
                 }
               }
            ]
    
  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'
              }
            }
    
  2. 파일을 저장하고 GitLab을 다시 시작합니다:

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

idp_cert 사용

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

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: '-----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 차트 (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: |
        -----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
    
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: '-----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 (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: '-----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 서버로 사용자 리디렉션하여 인증

GitLab 구성에 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 사용자가 관리자 액세스 권한을 갖도록 하십시오.

note
자동 로그인 설정을 우회하려면 로그인 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 해시의 항목으로 매핑할 수 있습니다.

note
이 설정은 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이라는 이름의 파일에 다음 내용을 입력하여 쿠버네티스 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. 쿠버네티스 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 사용자 이름을 생성합니다.

attribute_statements에서 username 또는 nickname을 구성하여 사용자의 원하는 사용자 이름을 포함한 하나 이상의 속성을 지정하세요.

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: { nickname: ['username'] }
        }
      }
    ]
    
  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:
        nickname: ['username']
    
  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',
                         attribute_statements: { nickname: ['username'] }
                 }
               }
            ]
    
  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',
                      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 package (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 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'
      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
    
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',
                      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 사용자가 이러한 속성을 변경할 수 없도록 다음 속성을 구성했는지 확인하십시오:

  • NameID.
  • omniauth_auto_link_saml_user와 함께 사용될 때 Email.

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

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',
                uid_attribute: 'uid'
        }
      }
    ]
    
  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'
      uid_attribute: 'uid'
    
  2. Kubernetes Secret을 생성합니다:

    kubectl create secret generic -n <namespace> gitlab-saml --from-file=provider=saml.yaml
    
  3. Helm 값(values) 내보내기:

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

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

    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 암호화를 빠르게 종료합니다.
  • 로그에 나타나기를 원치 않는 주장(assertion)에 민감한 세부 정보를 포함합니다.

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

귀하의 IdP는 GitLab의 공개 인증서로 주장을 암호화합니다. GitLab은 EncryptedAssertion을 자신의 개인 키로 해독합니다.

note
이 통합은 주장 암호화와 요청 서명을 위한 certificateprivate_key 설정을 사용합니다.

SAML 통합은 EncryptedAssertion을 지원합니다. 주장을 암호화하려면 SAML 설정에서 GitLab 인스턴스의 개인 키와 공개 인증서를 정의하십시오.

키와 인증서를 정의할 때 키 파일의 모든 줄 바꿈을 \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 값(values) 내보내기:

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

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

    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',
                         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
    
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',
                      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 섹션에 있습니다. 예:

    리눅스 패키지 (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,  # AuthNRequest에 서명을 활성화합니다
                    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  # AuthNRequest에 서명을 활성화합니다
          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 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_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
                           idp_sso_target_url: 'https://login.example.com/idp',
                           issuer: 'https://gitlab.example.com',
                           name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
                           certificate: '-----BEGIN CERTIFICATE-----\n<redacted>\n-----END CERTIFICATE-----',
                           private_key: '-----BEGIN PRIVATE KEY-----\n<redacted>\n-----END PRIVATE KEY-----',
                           security: {
                             authn_requests_signed: true,  # AuthNRequest에 서명을 활성화합니다
                             want_assertions_signed: true,  # 서명된 어설션의 요구사항을 활성화합니다
                             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
      
    직접 컴파일 (소스)
    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,  # AuthNRequest에 서명을 활성화합니다
                          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 인증의 클라이언트 측을 구현하는 데 사용됩니다.

note
SAML 리디렉트 바인딩은 SAML POST 바인딩과 다릅니다. POST 바인딩에서는 요청을 조작하는 중개자를 방지하기 위해 서명이 필요합니다.

SAML을 통해 생성된 사용자의 비밀번호 생성

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

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

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

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

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

Self-managed 인스턴스에서 그룹 SAML SSO 구성

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

Self-managed 인스턴스에서 여러 SAML IdP를 통해 액세스를 허용해야 하는 경우 그룹 SAML SSO를 사용하십시오.

그룹 SAML SSO를 구성하려면:

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

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

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

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

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

    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. 파일을 저장하고 새 값들을 적용합니다:

    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. group_saml 공급자를 활성화하도록 /home/git/gitlab/config/gitlab.yml을 편집합니다:

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

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

Self-managed 인스턴스에서 그룹 SAML은 권장되는 인스턴스 전체 SAML에 비해 제한되어 있습니다. 다음을 활용하려면 인스턴스 전체 SAML을 사용하십시오:

IdP에서 SAML 앱에 대한 추가 구성

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

필드 참고
SAML 프로필 웹 브라우저 SSO 프로필 GitLab은 브라우저를 통해 사용자를 로그인시키기 위해 SAML을 사용합니다. IdP에 직접적으로 요청을 보내지 않습니다.
SAML 요청 바인딩 HTTP 리디렉션 GitLab(SP)은 사용자를 IdP로 SAMLRequest를 Base64로 인코딩한 HTTP 매개변수와 함께 리디렉션합니다.
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 주장 암호화 선택 사항 IdP, 사용자의 브라우저, GitLab 간에 TLS를 사용합니다.
SAML 주장 서명 선택 사항 SAML 주장의 무결성을 검증합니다. 활성화되어 있으면 응답 전체에 서명합니다.
SAML 요청 서명 확인 선택 사항 SAML 응답에서 서명을 확인합니다.
기본 RelayState 선택 사항 사용자가 IdP에서 SAML로 로그인한 후에 기본 URL의 하위 경로를 지정합니다.
NameID 형식 지속적 NameID 형식 세부 정보를 참조하세요.
추가 URL 선택 사항 일부 공급자에서 발행자, 식별자 또는 기타 필드에 발급자, 식별자 또는 주장 소비자 서비스 URL을 포함할 수 있습니다.

구체적인 구성 예는 특정 공급자에 대한 노트를 참조하십시오.

용어집

용어 설명
Identity provider (IdP) 사용자 ID(예: Okta 또는 OneLogin)를 관리하는 서비스입니다.
Service provider (SP) SAML IdP(예: Okta)에서 주장을 사용하여 사용자를 인증하는 서비스입니다. GitLab을 SAML 2.0 SP로 구성할 수 있습니다.
Assertion 사용자 ID(예: 이름 또는 역할)에 대한 정보 조각입니다. 주장 또는 속성으로도 알려져 있습니다.
Single Sign-On (SSO) 인증 방식의 이름입니다.
Assertion consumer service URL 사용자가 IdP로 성공적으로 인증한 후 GitLab으로 리디렉션되는 콜백입니다.
Issuer GitLab이 IdP에 자신을 식별하는 방법입니다. “의존하는 당사 신뢰 식별자”로도 알려져 있습니다.
Certificate fingerprint SAML 통신이 올바른 인증서로 통신을 서명하는 것을 확인하여 안전한지를 확인하는 지문입니다. 인증서 썸프린트로도 알려져 있습니다.

문제 해결

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