GitLab과 LDAP 통합하기

Tier: Free, Premium, Ultimate

Offering: Self-managed

GitLab은 사용자 인증을 지원하기 위해 LDAP - Lightweight Directory Access Protocol과 통합됩니다.

이 통합은 Microsoft Active Directory, Apple Open Directory, Open LDAP, 389 Server를 포함한 대부분의 LDAP 준수 디렉터리 서버와 작동합니다.

note
GitLab은 Microsoft Active Directory Trusts를 지원하지 않습니다.

LDAP를 통해 추가된 사용자:

  • 일반적으로 라이센스 좌석을 사용합니다.

  • GitLab 사용자 이름 또는 이메일 및 LDAP 비밀번호를 사용하여 Git으로 인증할 수 있으며, 비밀번호 인증이 비활성화된 경우에도 가능합니다. 활성화됨.

LDAP 구별 이름(DN)은 다음과 같은 경우 기존 GitLab 사용자와 연관됩니다:

  • 기존 사용자가 LDAP를 사용하여 처음으로 GitLab에 로그인할 때.
  • LDAP 이메일 주소가 기존 GitLab 사용자의 기본 이메일 주소일 때. LDAP 이메일 속성이 GitLab 사용자 데이터베이스에 존재하지 않는 경우 새로운 사용자가 생성됩니다.

기존 GitLab 사용자가 자신을 위해 LDAP 로그인을 활성화하려면:

  1. GitLab 이메일 주소가 LDAP 이메일 주소와 일치하는지 확인합니다.

  2. LDAP 자격 증명을 사용하여 GitLab에 로그인합니다.

보안

GitLab은 사용자가 LDAP에서 여전히 활성 상태인지 확인합니다.

사용자는 LDAP에서 비활성 상태로 간주됩니다:

  • 디렉터리에서 완전히 제거될 경우.

  • 구성된 base DN 또는 user_filter 검색 외부에 위치할 경우.

  • Active Directory에서 사용자 계정 제어 속성에 의해 비활성 또는 비활성화로 표시될 경우. 이는 속성 userAccountControl:1.2.840.113556.1.4.803이 비트 2 설정되었음을 의미합니다.

사용자가 LDAP에서 활성인지 비활성인지 확인하려면 다음 PowerShell 명령어와 Active Directory Module를 사용하여 Active Directory를 확인하세요:

Get-ADUser -Identity <username> -Properties userAccountControl | Select-Object Name, userAccountControl

GitLab은 LDAP 사용자의 상태를 확인합니다:

  • 모든 인증 공급자를 사용하여 로그인할 때.

  • 활성 웹 세션이나 Git 요청이 있는 1시간마다 토큰 또는 SSH 키를 사용하여.

  • LDAP 사용자 이름 및 비밀번호를 사용하여 HTTP 요청을 통해 Git을 수행할 때.

  • 사용자 동기화 중 매일 한 번.

사용자가 더 이상 LDAP에서 활성 상태가 아닌 경우, 그들은:

  • 로그아웃됩니다.

  • ldap_blocked 상태로 배치됩니다.

  • LDAP에서 재활성화될 때까지 어떤 인증 공급자를 사용하여도 로그인할 수 없습니다.

보안 위험

LDAP 사용자가 다음을 수행할 수 없는 경우에만 LDAP 통합을 사용해야 합니다:

  • LDAP 서버에서 mail, email 또는 userPrincipalName 속성을 변경할 수 없습니다. 이러한 사용자들은 GitLab 서버의 모든 계정을 차지할 수 있습니다.

  • 이메일 주소를 공유합니다. 동일한 이메일 주소를 가진 LDAP 사용자는 동일한 GitLab 계정을 공유할 수 있습니다.

LDAP 구성하기

전제 조건:

  • LDAP를 사용하려면 이메일 주소가 필요하며, 해당 이메일 주소를 사용해도 괜찮습니다.

LDAP를 구성하려면 구성 파일의 설정을 편집합니다:

편집할 파일은 GitLab 설정에 따라 다릅니다:

