LDAP 동기화

Tier: Premium, Ultimate Offering: Self-managed

만약 GitLab과 함께 LDAP를 구성했다면, GitLab은 사용자와 그룹을 자동으로 동기화할 수 있습니다.

LDAP 동기화는 LDAP 신원이 할당된 기존 GitLab 사용자의 사용자 및 그룹 정보를 업데이트합니다. 이는 LDAP를 통해 새로운 GitLab 사용자를 생성하지는 않습니다.

동기화가 발생하는 시기를 변경할 수 있습니다.

사용자 동기화

GitLab 15.11에서 도입된 LDAP 사용자 프로필 이름 동기화 방지.

하루에 한 번, GitLab은 작업자를 실행하여 LDAP와 비교하여 GitLab 사용자를 확인하고 업데이트합니다.

이 과정에서 다음과 같은 접근 확인을 실행합니다:

사용자가 LDAP에 여전히 존재하는지 확인합니다.
LDAP 서버가 Active Directory인 경우, 사용자가 활성 상태인지 확인합니다(차단/비활성 상태가 아닌지). 이 확인은 LDAP 구성에서 active_directory: true로 설정된 경우에만 수행됩니다.

Active Directory에서 사용자는 userAccountControl 속성(userAccountControl:1.2.840.113556.1.4.803)에 비트 2가 설정된 경우에 차단/비활성 상태로 표시됩니다.

더 많은 정보는 LDAP에서 비트마스크 검색을 참조하세요.

이 과정은 또한 다음 사용자 정보를 업데이트합니다:

이름. 동기화 문제로 인해 name이 동기화되지 않습니다 사용자 프로필 이름 변경 방지이 활성화되어 있거나 sync_name이 false로 설정된 경우입니다.
이메일 주소.
sync_ssh_keys가 설정된 경우 SSH 공개 키.
Kerberos가 활성화된 경우 Kerberos 신원.

LDAP 사용자 프로필 이름 동기화

기본적으로 GitLab은 LDAP 사용자의 프로필 이름 필드를 동기화합니다.

이 동기화를 방지하려면 sync_name을 false로 설정할 수 있습니다.

Linux package (Omnibus)

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

gitlab_rails['ldap_servers'] = {
  'main' => {
    'sync_name' => false,
    }
}

파일을 저장한 뒤 GitLab을 다시 구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm chart (Kubernetes)

Helm 값들을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

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

global:
  appConfig:
    ldap:
      servers:
        main:
          sync_name: false

파일을 저장한 뒤 새 값들을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

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

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'sync_name' => false,
            }
        }

파일을 저장한 뒤 GitLab을 다시 시작합니다:
```
docker compose up -d
```

Self-compiled (source)

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

production: &base
  ldap:
    servers:
      main:
        sync_name: false

파일을 저장한 뒤 GitLab을 다시 시작합니다:

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

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

차단된 사용자

사용자가 차단된 경우:

접근 확인에 실패하고 해당 사용자가 GitLab에서 ldap_blocked 상태로 설정된 경우.
사용자가 로그인할 때 LDAP 서버를 사용할 수 없는 경우.

사용자가 차단된 경우, 해당 사용자는 로그인하거나 코드를 푸시하거나 끌 수 없습니다.

LDAP 사용자 동기화가 실행될 때 LDAP 서버가 사용할 수 없는 경우, 모든 사용자가 차단됩니다.

차단된 사용자들이 LDAP 사용자 동기화 실행 시 LDAP 서버가 사용할 수 없는 경우, 후속 LDAP 사용자 동기화로 이러한 사용자들이 자동으로 차단 해제되지 않습니다.

LDAP 사용자 동기화 일정 조정

기본적으로 GitLab은 매일 새벽 01:30에 한 번씩 작업자를 실행하여 LDAP를 통해 GitLab 사용자를 확인하고 업데이트합니다.

다음 구성 값들을 cron 형식으로 설정하여 필요한 경우 LDAP 사용자 동기화 시간을 수동으로 구성할 수 있습니다. 필요한 경우 crontab 생성기를 사용할 수 있습니다. 아래 예제는 매 12시간마다 맨 위 시간에 LDAP 사용자 동기화를 실행하는 방법을 보여줍니다.

Linux package (Omnibus)

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

gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"

파일을 저장한 뒤 GitLab을 다시 구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm chart (Kubernetes)

Helm 값들을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

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

global:
  appConfig:
    cron_jobs:
      ldap_sync_worker:
        cron: "0 */12 * * *"

