InfoGrab DocsInfoGrab Docs

GitLab과 LDAP 통합

요약

GitLab은 LDAP - Lightweight Directory Access Protocol과 통합되어 사용자 인증을 지원합니다. 이 통합은 다음을 포함한 대부분의 LDAP 호환 디렉터리 서버에서 작동합니다. GitLab은 Microsoft Active Directory Trusts를 지원하지 않습니다.

GitLab은 LDAP - Lightweight Directory Access Protocol과 통합되어 사용자 인증을 지원합니다.

이 통합은 다음을 포함한 대부분의 LDAP 호환 디렉터리 서버에서 작동합니다.

  • Microsoft Active Directory.
  • Apple Open Directory.
  • OpenLDAP.
  • 389 Server.
Note

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

LDAP를 통해 추가된 사용자는 다음과 같습니다.

  • 일반적으로 라이선스 시트를 사용합니다.
  • Git에 대한 비밀번호 인증이 비활성화되어 있어도 GitLab 사용자 이름 또는 이메일과 LDAP 비밀번호로 Git에 인증할 수 있습니다.

LDAP 고유 이름(DN)은 다음 경우에 기존 GitLab 사용자와 연결됩니다.

  • 기존 사용자가 LDAP로 GitLab에 처음 로그인하는 경우.
  • LDAP 이메일 주소가 기존 GitLab 사용자의 기본 이메일 주소인 경우. LDAP 이메일 속성이 GitLab 사용자 데이터베이스에 없으면 새 사용자가 생성됩니다.

기존 GitLab 사용자가 스스로 LDAP 로그인을 사용하려면 다음을 수행해야 합니다.

  1. GitLab 이메일 주소가 LDAP 이메일 주소와 일치하는지 확인합니다.
  2. LDAP 자격 증명으로 GitLab에 로그인합니다.
Note

사용자가 LDAP ID를 GitLab 계정에 연결하면 더 이상 표준 사용자 이름과 비밀번호 인증 흐름을 사용할 수 없습니다. 대신 LDAP 자격 증명으로 인증해야 합니다. 사용자 이름과 비밀번호로 로그인을 시도하면 잘못된 로그인 또는 비밀번호 오류가 반환됩니다.

보안#

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

다음 경우 사용자는 LDAP에서 비활성 상태로 간주됩니다.

  • 디렉터리에서 완전히 제거된 경우.
  • 구성된 base DN 또는 user_filter 검색 범위 밖에 있는 경우.
  • 사용자 계정 제어 속성을 통해 Active Directory에서 비활성화(disabled 또는 deactivated)로 표시된 경우. 이는 속성 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 사용자의 상태를 확인합니다.

  • 인증 공급자를 사용해 로그인할 때.
  • 토큰 또는 SSH 키를 사용하는 활성 웹 세션이나 Git 요청에 대해 한 시간에 한 번.
  • LDAP 사용자 이름과 비밀번호로 HTTP를 통한 Git 요청을 수행할 때.
  • 사용자 동기화 중 하루에 한 번.

사용자가 LDAP에서 더 이상 활성 상태가 아니면 다음과 같이 처리됩니다.

  • 로그아웃됩니다.
  • ldap_blocked 상태가 됩니다.
  • LDAP에서 다시 활성화될 때까지 어떤 인증 공급자로도 로그인할 수 없습니다.

보안 위험#

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

  • LDAP 서버에서 mail, email 또는 userPrincipalName 속성을 변경하는 것. 이러한 사용자는 GitLab 서버의 모든 계정을 탈취할 수 있습니다.
  • 이메일 주소를 공유하는 것. 이메일 주소가 같은 LDAP 사용자는 같은 GitLab 계정을 공유할 수 있습니다.

LDAP 구성#

사전 요구 사항:

  • LDAP를 사용하려면 이메일 주소가 있어야 합니다. 그 이메일 주소로 로그인하는지 여부와 관계없습니다.

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

편집하는 파일은 GitLab 설정에 따라 다릅니다.

  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

  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를 구성하는 방법을 참고합니다.

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