Linux 패키지 (Omnibus)

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

    gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' =>  'ldap.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'bind_dn' => 'CN=Gitlab,OU=Users,DC=domain,DC=com',
    'password' => '<bind_user_password>',
    'encryption' => 'simple_tls',
    'verify_certificates' => true,
    'timeout' => 10,
    'active_directory' => false,
    'user_filter' => '(employeeType=developer)',
    'base' => 'dc=example,dc=com',
    'lowercase_usernames' => 'false',
    'retry_empty_result_with_codes' => [80],
    'allow_username_or_email_login' => false,
    'block_auto_created_users' => false
  }
}

  2. 파일을 저장하고 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

  1. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다:

    global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'LDAP'
          host: 'ldap.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          bind_dn: 'CN=Gitlab,OU=Users,DC=domain,DC=com'
          password: '<bind_user_password>'
          encryption: 'simple_tls'
          verify_certificates: true
          timeout: 10
          active_directory: false
          user_filter: '(employeeType=developer)'
          base: 'dc=example,dc=com'
          lowercase_usernames: false
          retry_empty_result_with_codes: [80]
          allow_username_or_email_login: false
          block_auto_created_users: false

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

자세한 정보는 Helm 차트를 사용하여 설치한 GitLab 인스턴스를 위한 LDAP 구성 방법을 참조하세요.

Docker

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

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_enabled'] = true
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'label' => 'LDAP',
            'host' =>  'ldap.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'bind_dn' => 'CN=Gitlab,OU=Users,DC=domain,DC=com',
            'password' => '<bind_user_password>',
            'encryption' => 'simple_tls',
            'verify_certificates' => true,
            'timeout' => 10,
            'active_directory' => false,
            'user_filter' => '(employeeType=developer)',
            'base' => 'dc=example,dc=com',
            'lowercase_usernames' => 'false',
            'retry_empty_result_with_codes' => [80],
            'allow_username_or_email_login' => false,
            'block_auto_created_users' => false
          }
        }

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

    docker compose up -d
수동 컴파일 (소스)

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

    production: &base
  ldap:
    enabled: true
    servers:
      main:
        label: 'LDAP'
        host: 'ldap.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        bind_dn: 'CN=Gitlab,OU=Users,DC=domain,DC=com'
        password: '<bind_user_password>'
        encryption: 'simple_tls'
        verify_certificates: true
        timeout: 10
        active_directory: false
        user_filter: '(employeeType=developer)'
        base: 'dc=example,dc=com'
        lowercase_usernames: false
        retry_empty_result_with_codes: [80]
        allow_username_or_email_login: false
        block_auto_created_users: false

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

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

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

다양한 LDAP 옵션에 대한 자세한 내용은 gitlab.yml.example의 ldap 설정을 참조하세요.

LDAP 구성을 완료한 후, 구성을 테스트하려면 LDAP 확인 Rake 작업을 사용하세요.

기본 구성 설정

다음 기본 설정이 가능합니다:

설정 필수 유형 설명
label 예 문자열 LDAP 서버에 대한 사람 친화적인 이름입니다. 로그인 페이지에 표시됩니다. 예: 'Paris' 또는 'Acme, Ltd.'
host 예 문자열 LDAP 서버의 IP 주소 또는 도메인 이름입니다. hosts가 정의되면 무시됩니다. 예: 'ldap.mydomain.com'
port 예 정수 LDAP 서버와 연결할 포트입니다. hosts가 정의되면 무시됩니다. 예: 389 또는 636 (SSL용)
uid 예 문자열 사용자가 로그인하는 데 사용하는 사용자 이름과 매핑되는 LDAP 속성입니다. uid에 매핑되는 값이 아니라 속성이어야 합니다. GitLab 사용자 이름에는 영향을 미치지 않습니다 (자세한 내용은 속성 섹션을 참조하세요). 예: 'sAMAccountName' 또는 'uid' 또는 'userPrincipalName'
base 예 문자열 사용자를 검색할 수 있는 기준입니다. 예: 'ou=people,dc=gitlab,dc=example' 또는 'DC=mydomain,DC=com'
encryption 예 문자열 암호화 방법 (method 키는 encryption으로 대체되었습니다). 세 가지 값 중 하나를 가질 수 있습니다: 'start_tls', 'simple_tls', 또는 'plain'. simple_tls는 LDAP 라이브러리의 ‘Simple TLS’에 해당하고, start_tls는 일반 TLS와 혼동해서는 안 됩니다. simple_tls를 지정하면 일반적으로 포트 636에서 실행되고, start_tls (StartTLS)는 포트 389에서 실행됩니다. plain 또한 포트 389에서 작동합니다.
hosts 아니오 문자열 및 정수의 배열 연결을 열기 위한 호스트 및 포트 쌍의 배열입니다. 각 구성된 서버는 동일한 데이터 세트를 가져야 합니다. 이는 여러 다른 LDAP 서버를 구성하기 위한 것이 아니라 장애 조치를 구성하기 위한 것입니다. 호스트는 구성된 순서대로 시도됩니다. 예: [['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]
bind_dn 아니오 문자열 바인딩할 사용자의 전체 DN입니다. 예: 'america\momo' 또는 'CN=Gitlab,OU=Users,DC=domain,DC=com'
password 아니오 문자열 바인드 사용자 비밀번호입니다.
verify_certificates 아니오 부울 기본값은 true입니다. 암호화 방법이 start_tls 또는 simple_tls인 경우 SSL 인증서 검증을 활성화합니다. false로 설정하면 LDAP 서버의 SSL 인증서 검증이 수행되지 않습니다.
timeout 아니오 정수 기본값은 10입니다. LDAP 쿼리에 대한 초 단위의 타임아웃을 설정합니다. 이는 LDAP 서버가 응답하지 않을 경우 요청이 차단되는 것을 방지하는 데 도움이 됩니다. 값이 0이면 타임아웃이 없습니다.
active_directory 아니오 부울 이 설정은 LDAP 서버가 Active Directory LDAP 서버인지 지정합니다. 비 AD 서버의 경우 AD 특정 쿼리를 건너뜁니다. LDAP 서버가 AD가 아닌 경우 이 설정을 false로 설정하세요.
allow_username_or_email_login 아니오 부울 기본값은 false입니다. 활성화하면 GitLab은 사용자가 로그인할 때 제출한 LDAP 사용자 이름의 첫 번째 @ 이후의 모든 것을 무시합니다. ActiveDirectory에서 uid: 'userPrincipalName'을 사용하고 있다면 이 설정을 비활성화해야 합니다. userPrincipalName에 @가 포함되어 있기 때문입니다.
block_auto_created_users 아니오 부울 기본값은 false입니다. GitLab 설치에서 청구 가능한 사용자 수를 철저히 관리하려면 이 설정을 활성화하여 신규 사용자가 관리자가 승인할 때까지 차단되도록 해야 합니다.
user_filter 아니오 문자열 LDAP 사용자를 필터링합니다. RFC 4515의 형식을 따릅니다. GitLab은 omniauth-ldap의 사용자 정의 필터 구문을 지원하지 않습니다. user_filter 필드 구문 예시:

- '(employeeType=developer)'
- '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
lowercase_usernames 아니오 부울 활성화되면 GitLab은 이름을 소문자로 변환합니다.
retry_empty_result_with_codes 아니오 배열 결과/내용이 비어 있으면 작업을 다시 시도하기 위해 LDAP 쿼리 응답 코드의 배열입니다. Google Secure LDAP의 경우 이 값을 [80]으로 설정하세요.

SSL 구성 설정

tls_options 이름/값 쌍 아래에 SSL 구성 설정을 구성할 수 있습니다. 다음 설정은 모두 선택 사항입니다:

설정 설명 예시
ca_file PEM 형식 CA 인증서가 포함된 파일의 경로를 지정합니다. 내부 CA가 필요한 경우에 사용합니다. '/etc/ca.pem'
ssl_version OpenSSL에서 사용할 SSL 버전을 지정합니다. OpenSSL 기본값이 적합하지 않은 경우에 사용합니다. 'TLSv1_1'
ciphers LDAP 서버와의 통신에 사용할 특정 SSL 암호를 지정합니다. 'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'
cert 클라이언트 인증서. '-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'
key 클라이언트 개인 키. '-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'

아래 예시는 tls_options에서 ca_file 및 ssl_version을 설정하는 방법을 보여줍니다:

Linux 패키지 (Omnibus)

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

    gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' =>  'ldap.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com'
    'tls_options' => {
      'ca_file' => '/path/to/ca_file.pem',
      'ssl_version' => 'TLSv1_2'
    }
  }
}

  2. 파일을 저장하고 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

  1. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다:

    global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'LDAP'
          host: 'ldap.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'
          tls_options:
            ca_file: '/path/to/ca_file.pem'
            ssl_version: 'TLSv1_2'

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

