자체 호스트된 GitLab 인스턴스를 위한 SAML SSO

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

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

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

GitLab.com에서 SAML을 설정하려면 SAML SSO for GitLab.com 그룹을 참조하십시오.

자세한 정보:

  • 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
    

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

    또는 사용자는 기존 GitLab 계정에 매뉴얼으로 SAML 신원을 링크하여 기존 사용자를 위한 OmniAuth 활성화를 할 수 있습니다.

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

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 Email.

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

  6. /etc/gitlab/gitlab.rb을 편집하고 제공자 구성을 추가하십시오:

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

    상기에서:

    • assertion_consumer_service_url: GitLab HTTPS 엔드포인트 (GitLab 설치의 HTTPS URL에 /users/auth/saml/callback을 추가하십시오).
    • idp_cert_fingerprint: 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에 다음 설정을 추가하십시오:

    global:
      appConfig:
        omniauth:
          autoLinkSamlUser: true
    

    또는 사용자는 기존 GitLab 계정에 매뉴얼으로 SAML 신원을 링크하여 기존 사용자를 위한 OmniAuth 활성화를 할 수 있습니다.

  6. SAML 사용자가 이러한 속성을 변경할 수 없도록 다음 속성을 구성하십시오:

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 Email.

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

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

    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 값.
  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