다양한 LDAP 옵션에 대한 자세한 내용은 gitlab.yml.example의 ldap 설정을 참고합니다.

LDAP를 구성한 후 구성을 테스트하려면 LDAP check Rake 태스크를 사용합니다.

기본 구성 설정#

다음 기본 설정을 사용할 수 있습니다.

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

- '(employeeType=developer)'
- '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
lowercase_usernames ❌ Boolean 활성화하면 GitLab이 이름을 소문자로 변환합니다.
retry_empty_result_with_codes ❌ Array 결과나 콘텐츠가 비어 있을 때 작업을 재시도할 LDAP 쿼리 응답 코드의 배열입니다. Google Secure LDAP에서는 이 값을 [80]으로 설정합니다.
Note

GitLab은 Microsoft advisory ADV190023에서 도입된 Microsoft Active Directory Services의 더 엄격한 바인딩 요구 사항의 영향을 받지 않습니다. 자세한 내용은 issue 201894를 참고합니다.

SSL 구성 설정#

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

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

다음 예시는 tls_options에서 ca_file과 ssl_version을 설정하는 방법을 보여 줍니다.

  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

  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를 구성하는 방법을 참고합니다.

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

속성 구성 설정#

GitLab은 다음 LDAP 속성을 사용하여 LDAP 사용자의 계정을 생성합니다. 지정하는 속성은 다음 중 하나일 수 있습니다.

  • 문자열 형태의 속성 이름. 예: 'mail'.
  • 순서대로 시도할 속성 이름의 배열. 예: ['mail', 'email'].

사용자의 LDAP 로그인 이름은 uid로 지정한 LDAP 속성입니다.

다음 LDAP 속성은 모두 선택 사항입니다. 기본값과 다른 속성만 지정하면 됩니다. 예를 들어 username을 지정했다면 나머지를 지정할 필요가 없습니다. 나머지에는 기본값이 적용됩니다.

이러한 속성을 정의하는 경우 attributes 해시 안에 정의해야 합니다.

설정 설명 기본값
username GitLab 계정을 프로비저닝할 @username입니다. 값에 이메일 주소가 포함되어 있으면 GitLab 사용자 이름은 이메일 주소에서 @ 앞부분입니다. 기본값은 uid로 지정한 LDAP 속성(['uid', 'userid', 'sAMAccountName'])입니다.
email 사용자 이메일에 대한 LDAP 속성입니다. ['mail', 'email', 'userPrincipalName']
name 사용자 표시 이름에 대한 LDAP 속성입니다. name이 비어 있으면 first_name과 last_name에서 전체 이름을 가져옵니다. 'cn' 또는 'displayName' 속성에 전체 이름이 들어 있는 경우가 많습니다. 또는 'somethingNonExistent'처럼 존재하지 않는 속성을 지정하여 first_name과 last_name을 강제로 사용하게 할 수 있습니다. 'cn'
first_name 사용자 이름(first name)에 대한 LDAP 속성입니다. name에 구성한 속성이 존재하지 않을 때 사용합니다. 'givenName'
last_name 사용자 성(last name)에 대한 LDAP 속성입니다. name에 구성한 속성이 존재하지 않을 때 사용합니다. 'sn'

사용자 이름에 displayName을 사용하고 email에 속성 배열을 사용하는 구성 예시입니다.

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

    gitlab_rails['ldap_servers'] = {
  'main' => {
    # Other configuration settings ...
    'attributes' => {
      'username' => 'uid',
      'email' => ['mail', 'email', 'userPrincipalName'],
      'name' => 'displayName',
      'first_name' => 'givenName',
      'last_name' => 'sn'
    }
  }
}

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

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

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

    global:
  appConfig:
    ldap:
      servers:
        main:
          # Other configuration settings ...
          attributes:
            username: 'uid'
            email:
              - 'mail'
              - 'email'
              - 'userPrincipalName'
            name: 'displayName'
            first_name: 'givenName'
            last_name: 'sn'

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  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' => {
            # Other configuration settings ...
            'attributes' => {
              'username' => 'uid',
              'email' => ['mail', 'email', 'userPrincipalName'],
              'name' => 'displayName',
              'first_name' => 'givenName',
              'last_name' => 'sn'
            }
          }
        }

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

    docker compose up -d

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

    production: &base
  ldap:
    servers:
      main:
        # Other configuration settings ...
        attributes:
          username: 'uid'
          email:
            - 'mail'
            - 'email'
            - 'userPrincipalName'
          name: 'displayName'
          first_name: 'givenName'
          last_name: 'sn'

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 동기화 구성 설정#