파일을 저장한 뒤 새 값들을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

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

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"

파일을 저장한 뒤 GitLab을 다시 시작합니다:
```
docker compose up -d
```

Self-compiled (source)

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

production: &base
  ee_cron_jobs:
    ldap_sync_worker:
      cron: "0 */12 * * *"

파일을 저장한 뒤 GitLab을 다시 시작합니다:

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

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

그룹 동기화

만약 LDAP가 memberof 속성을 지원한다면, 사용자가 처음으로 로그인할 때 GitLab은 사용자가 소속되어 있어야 할 그룹들에 대한 동기화를 트리거합니다. 이렇게 하면 시간별 동기화를 기다릴 필요 없이 바로 그룹 및 프로젝트에 액세스를 얻을 수 있습니다.

그룹 동기화 프로세스는 매 시간 정각에 실행되며, LDAP 그룹 CN을 기반으로 한 LDAP 동기화를 위해 LDAP 구성에서 group_base가 설정되어야 합니다. 이를 통해 LDAP 그룹 구성원에 기반하여 GitLab 그룹 멤버십이 자동으로 업데이트됩니다.

group_base 구성은 GitLab에서 사용 가능해야 할 LDAP 그룹을 포함하는 기본 LDAP ‘컨테이너’여야 합니다. 예를 들어, group_base는 ou=groups,dc=example,dc=com일 수 있습니다. 구성 파일에서는 다음과 같이 보입니다.

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일 편집:

gitlab_rails['ldap_servers'] = {
  'main' => {
    'group_base' => 'ou=groups,dc=example,dc=com',
    }
}

파일 저장 및 GitLab 재구성:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

Helm 값 내보내기:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 편집:

global:
  appConfig:
    ldap:
      servers:
        main:
          group_base: ou=groups,dc=example,dc=com

파일 저장 및 새 값 적용:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml 편집:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'group_base' => 'ou=groups,dc=example,dc=com',
            }
        }

파일 저장 및 GitLab 재시작:
```
docker compose up -d
```

소스로 직접 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml 파일 편집:

production: &base
  ldap:
    servers:
      main:
        group_base: ou=groups,dc=example,dc=com

파일 저장 및 GitLab 재시작:

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

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

그룹 동기화를 활용하려면 그룹 소유자 또는 관리자 역할을 가진 사용자가 하나 이상의 LDAP 그룹 링크를 생성해야 합니다.

그룹 링크 추가

CN 및 필터를 사용하여 그룹 링크를 추가하는 정보는 GitLab 그룹 설명서를 참조하십시오.

관리자 동기화

그룹 동기화의 확장으로, 전역 GitLab 관리자를 자동으로 관리할 수 있습니다. admin_group에 대한 그룹 CN을 지정하면 해당 LDAP 그룹의 모든 구성원에게 관리자 권한이 부여됩니다. 구성은 다음과 같습니다.

참고: admin_group과 함꼐 group_base도 명시되지 않으면 관리자들은 동기화되지 않습니다. 또한 전체 DN 대신 admin_group의 CN만 지정해야 합니다. 또한, LDAP 사용자가 admin 역할을 가지고 있지만 admin_group 그룹의 구성원이 아닌 경우, GitLab은 동기화시 해당 사용자의 admin 역할을 취소합니다.

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일 편집:

gitlab_rails['ldap_servers'] = {
  'main' => {
    'group_base' => 'ou=groups,dc=example,dc=com',
    'admin_group' => 'my_admin_group',
    }
}

파일 저장 및 GitLab 재구성:
```
sudo gitlab-ctl reconfigure
```

Helm 차트 (Kubernetes)

Helm 값 내보내기:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 편집:

global:
  appConfig:
    ldap:
      servers:
        main:
          group_base: ou=groups,dc=example,dc=com
          admin_group: my_admin_group

파일 저장 및 새 값 적용:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

docker-compose.yml 편집:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'group_base' => 'ou=groups,dc=example,dc=com',
            'admin_group' => 'my_admin_group',
            }
        }

파일 저장 및 GitLab 재시작:
```
docker compose up -d
```

소스로 직접 컴파일 (소스)

/home/git/gitlab/config/gitlab.yml 파일 편집:

production: &base
  ldap:
    servers:
      main:
        group_base: ou=groups,dc=example,dc=com
        admin_group: my_admin_group

파일 저장 및 GitLab 재시작:

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

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

전역 그룹 멤버십 잠금

GitLab 12.0에 도입되었습니다.