도커
  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에 다음 설정을 추가하십시오:

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

    또는 사용자는 기존 GitLab 계정에 매뉴얼으로 SAML 신원을 링크하여 기존 사용자를 위한 OmniAuth 활성화를 할 수 있습니다.

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

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 Email.

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

  6. docker-compose.yml을 편집하고 제공자 구성을 추가하십시오:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_providers'] = [
              {
                name: "saml",
                label: "제공자 이름", # 선택적으로 로그인 버튼에 대한 라벨, 기본값은 "Saml"
                args: {
                  assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
                  idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
                  idp_sso_target_url: "https://login.example.com/idp",
                  issuer: "https://gitlab.example.com",
                  name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
                }
              }
            ]
    
  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에 다음 설정을 추가하십시오:

    production: &base
      omniauth:
        auto_link_saml_user: true
    

    또는 사용자는 기존 GitLab 계정에 매뉴얼으로 SAML 신원을 링크하여 기존 사용자를 위한 OmniAuth 활성화를 할 수 있습니다.

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

    • NameID.
    • omniauth_auto_link_saml_user와 함께 사용되는 Email.

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

  6. /home/git/gitlab/config/gitlab.yml을 편집하고 제공자 구성을 추가하십시오:

    ```yaml omniauth: providers: - { name: ‘saml’, label: ‘제공자 이름’, # 선택적으로 로그인 버튼에 대한 라벨, 기본값은 “Saml” args: { assertion_consumer_service_url: ‘https://gitlab.example.com/users/auth/saml/callback’, idp_cert_fingerprint: ‘43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8’, idp_sso_target_url: ‘https://login.example.com/idp’, issuer: ‘https://gitlab.example.com’, name_identifier_format: ‘urn:oasis:names:tc:SAML:2.0:nameid-format:persistent’

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를 설정하려면 다음을 수행합니다:

::Tabs

Linux package (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 chart (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
    
Self-compiled (source)
  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
    

Identity Provider 설정

GitLab의 SAML 지원을 통해 넓은 범위의 IdP(Identity Provider)를 통해 GitLab에 로그인할 수 있습니다.

GitLab은 Okta 및 Google Workspace IdP를 설정하는 콘텐츠를 안내하기 위해 다음과 같은 내용을 제공합니다. 이 두 IdP 중 하나를 구성하는 데 관한 질문이 있으면 제공업체 지원팀에 문의하십시오.

Okta 설정

  1. Okta 관리자 섹션에서 Applications를 선택합니다.
  2. 앱 화면에서 앱 통합 생성을 선택한 다음 다음 화면에서 SAML 2.0을 선택합니다.
  3. Optional. GitLab Press에서 로고를 선택하고 추가합니다. 로고를 자르고 크기를 조정해야 합니다.
  4. SAML 일반 구성을 완료합니다. 다음을 입력하세요:
    • "단일 회원가입 URL": 단일 로그인 서비스 URL을 사용합니다.
    • "Audience URI": 발급자를 사용합니다.
    • NameID.
    • Assertions.
  5. 피드백 섹션에서 “Customer”임을 입력하고 내부 사용을 위한 앱을 생성 중임을 입력합니다.
  6. 새 앱 프로필의 맨 위에서 SAML 2.0 구성 지침을 선택합니다.
  7. 아이덴티티 제공자 단일 로그인 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 형식 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 아이덴티티 제공자 세부 정보. 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 구성

  • GitLab 16.7에서 도입된 Microsoft Azure/Entra ID 속성 지원.
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)만 해당?
필수 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을 구성하여 다음을 식별해야 합니다.

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

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

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
    
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'
                 }
               }
            ]
    
  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',
              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 패키지 (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
    
Self-compiled (소스)
  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을 구성합니다.

구성 예시:

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

귀하의 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 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',
                 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 그룹 동기화 관리하기

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

이중 인증 우회

세션당 SAML 인증 방법을 이중 인증으로 계산하도록 구성하려면 해당 방법을 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
      
    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 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
    
직접 컴파일(소스)
  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을 직접 구성할 수 있습니다. 구성 예시:

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: '-----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 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: |
        -----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 서버로 리디렉션

auto_sign_in_with_provider 설정을 GitLab 구성에 추가하여 인증을 위해 자동으로 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라는 속성이 포함되어 있으면 ` { email: [‘EmailAddress’] }로 속성을 info 해시의 해당 키에 매핑합니다. URI 이름을 가진 속성도 지원됩니다. 예를 들어, { email: [‘http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress’] }`와 같이 말입니다.

이 설정을 사용하여 계정을 생성하는 데 필요한 특정 속성의 위치를 GitLab에 알려주기 위해 사용합니다. 예를 들어, IdP가 사용자의 이메일 주소를 EmailAdres로 보내는 경우, email 대신 설정하여 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 사용자 이름을 생성합니다.

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 차트 (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 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',
                         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의 사용자 이름으로 설정됩니다.

클럭 드리프트, Clock Drift 허용

IdP의 시계는 약간 시스템 시계보다 앞서 들어갈 수 있습니다. 작은 양의 클럭 드리프트, Clock Drift를 허용하려면, 설정에서 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초의 클럭 드리프트, Clock Drift에 대해
        }
      }
    ]
    
  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'
      allowed_clock_drift: 1  # 1초의 클럭 드리프트, Clock Drift에 대해
    
  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',
                         allowed_clock_drift: 1  # 1초의 클럭 드리프트, Clock Drift에 대해
                 }
               }
            ]
    
  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초의 클럭 드리프트, Clock Drift에 대해
              }
            }
    
  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 값을 내보냅니다:

    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 (소스)
  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는 GitLab의 공개 인증서로 주장을 암호화하고, GitLab은 EncryptedAssertion를 개인 키로 복호화합니다.

note
이 통합은 주장 암호화와 요청 서명을 위해 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
    
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 (소스)
  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 설정을 구성합니다. 구성의 security 섹션에 아래와 같이 설정하세요. 예:

    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',
                  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,  # Metadata에 서명을 활성화합니다
                    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 chart (Kubernetes)
    1. 사용할 Kubernetes Secret로 사용될 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  # Metadata에 서명을 활성화합니다
          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
      
    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,  # AuthNRequest에 서명을 활성화합니다
                             want_assertions_signed: true,  # 서명된 어설션 요구를 활성화합니다
                             metadata_signed: false,  # Metadata에 서명을 활성화합니다
                             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 (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',
                        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,  # Metadata에 서명을 활성화합니다
                          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 documentation을 참조하십시오.

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

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. OmniAuth 및 group_saml 프로바이더를 활성화하기 위해 docker-compose.yml 파일을 편집합니다:

    version: "3.6"
    services:
      gitlab:
        environment:
          GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['omniauth_enabled'] = true
            gitlab_rails['omniauth_providers'] = [{ name: 'group_saml' }]
    
  3. 파일을 저장하고 GitLab을 다시 시작합니다:

    docker compose up -d
    
직접 컴파일 (소스)
  1. GitLab이 HTTPS로 구성되었는지 확인하십시오.
  2. OmniAuth와 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 앱을 위한 추가 구성

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

필드 참고
SAML 프로필 Web 브라우저 SSO 프로필 GitLab은 사용자를 브라우저를 통해 로그인합니다. IdP에 직접 요청을 보내지 않습니다.
SAML 요청 바인딩 HTTP 리디렉트 GitLab(SP)은 사용자를 IdP로 SAMLRequest의 base64로 인코딩된 HTTP 매개변수를 사용하여 리디렉트합니다.
SAML 응답 바인딩 HTTP POST IdP가 사용자의 브라우저가 GitLab으로 제출하는 SAMLResponse를 포함한 SAML 토큰을 어떻게 보내는지 지정합니다.
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을 통해 성공적으로 로그인한 후 GitLab에 어느 URL 경로로 이동해야 하는지 지정합니다.
NameID 형식 지속적 NameID 형식에 대한 자세한 내용을 참조하십시오.
추가 URL 선택 사항 일부 제공업체의 다른 필드에서 발행자, 식별자 또는 주장 소비자 서비스 URL을 포함할 수 있습니다.

예제 구성에 대해서는 특정 제공업체에 대한 참고 사항을 참조하십시오.

용어 해설

용어 설명
신원 제공자 (IdP) Okta나 OneLogin과 같이 사용자 신원을 관리하는 서비스입니다.
서비스 제공자 (SP) SAML 2.0 SP인 GitLab이 SAML IdP에서 보이는 주장을 사용자의 인증에 사용합니다.
주장 사용자의 신원에 대한 정보, 예를 들어 이름이나 역할을 나타내는 것입니다. 클레임이나 속성이라고도 합니다.
단일 로그온 (SSO) 인증 체계의 이름입니다.
주장 소비자 서비스 URL IdP에서 성공적으로 인증한 후 사용자가 GitLab으로 리디렉트되는 콜백 URL입니다.
발행자 GitLab이 IdP에 대해 자신을 식별하는 방식입니다. “의존 당사자 신뢰 식별자”로도 알려져 있습니다.
인증서 지문 통신이 안전하게 이루어지고 있는지 확인하기 위해 서버가 올바른 인증서로 통신을 서명하고 있는지 확인합니다. 인증서 썸프린트로도 불립니다.

문제 해결

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