다음 LDAP 동기화 구성 설정은 선택 사항입니다. 단, external_groups를 구성하는 경우에는 group_base가 필요합니다.

설정 설명 예시
group_base 그룹을 검색하는 기준 위치입니다. 유효한 모든 그룹의 DN에는 이 기준이 포함됩니다. 'ou=groups,dc=gitlab,dc=example'
group_filter group_base 아래에서 검색할 LDAP 그룹을 필터링합니다. RFC 4515 형식을 따릅니다. '(objectclass=group)'
admin_group GitLab 관리자가 속한 그룹의 CN입니다. cn=administrators나 전체 DN이 아닙니다. 'administrators'
audit_group GitLab 감사자가 속한 그룹의 CN입니다. cn=auditors나 전체 DN이 아닙니다. 'auditors'
external_groups 외부 사용자로 간주할 사용자가 속한 그룹의 CN 배열입니다. cn=interns나 전체 DN이 아닙니다. ['interns', 'contractors']
sync_ssh_keys 사용자의 공개 SSH 키가 들어 있는 LDAP 속성입니다. 'sshPublicKey' 또는 설정하지 않은 경우 false
Note

Sidekiq이 Rails 서버와 다른 서버에 구성되어 있으면 LDAP 동기화가 작동하도록 모든 Sidekiq 서버에도 LDAP 구성을 추가해야 합니다.

여러 LDAP 서버 사용#

여러 LDAP 서버에 사용자가 있는 경우 GitLab이 해당 서버를 사용하도록 구성할 수 있습니다. LDAP 서버를 추가하려면 다음을 수행합니다.

  1. main LDAP 구성을 복제합니다.
  2. 복제한 각 구성을 추가 서버의 세부 정보로 편집합니다.
    • 추가하는 각 서버에는 main, secondary, tertiary처럼 서로 다른 공급자 ID를 지정합니다. 소문자 영숫자를 사용합니다. GitLab은 공급자 ID를 사용하여 각 사용자를 특정 LDAP 서버에 연결합니다.
    • 각 항목에 고유한 label 값을 사용합니다. 이 값은 로그인 페이지의 탭 이름으로 사용됩니다.

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

  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

  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

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

다양한 LDAP 옵션에 대한 자세한 내용은 gitlab.yml.example의 ldap 설정을 참고합니다.

이 예시를 적용하면 로그인 페이지에 다음 탭이 표시됩니다.

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

LDAP 사용자 필터 설정#

GitLab 접근을 LDAP 서버의 일부 LDAP 사용자로 제한하려면 먼저 구성된 base를 좁힙니다. 그런 다음 필요하면 LDAP 사용자 필터를 설정하여 사용자를 추가로 필터링할 수 있습니다. 필터는 RFC 4515를 준수해야 합니다.

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

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

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

    sudo gitlab-ctl reconfigure

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running 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 필터에 대한 자세한 내용은 Search Filter Syntax를 참고합니다.

사용자 필터의 중첩 멤버 지원을 그룹 동기화 중첩 그룹 지원과 혼동하지 않아야 합니다.

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 서버는 구성에 따라 대문자 사용자 이름을 반환할 수 있습니다. 이로 인해 대문자 이름으로 링크나 네임스페이스가 생성되는 등 여러 혼란스러운 문제가 발생할 수 있습니다.

구성 옵션 lowercase_usernames를 활성화하면 GitLab이 LDAP 서버에서 제공한 사용자 이름을 자동으로 소문자로 변환합니다. 이 구성 옵션의 기본값은 false입니다.

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

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

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

    sudo gitlab-ctl reconfigure

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 웹 로그인 비활성화#