자세한 내용은 Helm 차트를 사용하여 설치된 GitLab 인스턴스에 대한 LDAP 구성 방법을 참조하십시오.

Docker

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

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_enabled'] = true
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'label' => 'LDAP',
            'host' =>  'ldap.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
            'tls_options' => {
              'ca_file' => '/path/to/ca_file.pem',
              'ssl_version' => 'TLSv1_2'
            }
          }
        }

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

    docker compose up -d
직접 컴파일 (소스)

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

    production: &base
  ldap:
    enabled: true
    servers:
      main:
        label: 'LDAP'
        host: 'ldap.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        encryption: 'simple_tls'
        base: 'dc=example,dc=com'
        tls_options:
          ca_file: '/path/to/ca_file.pem'
          ssl_version: 'TLSv1_2'

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

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

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

속성 구성 설정

GitLab은 이러한 LDAP 속성을 사용하여 LDAP 사용자에 대한 계정을 생성합니다. 지정된 속성은 다음 중 하나일 수 있습니다:

  • 문자열로 된 속성 이름입니다. 예를 들어, 'mail'.
  • 순서에 따라 시도할 속성 이름의 배열입니다. 예를 들어, ['mail', 'email'].

사용자의 LDAP 로그인은 지정된 LDAP 속성으로 uid입니다.

아래의 모든 LDAP 속성은 선택사항입니다. 이러한 속성을 정의하는 경우, attributes 해시에서 그렇게 해야 합니다.

설정 설명 예시
username GitLab 계정이 프로비저닝될 @username입니다. 값이 이메일 주소를 포함하는 경우, GitLab 사용자 이름은 이메일 주소에서 @ 앞부분입니다. 기본값은 지정된 LDAP 속성으로 uid입니다. ['uid', 'userid', 'sAMAccountName']
email 사용자 이메일에 대한 LDAP 속성입니다. 기본값은 ['mail', 'email', 'userPrincipalName']입니다. ['mail', 'email', 'userPrincipalName']
name 사용자 표시 이름에 대한 LDAP 속성입니다. name이 비어 있으면 전체 이름은 first_name과 last_name에서 가져옵니다. 기본값은 'cn'입니다. 속성 'cn' 또는 'displayName'은 일반적으로 전체 이름을 포함합니다. 그 외에, 'somethingNonExistent'와 같은 존재하지 않는 속성을 지정하여 first_name 및 last_name 사용을 강제할 수 있습니다.
first_name 사용자 이름에 대한 LDAP 속성입니다. name에 대해 구성된 속성이 존재하지 않을 때 사용됩니다. 기본값은 'givenName'입니다. 'givenName'
last_name 사용자 성에 대한 LDAP 속성입니다. name에 대해 구성된 속성이 존재하지 않을 때 사용됩니다. 기본값은 'sn'입니다. 'sn'

LDAP 동기화 구성 설정

Tier: Premium, Ultimate Offering: Self-managed

이 LDAP 동기화 구성 설정은 선택 사항이며, external_groups가 구성된 경우에는 group_base가 필요합니다:

설정 설명 예시
group_base 그룹을 검색하는 데 사용되는 기준입니다. 모든 유효한 그룹은 DN의 일부로 이 기준을 포함합니다. 'ou=groups,dc=gitlab,dc=example'
admin_group GitLab 관리자를 포함하는 그룹의 CN입니다. cn=administrators 또는 전체 DN이 아닙니다. 'administrators'
external_groups 외부로 간주되어야 하는 사용자 그룹의 CN 배열입니다. cn=interns 또는 전체 DN이 아닙니다. ['interns', 'contractors']
sync_ssh_keys 사용자의 공개 SSH 키를 포함하는 LDAP 속성입니다. 'sshPublicKey' 또는 설정되지 않은 경우 false
note
Sidekiq가 Rails 서버와 다른 서버에 구성된 경우, LDAP 동기화가 작동할 수 있도록 LDAP 구성을 모든 Sidekiq 서버에 추가해야 합니다.

여러 LDAP 서버 사용

Tier: Premium, Ultimate Offering: Self-managed

여러 LDAP 서버에 사용자가 있는 경우, GitLab이 이를 사용할 수 있도록 구성할 수 있습니다. 추가 LDAP 서버를 추가하려면:

  1. main LDAP 구성을 복제합니다.

  2. 각 복제 구성에서 추가 서버의 세부 정보를 편집합니다.

    • 각 추가 서버에 대해 main, secondary 또는 tertiary와 같이 다른 제공자 ID를 선택하세요. 소문자 알파벳과 숫자를 사용합니다. GitLab은 제공자 ID를 사용하여 각 사용자를 특정 LDAP 서버와 연결합니다.
    • 각 항목에 대해 고유한 label 값을 사용합니다. 이러한 값은 로그인 페이지에서 탭 이름으로 사용됩니다.

다음 예는 최소 구성으로 세 개의 LDAP 서버를 구성하는 방법을 보여줍니다:

Linux 패키지 (Omnibus)

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

    gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'GitLab AD',
    'host' =>  'ad.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com',
  },

  'secondary' => {
    'label' => 'GitLab Secondary AD',
    'host' =>  'ad-secondary.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com',
  },

  'tertiary' => {
    'label' => 'GitLab Tertiary AD',
    'host' =>  'ad-tertiary.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com',
  }
}

  2. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

  1. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다:

    global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'GitLab AD'
          host: 'ad.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'
        secondary:
          label: 'GitLab Secondary AD'
          host: 'ad-secondary.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'
        tertiary:
          label: 'GitLab Tertiary AD'
          host: 'ad-tertiary.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

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

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_enabled'] = true
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'label' => 'GitLab AD',
            'host' =>  'ad.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
          },

          'secondary' => {
            'label' => 'GitLab Secondary AD',
            'host' =>  'ad-secondary.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
          },

          'tertiary' => {
            'label' => 'GitLab Tertiary AD',
            'host' =>  'ad-tertiary.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
          }
        }

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

    docker compose up -d
소스에서 직접 컴파일 (Self-compiled)

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

    production: &base
  ldap:
    enabled: true
    servers:
      main:
        label: 'GitLab AD'
        host: 'ad.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        base: 'dc=example,dc=com'
        encryption: 'simple_tls'
      secondary:
        label: 'GitLab Secondary AD'
        host: 'ad-secondary.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        base: 'dc=example,dc=com'
        encryption: 'simple_tls'
      tertiary:
        label: 'GitLab Tertiary AD'
        host: 'ad-tertiary.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        base: 'dc=example,dc=com'
        encryption: 'simple_tls'

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

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

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

LDAP 옵션에 대한 자세한 내용은 gitlab.yml.example의 ldap 설정을 참조하십시오.

이 예제는 다음과 같은 탭이 포함된 로그인 페이지를 만듭니다:

  • GitLab AD.
  • GitLab Secondary AD.
  • GitLab Tertiary AD.

LDAP 사용자 필터 설정