GitLab 관리자는 멤버십이 LDAP과 동기화된 하위 그룹에 새 멤버를 초대하는 것을 방지할 수 있습니다.

전역 그룹 멤버십 잠금은 LDAP 동기화가 구성된 최상위 그룹의 하위 그룹에만 적용됩니다. 사용자는 LDAP 동기화가 구성된 최상위 그룹의 멤버십을 수정할 수 없습니다.

전역 그룹 멤버십 잠금이 활성화된 경우:

관리자만 모든 그룹의 멤버십 및 액세스 수준을 관리할 수 있습니다.
사용자는 프로젝트를 다른 그룹과 공유하거나 그룹에서 생성된 프로젝트에 멤버를 초대할 수 없습니다.

전역 그룹 멤버십 잠금을 활성화하려면:

LDAP 구성합니다.
왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
설정 > 일반을 선택합니다.
가시성 및 액세스 제어를 확장합니다.
LDAP 동기화로 멤버십 잠금 확인란을 선택합니다.

LDAP 그룹 동기화 설정 관리 변경

기본적으로 소유자 역할이 있는 그룹 멤버는 LDAP 그룹 동기화 설정을 관리할 수 있습니다.

GitLab 관리자는 그룹 소유자로부터 이 권한을 제거할 수 있습니다:

LDAP 구성합니다.
왼쪽 사이드바에서 가장 아래에서 관리 영역을 선택합니다.
설정 > 일반을 선택합니다.
가시성 및 액세스 제어를 확장합니다.
그룹 소유자가 LDAP 관련 설정을 관리할 수 있음 확인란이 선택되어 있지 않은지 확인합니다.

그룹 소유자가 LDAP 관련 설정을 관리할 수 있음이 비활성화된 경우:

그룹 소유자는 최상위 그룹 및 하위 그룹에 대한 LDAP 동기화 설정을 변경할 수 없습니다.
인스턴스 관리자는 인스턴스의 모든 그룹에서 LDAP 그룹 동기화 설정을 관리할 수 있습니다.

LDAP 그룹 동기화 일정 조정

기본적으로 GitLab은 매 시간 정각에 그룹 동기화 프로세스를 실행합니다. 표시된 값은 cron 형식으로 표시됩니다. 필요한 경우 크론 생성기를 사용할 수 있습니다.

경고: 동시에 여러 번 동기화 프로세스가 실행되면 문제가 발생할 수 있으므로 동기화 프로세스를 너무 자주 시작하지 마십시오. 이 문제는 특히 많은 수의 LDAP 사용자가 있는 설치에 대해 주로 적용됩니다. 계속 진행하기 전에 LDAP 그룹 동기화 벤치마킹 메트릭을 확인하여 설치가 어떻게 비교되는지 확인하세요.

다음 구성 값을 설정하여 수동으로 LDAP 그룹 동기화 시간을 구성할 수 있습니다. 아래 예제는 매 두 시간마다 정각에 그룹 동기화가 실행되도록 그룹 동기화를 설정하는 방법을 보여줍니다.

Linux package (Omnibus)

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

gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *"

파일을 저장하고 GitLab을 다시 구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm chart (Kubernetes)

Helm 값 내보내기:

helm get values gitlab > gitlab_values.yaml

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

global:
  appConfig:
    cron_jobs:
      ldap_group_sync_worker:
        cron: "*/30 * * * *"

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

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

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

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *"

파일을 저장하고 GitLab을 다시 시작합니다:
```
docker compose up -d
```

직접 컴파일 (소스)

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

production: &base
  ee_cron_jobs:
    ldap_group_sync_worker:
      cron: "*/30 * * * *"

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

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

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

외부 그룹

external_groups 설정을 사용하면 해당 그룹에 속한 모든 사용자를 외부 사용자로 표시할 수 있습니다. 그룹 멤버십은 LdapGroupSync 백그라운드 작업을 통해 주기적으로 확인됩니다.

Linux package (Omnibus)

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

gitlab_rails['ldap_servers'] = {
  'main' => {
    'external_groups' => ['interns', 'contractors'],
    }
}

파일을 저장하고 GitLab을 다시 구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm chart (Kubernetes)

Helm 값 내보내기:

helm get values gitlab > gitlab_values.yaml

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

global:
  appConfig:
    ldap:
      servers:
        main:
          external_groups: ['interns', 'contractors']

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

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Docker

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

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'external_groups' => ['interns', 'contractors'],
          }
        }