SAML 같은 대안을 사용하려는 경우 웹 UI에서 LDAP 자격 증명 사용을 막는 것이 유용할 수 있습니다. 이렇게 하면 LDAP를 그룹 동기화에 사용하면서 SAML ID 공급자가 사용자 지정 2FA 같은 추가 검사를 처리하도록 할 수도 있습니다. 이 경우 LDAP는 그룹 동기화에만 사용됩니다.

LDAP 웹 로그인을 비활성화하면 사용자에게 로그인 페이지에 LDAP 탭이 표시되지 않습니다. 이 설정은 Git 접근에 LDAP 자격 증명을 사용하는 것을 비활성화하지 않습니다.

LDAP 웹 로그인을 비활성화해도 이러한 사용자가 웹 UI에서 차단되지는 않습니다. GitLab 비밀번호로 계속 로그인할 수 있습니다. ID 공급자를 통한 로그인만 요구하려면 다음도 함께 수행합니다. SSO ID가 있는 사용자의 비밀번호 및 패스키 인증 비활성화.

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

    gitlab_rails['prevent_ldap_sign_in'] = true

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

    sudo gitlab-ctl reconfigure

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

GitLab에 스마트 카드 인증 제공#

LDAP 서버 및 GitLab에서 스마트 카드를 사용하는 방법에 대한 자세한 내용은 스마트 카드 인증을 참고합니다.

암호화된 자격 증명 사용#

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

사전 요구 사항:

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

LDAP의 암호화된 구성은 암호화된 YAML 파일에 있습니다. 파일의 암호화되지 않은 내용은 LDAP 구성의 servers 블록에 있는 시크릿 설정의 부분 집합이어야 합니다.

암호화된 파일에서 지원하는 구성 항목은 다음과 같습니다.

  • bind_dn
  • password

  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

Kubernetes 시크릿을 사용하여 LDAP 비밀번호를 저장합니다. 자세한 내용은 Helm LDAP 시크릿을 참고합니다.

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running 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 계정에 저장된 DN을 업데이트합니다. 이제 두 값이 모두 LDAP에 저장된 정보와 일치합니다.
    • 이메일 주소로도 사용자를 찾을 수 없으면(DN과 이메일 주소가 모두 변경된 경우) 사용자 DN과 이메일이 변경된 경우를 참고합니다.

익명 LDAP 인증 비활성화#

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

  1. 익명 인증을 비활성화합니다.
  2. 다음 인증 유형 중 하나를 활성화합니다.
    • 단순 인증.
    • SASL(Simple Authentication and Security Layer) 인증.

LDAP 서버의 TLS 클라이언트 인증 설정은 필수로 지정할 수 없으며, 클라이언트를 TLS 프로토콜로 인증해서는 안 됩니다.

LDAP에서 삭제된 사용자#

LDAP 서버에서 삭제된 사용자는 다음과 같이 처리됩니다.

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

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

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

LDAP를 로그인에 사용하는 경우 LDAP 서버의 이메일 주소가 사용자에 대한 단일 진실 공급원(Single Source Of Truth, SSOT)으로 간주됩니다.

사용자 이메일 주소 업데이트는 해당 사용자를 관리하는 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 ID를 제거할 수 있습니다.

  4. 사용자가 계정에 로그인할 수 있는지 확인합니다. 사용자가 로그인할 수 없으면 해당 사용자의 LDAP가 아직 남아 있는지 확인하고, 필요하면 제거합니다. 문제가 계속되면 로그를 확인하여 원인을 파악합니다.

  5. 구성 파일에서 다음을 변경합니다.

    • omniauth_auto_link_user를 saml만 남기도록 변경합니다.
    • omniauth_auto_link_ldap_user를 false로 변경합니다.
    • ldap_enabled를 false로 변경합니다. LDAP 공급자 설정을 주석 처리할 수도 있습니다.

문제 해결#

LDAP 문제 해결에 대한 관리자 가이드를 참고합니다.