LDAP 서버의 LDAP 사용자 하위 집합으로 GitLab 접근을 제한하려면, 먼저 구성된 base를 좁혀야 합니다. 그러나 필요에 따라 추가 사용자 필터를 설정할 수 있습니다. 필터는 RFC 4515를 준수해야 합니다.

Linux 패키지 (Omnibus)

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

    gitlab_rails['ldap_servers'] = {
  'main' => {
    'user_filter' => '(employeeType=developer)'
  }
}

  2. 파일을 저장하고 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

  1. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml를 편집합니다:

    global:
  appConfig:
    ldap:
      servers:
        main:
          user_filter: '(employeeType=developer)'

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

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

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'user_filter' => '(employeeType=developer)'
          }
        }

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

    docker compose up -d
자체 컴파일 (소스)

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

    production: &base
  ldap:
    servers:
      main:
        user_filter: '(employeeType=developer)'

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

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

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

Active Directory 그룹의 중첩된 구성원 접근을 제한하려면, 다음 구문을 사용합니다:

(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)

LDAP_MATCHING_RULE_IN_CHAIN 필터에 대한 더 많은 정보는 검색 필터 구문을 참조하세요.

사용자 필터에서 중첩된 구성원에 대한 지원은 그룹 동기화 중첩 그룹 지원과 혼동되지 않아야 합니다.

GitLab은 OmniAuth LDAP에서 사용하는 사용자 정의 필터 구문을 지원하지 않습니다.

user_filter에서 특수 문자 이스케이프

user_filter DN은 특수 문자를 포함할 수 있습니다. 예를 들어:

  • 쉼표:

    OU=GitLab, Inc,DC=gitlab,DC=com

  • 여는 괄호와 닫는 괄호:

    OU=GitLab (Inc),DC=gitlab,DC=com

이러한 문자는 RFC 4515에서 문서화된 대로 이스케이프되어야 합니다.

  • 쉼표는 \2C로 이스케이프합니다. 예:

    OU=GitLab\2C Inc,DC=gitlab,DC=com

  • 여는 괄호는 \28로, 닫는 괄호는 \29로 이스케이프합니다. 예:

    OU=GitLab \28Inc\29,DC=gitlab,DC=com

LDAP 사용자 이름 소문자 사용 설정

일부 LDAP 서버는 구성에 따라 대문자 사용자 이름을 반환할 수 있습니다.

이로 인해 대문자 이름으로 링크나 네임스페이스를 생성하는 등의 여러 혼란스러운 문제가 발생할 수 있습니다.

GitLab은 구성 옵션 lowercase_usernames를 활성화함으로써 LDAP 서버에서 제공된 사용자 이름을 자동으로 소문자로 변환할 수 있습니다. 기본적으로 이 구성 옵션은 false입니다.

리눅스 패키지 (Omnibus)

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

    gitlab_rails['ldap_servers'] = {
  'main' => {
    'lowercase_usernames' => true
  }
}

  2. 파일을 저장하고 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

  1. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml

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

    global:
  appConfig:
    ldap:
      servers:
        main:
         lowercase_usernames: true

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

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

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'lowercase_usernames' => true
          }
        }

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

    docker compose up -d
소스에서 컴파일한 버전

  1. config/gitlab.yaml 파일을 편집합니다:

    production:
  ldap:
    servers:
      main:
        lowercase_usernames: true

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

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

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

LDAP 웹 로그인 비활성화

SAML과 같은 대안이 선호될 때 웹 UI를 통해 LDAP 자격 증명을 사용하는 것을 방지하는 것이 유용할 수 있습니다.

이것은 LDAP가 그룹 동기화에 사용될 수 있도록 하면서도 SAML ID 제공자가 사용자 정의 2FA와 같은 추가 검사를 처리할 수 있도록 허용합니다.

LDAP 웹 로그인이 비활성화되면 사용자는 로그인 페이지에서 LDAP 탭을 보지 못합니다.

이것은 Git 접근을 위한 LDAP 자격 증명의 사용을 비활성화하지 않습니다.