파일을 저장하고 GitLab을 다시 시작합니다:
```
docker compose up -d
```

직접 컴파일 (소스)

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

production: &base
  ldap:
    servers:
      main:
        external_groups: ['interns', 'contractors']

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

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

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

그룹 동기화 기술 상세

이 섹션에서는 어떤 LDAP 쿼리가 실행되는지와 그룹 동기화에서 기대할 수 있는 동작에 대해 개요합니다.

그룹 구성원의 액세스는 LDAP 그룹 멤버십이 변경되면 더 높은 수준에서 하향 조정됩니다. 예를 들어 사용자가 그룹에서 Owner 역할을 하고 있지만 다음 그룹 동기화에서 Developer 역할만 맡아야 한다고 판명되면 그에 맞게 액세스가 조정됩니다. 단, 사용자가 그룹에서 마지막 소유자인 경우에는 예외입니다. 그룹에는 관리 업무를 수행할 최소한 하나의 소유자가 있어야 합니다.

지원되는 LDAP 그룹 유형/속성

GitLab은 멤버 속성을 사용하는 LDAP 그룹을 지원합니다.

member
submember
uniquemember
memberof
memberuid

이는 그룹 동기화가 다음과 같은 객체 클래스를 사용하는 LDAP 그룹을 지원함을 의미합니다.

groupOfNames
posixGroup
groupOfUniqueNames

기타 객체 클래스는 언급된 속성 중 하나로 정의된 경우에 작동해야 합니다.

Active Directory는 중첩 그룹을 지원합니다. 그룹 동기화는 설정 파일에서 active_directory: true로 설정되어 있으면 멤버십을 재귀적으로 해결합니다.

중첩 그룹 멤버십

중첩 그룹 멤버십은 구성된 group_base에서 중첩 그룹을 발견한 경우에만 해결됩니다. 예를 들어 GitLab이 구성된 group_base가 ou=groups,dc=example,dc=com이지만 cn=nested_group,ou=special_groups,dc=example,dc=com와 같은 DN을 갖는 중첩 그룹을 발견하면 cn=nested_group은 무시됩니다.

쿼리

각 LDAP 그룹은 group_base와 필터 (cn=<cn_from_group_link>)를 사용하여 최대 한 번 쿼리됩니다.
LDAP 그룹에 memberuid 속성이 있는 경우, GitLab은 각 사용자의 전체 DN을 얻기 위해 각 멤버 당 추가 LDAP 쿼리를 실행합니다. 이러한 쿼리는 base를 기준으로 하며, ‘base object’를 범위로 하고, user_filter가 설정되어 있는지에 따라 필터가 (uid=<uid_from_group>) 또는 user_filter의 결합일 수 있습니다.

벤치마크

그룹 동기화는 가능한 성능이 좋도록 작성되었습니다. 데이터는 캐시되고, 데이터베이스 쿼리는 최적화되었으며, LDAP 쿼리는 최소화되었습니다. 마지막 벤치마크 실행에서 다음과 같은 지표가 나타났습니다.

20,000개의 LDAP 사용자, 11,000개의 LDAP 그룹, 그리고 각각 10개의 LDAP 그룹 링크가 있는 1,000개의 GitLab 그룹의 경우:

초기 동기화(지정된 회원이 GitLab에 할당되지 않은 상태)에는 1.8시간이 소요되었습니다.
이후의 동기화(멤버십 확인, 쓰기 없음)에는 15분이 소요되었습니다.

이러한 지표는 기준을 제공하기 위한 것이며, 성능은 다양한 요소에 따라 달라질 수 있습니다. 이 벤치마크는 극단적이며 대부분의 인스턴스는 이보다 훨씬 적은 사용자나 그룹을 보유하고 있습니다. 디스크 속도, 데이터베이스 성능, 네트워크 및 LDAP 서버 응답 시간은 이러한 지표에 영향을 미칩니다.

문제 해결

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

LDAP 동기화

사용자 동기화

LDAP 사용자 프로필 이름 동기화

차단된 사용자

LDAP 사용자 동기화 일정 조정

그룹 동기화

그룹 링크 추가

관리자 동기화

전역 그룹 멤버십 잠금

LDAP 그룹 동기화 설정 관리 변경

LDAP 그룹 동기화 일정 조정

외부 그룹

그룹 동기화 기술 상세

지원되는 LDAP 그룹 유형/속성

중첩 그룹 멤버십

쿼리

벤치마크

문제 해결

도움말

기능 사용 가능성과 제품 평가판

도움받기