GitLab과 LDAP 통합

GitLab v19.4
Tier: Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

GitLab은 LDAP - Lightweight Directory Access Protocol과 통합되어 사용자 인증을 지원합니다. 이 통합은 다음을 포함한 대부분의 LDAP 호환 디렉터리 서버에서 작동합니다. GitLab은 Microsoft Active Directory Trusts를 지원하지 않습니다.

GitLab은 LDAP - Lightweight Directory Access Protocol과 통합되어 사용자 인증을 지원합니다.

이 통합은 다음을 포함한 대부분의 LDAP 호환 디렉터리 서버에서 작동합니다.

  • Microsoft Active Directory.
  • Apple Open Directory.
  • OpenLDAP.
  • 389 Server.
Note

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

LDAP를 통해 추가된 사용자는 다음과 같습니다.

  • 일반적으로 라이선스 시트를 사용합니다.
  • Git에 대한 비밀번호 인증이 비활성화되어 있어도 GitLab 사용자 이름 또는 이메일과 LDAP 비밀번호로 Git에 인증할 수 있습니다.

LDAP 고유 이름(DN)은 다음 경우에 기존 GitLab 사용자와 연결됩니다.

  • 기존 사용자가 LDAP로 GitLab에 처음 로그인하는 경우.
  • LDAP 이메일 주소가 기존 GitLab 사용자의 기본 이메일 주소인 경우. LDAP 이메일 속성이 GitLab 사용자 데이터베이스에 없으면 새 사용자가 생성됩니다.

기존 GitLab 사용자가 스스로 LDAP 로그인을 사용하려면 다음을 수행해야 합니다.

  1. GitLab 이메일 주소가 LDAP 이메일 주소와 일치하는지 확인합니다.
  2. LDAP 자격 증명으로 GitLab에 로그인합니다.
Note

사용자가 LDAP ID를 GitLab 계정에 연결하면 더 이상 표준 사용자 이름과 비밀번호 인증 흐름을 사용할 수 없습니다. 대신 LDAP 자격 증명으로 인증해야 합니다. 사용자 이름과 비밀번호로 로그인을 시도하면 잘못된 로그인 또는 비밀번호 오류가 반환됩니다.

보안#

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

다음 경우 사용자는 LDAP에서 비활성 상태로 간주됩니다.

  • 디렉터리에서 완전히 제거된 경우.
  • 구성된 base DN 또는 user_filter 검색 범위 밖에 있는 경우.
  • 사용자 계정 제어 속성을 통해 Active Directory에서 비활성화(disabled 또는 deactivated)로 표시된 경우. 이는 속성 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 사용자의 상태를 확인합니다.

  • 인증 공급자를 사용해 로그인할 때.
  • 토큰 또는 SSH 키를 사용하는 활성 웹 세션이나 Git 요청에 대해 한 시간에 한 번.
  • LDAP 사용자 이름과 비밀번호로 HTTP를 통한 Git 요청을 수행할 때.
  • 사용자 동기화 중 하루에 한 번.

사용자가 LDAP에서 더 이상 활성 상태가 아니면 다음과 같이 처리됩니다.

  • 로그아웃됩니다.
  • ldap_blocked 상태가 됩니다.
  • LDAP에서 다시 활성화될 때까지 어떤 인증 공급자로도 로그인할 수 없습니다.

보안 위험#

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

  • LDAP 서버에서 mail, email 또는 userPrincipalName 속성을 변경하는 것. 이러한 사용자는 GitLab 서버의 모든 계정을 탈취할 수 있습니다.
  • 이메일 주소를 공유하는 것. 이메일 주소가 같은 LDAP 사용자는 같은 GitLab 계정을 공유할 수 있습니다.

LDAP 구성#

사전 요구 사항:

  • LDAP를 사용하려면 이메일 주소가 있어야 합니다. 그 이메일 주소로 로그인하는지 여부와 관계없습니다.

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

편집하는 파일은 GitLab 설정에 따라 다릅니다.

  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

  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를 구성하는 방법을 참고합니다.

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