리눅스 패키지 (Omnibus)

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

    gitlab_rails['prevent_ldap_sign_in'] = true

  2. 파일을 저장하고 GitLab을 재구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

  1. Helm 값을 내보냅니다:

    helm get values gitlab > gitlab_values.yaml

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

    global:
  appConfig:
    ldap:
      preventSignin: true

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Docker

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

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['prevent_ldap_sign_in'] = true

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

    docker compose up -d
소스에서 컴파일한 버전

  1. config/gitlab.yaml 파일을 편집합니다:

    production:
  ldap:
    prevent_ldap_sign_in: true

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

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

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

GitLab을 위한 스마트 카드 인증 제공

GitLab과 LDAP 서버에서 스마트 카드를 사용하는 방법에 대한 자세한 내용은 스마트 카드 인증을 참조하세요.

암호화된 자격 증명 사용

구성 파일에 평문으로 LDAP 통합 자격 증명이 저장되는 대신, 암호화된 파일을 선택적으로 사용할 수 있습니다.

전제 조건:

  • 암호화된 자격 증명을 사용하려면, 먼저 암호화된 구성을 활성화해야 합니다.

LDAP에 대한 암호화된 구성은 암호화된 YAML 파일에 존재합니다. 파일의 비암호화된 내용은 LDAP 구성의 servers 블록에서 비밀 설정의 하위 집합이어야 합니다.

암호화된 파일에 대한 지원 구성 항목은 다음과 같습니다:

  • bind_dn
  • password
Linux 패키지 (Omnibus)

  1. 처음에 /etc/gitlab/gitlab.rb의 LDAP 구성은 다음과 같았습니다:

      gitlab_rails['ldap_servers'] = {
    'main' => {
      'bind_dn' => 'admin',
      'password' => '123'
    }
  }

  2. 암호화된 비밀을 편집합니다:

    sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim

  3. LDAP 비밀의 비암호화된 내용을 입력합니다:

    main:
  bind_dn: admin
  password: '123'

  4. /etc/gitlab/gitlab.rb를 편집하고 bind_dn 및 password 설정을 제거합니다.

  5. 파일을 저장하고 GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
Helm 차트 (Kubernetes)

Kubernetes 비밀을 사용하여 LDAP 비밀번호를 저장하세요. 자세한 내용은 Helm LDAP 비밀을 참조하세요.

Docker

  1. 처음에 docker-compose.yml의 LDAP 구성은 다음과 같았습니다:

    version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'bind_dn' => 'admin',
            'password' => '123'
          }
        }

  2. 컨테이너 안으로 들어가서 암호화된 비밀을 편집합니다:

    sudo docker exec -t <container_name> bash
gitlab-rake gitlab:ldap:secret:edit EDITOR=vim

  3. LDAP 비밀의 비암호화된 내용을 입력합니다:

    main:
  bind_dn: admin
  password: '123'

  4. docker-compose.yml을 편집하고 bind_dn 및 password 설정을 제거합니다.

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

    docker compose up -d
소스에서 컴파일한 것 (Self-compiled)

  1. 처음에 /home/git/gitlab/config/gitlab.yml의 LDAP 구성은 다음과 같았습니다:

    production:
  ldap:
    servers:
      main:
        bind_dn: admin
        password: '123'

  2. 암호화된 비밀을 편집합니다:

    bundle exec rake gitlab:ldap:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production

  3. LDAP 비밀의 비암호화된 내용을 입력합니다:

    main:
 bind_dn: admin
 password: '123'

  4. /home/git/gitlab/config/gitlab.yml을 편집하고 bind_dn 및 password 설정을 제거합니다.

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

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

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

LDAP DN 및 이메일 업데이트

LDAP 서버가 GitLab에 사용자를 생성하면 사용자의 LDAP DN이 해당 사용자의 GitLab 계정에 연결되어 식별자 역할을 합니다.