다양한 LDAP 옵션에 대한 자세한 내용은 gitlab.yml.example의 ldap 설정을 참고합니다.

LDAP를 구성한 후 구성을 테스트하려면 LDAP check Rake 태스크를 사용합니다.

기본 구성 설정#

다음 기본 설정을 사용할 수 있습니다.

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

- '(employeeType=developer)'
- '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
lowercase_usernames ❌ Boolean 활성화하면 GitLab이 이름을 소문자로 변환합니다.
retry_empty_result_with_codes ❌ Array 결과나 콘텐츠가 비어 있을 때 작업을 재시도할 LDAP 쿼리 응답 코드의 배열입니다. Google Secure LDAP에서는 이 값을 [80]으로 설정합니다.
Note

GitLab은 Microsoft advisory ADV190023에서 도입된 Microsoft Active Directory Services의 더 엄격한 바인딩 요구 사항의 영향을 받지 않습니다. 자세한 내용은 issue 201894를 참고합니다.

SSL 구성 설정#

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

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

다음 예시는 tls_options에서 ca_file과 ssl_version을 설정하는 방법을 보여 줍니다.

  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

  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를 구성하는 방법을 참고합니다.

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

속성 구성 설정#

GitLab은 다음 LDAP 속성을 사용하여 LDAP 사용자의 계정을 생성합니다. 지정하는 속성은 다음 중 하나일 수 있습니다.

  • 문자열 형태의 속성 이름. 예: 'mail'.
  • 순서대로 시도할 속성 이름의 배열. 예: ['mail', 'email'].

사용자의 LDAP 로그인 이름은 uid로 지정한 LDAP 속성입니다.

다음 LDAP 속성은 모두 선택 사항입니다. 기본값과 다른 속성만 지정하면 됩니다. 예를 들어 username을 지정했다면 나머지를 지정할 필요가 없습니다. 나머지에는 기본값이 적용됩니다.

이러한 속성을 정의하는 경우 attributes 해시 안에 정의해야 합니다.

설정 설명 기본값
username GitLab 계정을 프로비저닝할 @username입니다. 값에 이메일 주소가 포함되어 있으면 GitLab 사용자 이름은 이메일 주소에서 @ 앞부분입니다. 기본값은 uid로 지정한 LDAP 속성(['uid', 'userid', 'sAMAccountName'])입니다.
email 사용자 이메일에 대한 LDAP 속성입니다. ['mail', 'email', 'userPrincipalName']
name 사용자 표시 이름에 대한 LDAP 속성입니다. name이 비어 있으면 first_name과 last_name에서 전체 이름을 가져옵니다. 'cn' 또는 'displayName' 속성에 전체 이름이 들어 있는 경우가 많습니다. 또는 'somethingNonExistent'처럼 존재하지 않는 속성을 지정하여 first_name과 last_name을 강제로 사용하게 할 수 있습니다. 'cn'
first_name 사용자 이름(first name)에 대한 LDAP 속성입니다. name에 구성한 속성이 존재하지 않을 때 사용합니다. 'givenName'
last_name 사용자 성(last name)에 대한 LDAP 속성입니다. name에 구성한 속성이 존재하지 않을 때 사용합니다. 'sn'

사용자 이름에 displayName을 사용하고 email에 속성 배열을 사용하는 구성 예시입니다.

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

    gitlab_rails['ldap_servers'] = {
  'main' => {
    # Other configuration settings ...
    'attributes' => {
      'username' => 'uid',
      'email' => ['mail', 'email', 'userPrincipalName'],
      'name' => 'displayName',
      'first_name' => 'givenName',
      'last_name' => 'sn'
    }
  }
}

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

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

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

    global:
  appConfig:
    ldap:
      servers:
        main:
          # Other configuration settings ...
          attributes:
            username: 'uid'
            email:
              - 'mail'
              - 'email'
              - 'userPrincipalName'
            name: 'displayName'
            first_name: 'givenName'
            last_name: 'sn'

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  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' => {
            # Other configuration settings ...
            'attributes' => {
              'username' => 'uid',
              'email' => ['mail', 'email', 'userPrincipalName'],
              'name' => 'displayName',
              'first_name' => 'givenName',
              'last_name' => 'sn'
            }
          }
        }

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

    docker compose up -d

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

    production: &base
  ldap:
    servers:
      main:
        # Other configuration settings ...
        attributes:
          username: 'uid'
          email:
            - 'mail'
            - 'email'
            - 'userPrincipalName'
          name: 'displayName'
          first_name: 'givenName'
          last_name: 'sn'

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 동기화 구성 설정#

다음 LDAP 동기화 구성 설정은 선택 사항입니다. 단, external_groups를 구성하는 경우에는 group_base가 필요합니다.

설정 설명 예시
group_base 그룹을 검색하는 기준 위치입니다. 유효한 모든 그룹의 DN에는 이 기준이 포함됩니다. 'ou=groups,dc=gitlab,dc=example'
group_filter group_base 아래에서 검색할 LDAP 그룹을 필터링합니다. RFC 4515 형식을 따릅니다. '(objectclass=group)'
admin_group GitLab 관리자가 속한 그룹의 CN입니다. cn=administrators나 전체 DN이 아닙니다. 'administrators'
audit_group GitLab 감사자가 속한 그룹의 CN입니다. cn=auditors나 전체 DN이 아닙니다. 'auditors'
external_groups 외부 사용자로 간주할 사용자가 속한 그룹의 CN 배열입니다. cn=interns나 전체 DN이 아닙니다. ['interns', 'contractors']
sync_ssh_keys 사용자의 공개 SSH 키가 들어 있는 LDAP 속성입니다. 'sshPublicKey' 또는 설정하지 않은 경우 false
Note

Sidekiq이 Rails 서버와 다른 서버에 구성되어 있으면 LDAP 동기화가 작동하도록 모든 Sidekiq 서버에도 LDAP 구성을 추가해야 합니다.

여러 LDAP 서버 사용#

여러 LDAP 서버에 사용자가 있는 경우 GitLab이 해당 서버를 사용하도록 구성할 수 있습니다. LDAP 서버를 추가하려면 다음을 수행합니다.

  1. main LDAP 구성을 복제합니다.
  2. 복제한 각 구성을 추가 서버의 세부 정보로 편집합니다.
    • 추가하는 각 서버에는 main, secondary, tertiary처럼 서로 다른 공급자 ID를 지정합니다. 소문자 영숫자를 사용합니다. GitLab은 공급자 ID를 사용하여 각 사용자를 특정 LDAP 서버에 연결합니다.
    • 각 항목에 고유한 label 값을 사용합니다. 이 값은 로그인 페이지의 탭 이름으로 사용됩니다.

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

  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

  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

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

다양한 LDAP 옵션에 대한 자세한 내용은 gitlab.yml.example의 ldap 설정을 참고합니다.

이 예시를 적용하면 로그인 페이지에 다음 탭이 표시됩니다.

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

LDAP 사용자 필터 설정#

GitLab 접근을 LDAP 서버의 일부 LDAP 사용자로 제한하려면 먼저 구성된 base를 좁힙니다. 그런 다음 필요하면 LDAP 사용자 필터를 설정하여 사용자를 추가로 필터링할 수 있습니다. 필터는 RFC 4515를 준수해야 합니다.

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

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

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

    sudo gitlab-ctl reconfigure

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running 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 필터에 대한 자세한 내용은 Search Filter Syntax를 참고합니다.

사용자 필터의 중첩 멤버 지원을 그룹 동기화 중첩 그룹 지원과 혼동하지 않아야 합니다.

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 서버는 구성에 따라 대문자 사용자 이름을 반환할 수 있습니다. 이로 인해 대문자 이름으로 링크나 네임스페이스가 생성되는 등 여러 혼란스러운 문제가 발생할 수 있습니다.

구성 옵션 lowercase_usernames를 활성화하면 GitLab이 LDAP 서버에서 제공한 사용자 이름을 자동으로 소문자로 변환합니다. 이 구성 옵션의 기본값은 false입니다.

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

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

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

    sudo gitlab-ctl reconfigure

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 웹 로그인 비활성화#