사용자가 LDAP로 로그인하려고 시도할 때, GitLab은 해당 사용자의 계정에 저장된 DN을 사용하여 사용자를 찾으려고 합니다.

  • GitLab이 DN과 사용자의 이메일 주소로 사용자를 찾으면:
    • GitLab 계정의 이메일 주소와 일치하면 GitLab은 추가 행동을 취하지 않습니다.
    • 변경되면, GitLab은 사용자의 이메일을 LDAP의 이메일과 일치하도록 업데이트합니다.
  • GitLab이 DN으로 사용자를 찾을 수 없는 경우, 이메일로 사용자를 찾으려고 합니다. GitLab이:
    • 이메일로 사용자를 찾으면, GitLab은 사용자의 GitLab 계정에 저장된 DN을 업데이트합니다. 두 값 모두 이제 LDAP에 저장된 정보와 일치합니다.
    • 이메일 주소로 사용자를 찾을 수 없으면(두 값 모두 변경된 경우), 사용자 DN 및 이메일이 변경되었습니다.

익명 LDAP 인증 비활성화

GitLab은 TLS 클라이언트 인증을 지원하지 않습니다. LDAP 서버에서 다음 단계를 완료하십시오.

  1. 익명 인증을 비활성화합니다.
  2. 다음 인증 유형 중 하나를 활성화합니다:
    • 단순 인증.
    • 단순 인증 및 보안 계층(SASL) 인증.

LDAP 서버의 TLS 클라이언트 인증 설정은 필수가 아니며, 클라이언트는 TLS 프로토콜로 인증할 수 없습니다.

LDAP에서 삭제된 사용자

LDAP 서버에서 삭제된 사용자:

그러나 이러한 사용자는 다음 LDAP 검사 캐시가 실행될 때까지 SSH로 Git을 계속 사용할 수 있습니다.

계정을 즉시 삭제하려면 수동으로 사용자를 차단할 수 있습니다.

사용자 이메일 주소 업데이트

LDAP 서버의 이메일 주소는 LDAP로 로그인할 때 사용자의 진실한 출처로 간주됩니다.

사용자 이메일 주소 업데이트는 사용자를 관리하는 LDAP 서버에서 수행해야 합니다. GitLab의 이메일 주소는 다음 중 하나로 업데이트됩니다:

업데이트된 사용자의 이전 이메일 주소는 해당 사용자의 커밋 기록을 보존하기 위해 보조 이메일 주소가 됩니다.

사용자 업데이트의 예상되는 동작에 대한 자세한 내용은 LDAP 문제 해결 섹션에서 확인할 수 있습니다.

Google Secure LDAP

Google Cloud Identity는 GitLab과 인증 및 그룹 동기화에 대해 구성할 수 있는 Secure LDAP 서비스를 제공합니다. 자세한 구성 지침은 Google Secure LDAP를 참조하십시오.

사용자 및 그룹 동기화

LDAP와 GitLab 간의 사용자 및 그룹 동기화에 대한 자세한 내용은 LDAP 동기화를 참조하십시오.

LDAP에서 SAML로 이동

  1. SAML 구성 추가:

  2. 선택 사항. 로그인 페이지에서 LDAP 인증 비활성화.

  3. 선택 사항. 사용자 연결 문제를 해결하려면 먼저 이 사용자들의 LDAP 신원을 제거할 수 있습니다.

  4. 사용자가 자신의 계정에 로그인할 수 있는지 확인합니다. 사용자가 로그인할 수 없는 경우, 해당 사용자의 LDAP가 아직 있는지 확인하고 필요시 제거합니다. 이 문제가 지속되면, 로그를 확인하여 문제를 식별합니다.

  5. 구성 파일에서 다음을 변경합니다:
    • omniauth_auto_link_user를 saml로만 설정합니다.
    • omniauth_auto_link_ldap_user를 false로 설정합니다.
    • ldap_enabled를 false로 설정합니다. LDAP 공급자 설정을 주석 처리할 수도 있습니다.

문제 해결

LDAP 문제 해결에 대한 관리자 가이드를 참조하세요.