SAML 같은 대안을 사용하려는 경우 웹 UI에서 LDAP 자격 증명 사용을 막는 것이 유용할 수 있습니다. 이렇게 하면 LDAP를 그룹 동기화에 사용하면서 SAML ID 공급자가 사용자 지정 2FA 같은 추가 검사를 처리하도록 할 수도 있습니다. 이 경우 LDAP는 그룹 동기화에만 사용됩니다.

LDAP 웹 로그인을 비활성화하면 사용자에게 로그인 페이지에 LDAP 탭이 표시되지 않습니다. 이 설정은 Git 접근에 LDAP 자격 증명을 사용하는 것을 비활성화하지 않습니다.

LDAP 웹 로그인을 비활성화해도 이러한 사용자가 웹 UI에서 차단되지는 않습니다. GitLab 비밀번호로 계속 로그인할 수 있습니다. ID 공급자를 통한 로그인만 요구하려면 다음도 함께 수행합니다. SSO ID가 있는 사용자의 비밀번호 및 패스키 인증 비활성화.

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

    gitlab_rails['prevent_ldap_sign_in'] = true

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

    sudo gitlab-ctl reconfigure

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

GitLab에 스마트 카드 인증 제공#

LDAP 서버 및 GitLab에서 스마트 카드를 사용하는 방법에 대한 자세한 내용은 스마트 카드 인증을 참고합니다.

암호화된 자격 증명 사용#

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

사전 요구 사항:

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

LDAP의 암호화된 구성은 암호화된 YAML 파일에 있습니다. 파일의 암호화되지 않은 내용은 LDAP 구성의 servers 블록에 있는 시크릿 설정의 부분 집합이어야 합니다.

암호화된 파일에서 지원하는 구성 항목은 다음과 같습니다.

  • bind_dn
  • password

  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

Kubernetes 시크릿을 사용하여 LDAP 비밀번호를 저장합니다. 자세한 내용은 Helm LDAP 시크릿을 참고합니다.

  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

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

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running 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 계정에 저장된 DN을 업데이트합니다. 이제 두 값이 모두 LDAP에 저장된 정보와 일치합니다.
    • 이메일 주소로도 사용자를 찾을 수 없으면(DN과 이메일 주소가 모두 변경된 경우) 사용자 DN과 이메일이 변경된 경우를 참고합니다.

익명 LDAP 인증 비활성화#

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

  1. 익명 인증을 비활성화합니다.
  2. 다음 인증 유형 중 하나를 활성화합니다.
    • 단순 인증.
    • SASL(Simple Authentication and Security Layer) 인증.

LDAP 서버의 TLS 클라이언트 인증 설정은 필수로 지정할 수 없으며, 클라이언트를 TLS 프로토콜로 인증해서는 안 됩니다.

LDAP에서 삭제된 사용자#

LDAP 서버에서 삭제된 사용자는 다음과 같이 처리됩니다.

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

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

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

LDAP를 로그인에 사용하는 경우 LDAP 서버의 이메일 주소가 사용자에 대한 단일 진실 공급원(Single Source Of Truth, SSOT)으로 간주됩니다.

사용자 이메일 주소 업데이트는 해당 사용자를 관리하는 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 ID를 제거할 수 있습니다.

  4. 사용자가 계정에 로그인할 수 있는지 확인합니다. 사용자가 로그인할 수 없으면 해당 사용자의 LDAP가 아직 남아 있는지 확인하고, 필요하면 제거합니다. 문제가 계속되면 로그를 확인하여 원인을 파악합니다.

  5. 구성 파일에서 다음을 변경합니다.

    • omniauth_auto_link_user를 saml만 남기도록 변경합니다.
    • omniauth_auto_link_ldap_user를 false로 변경합니다.
    • ldap_enabled를 false로 변경합니다. LDAP 공급자 설정을 주석 처리할 수도 있습니다.

문제 해결#

LDAP 문제 해결에 대한 관리자 가이드를 참고합니다.