LDAP 동기화

Tier: 프리미엄, 얼티메이트 Offering: Self-managed

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

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

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

속도 제한이 있는 LDAP 서버

일부 LDAP 서버에는 속도 제한이 구성되어 있습니다.

GitLab은 다음을 위해 LDAP 서버에서 한 번씩 쿼리합니다:

사용자 동기화 작업 중에 사용자.
예정된 그룹 동기화 작업 중에 그룹.

일부 경우에는 LDAP 서버에 대해 더 많은 쿼리가 트리거될 수 있습니다. 예를 들어, 그룹 동기화 쿼리가 memberuid 속성을 반환할 때입니다.

LDAP 서버에 속도 제한이 구성되어 있고 해당 제한이 다음 중에서 발생할 때:

사용자 동기화 작업 시, LDAP 서버는 오류 코드로 응답하고 GitLab은 해당 사용자를 차단합니다.
그룹 동기화 작업 시, LDAP 서버는 오류 코드로 응답하고 GitLab은 해당 사용자의 그룹 멤버십을 제거합니다.

LDAP 동기화를 구성할 때 LDAP 서버의 속도 제한을 고려하여 원치 않는 사용자 차단 및 그룹 멤버십 제거를 방지해야 합니다.

사용자 동기화

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

하루에 한 번씩, GitLab은 LDAP에 대해 사용자를 확인하고 업데이트하는 워커를 실행합니다.

이 프로세스는 다음 액세스 확인을 실행합니다:

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

Active Directory에서 사용자는 비활성화/차단 상태로 표시되며 매개변수 2가 설정된 경우 사용자 계정 제어 속성(userAccountControl:1.2.840.113556.1.4.803)이 있습니다.

더 많은 정보는 LDAP에서 Bitmask 검색을 참조하십시오.

이 프로세스는 또한 다음 사용자 정보를 업데이트합니다:

이름. 동기화 문제 때문에, name이 활성화되어 있거나 sync_name이 false로 설정된 경우 사용자 프로필 이름 변경 금지이 가능하게 됩니다.
이메일 주소.
sync_ssh_keys가 설정된 경우 SSH 공개 키.
Kerberos가 활성화된 경우 Kerberos 식별.

참고: 만약 LDAP 서버가 속도 제한을 가지고 있다면, 해당 제한이 사용자 동기화 작업 중에 달성될 수 있습니다. 자세한 내용은 속도 제한 문서를 확인하십시오.

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

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

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

Linux 패키지 (Omnibus)

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

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

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

Helm 차트 (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
```

직접 컴파일 (소스)

/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가 memberof 속성을 지원한다면, 사용자가 처음으로 로그인할 때 GitLab은 사용자가 속할 그룹을 동기화합니다. 이렇게 하면 그들은 그룹과 프로젝트에 액세스를 얻기 위해 매시간 동기화를 기다릴 필요가 없게 됩니다.

그룹 동기화 작업은 매 시간 정각에 실행되며, 그룹 동기화 작업이 그룹 CN을 기반으로 하는 LDAP 동기화를 기반으로 할 경우 LDAP 구성에서 group_base가 설정되어 있어야 합니다. 이는 LDAP 그룹 멤버에 기초하여 GitLab 그룹 멤버십을 자동으로 업데이트할 수 있게 합니다.

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

참고: 만약 LDAP 서버가 속도 제한을 가지고 있다면, 해당 제한이 그룹 동기화 작업 중에 달성될 수 있습니다. 자세한 내용은 속도 제한 문서를 확인하십시오.

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

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

참고: LDAP 서버와 GitLab 인스턴스 간의 연결 문제가 빈번하게 발생하는 경우, GitLab에서 LDAP 그룹 동기화 작업 간격을 조정하여 기본 1시간보다 큰 간격으로 설정해보세요.

그룹 링크 추가

CNs 및 필터를 사용하여 그룹 링크를 추가하는 정보는 GitLab 그룹 문서를 참조하세요.

관리자 동기화

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

참고: group_base가 admin_group와 함께 지정되지 않으면 관리자가 동기화되지 않습니다. 또한, 전체 DN 대신 admin_group의 CN만 지정하세요. 추가로, LDAP 사용자가 admin 역할을 가지고 있지만 admin_group 그룹의 멤버가 아닌 경우 GitLab은 그들의 admin 역할을 동기화할 때 취소합니다.

Linux package (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 chart (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
```

Self-compiled (source)

/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 관리자는 그룹 멤버십이 LDAP와 동기화된 하위 그룹으로 새 멤버를 초대하는 것을 방지할 수 있습니다.

글로벌 그룹 멤버십 잠금은 구성된 LDAP 동기화를 가진 최상위 그룹의 하위 그룹에만 적용됩니다. 어떤 사용자도 LDAP 동기화가 구성된 최상위 그룹의 멤버십을 수정할 수 없습니다.

글로벌 그룹 멤버십 잠금이 활성화된 경우:

관리자만 모든 그룹의 멤버십을 관리할 수 있습니다. (접근 수준 포함)
사용자는 프로젝트를 다른 그룹과 공유하거나 그룹에서 생성한 프로젝트에 멤버를 초대할 수 없습니다.

글로벌 그룹 멤버십 잠금을 활성화하려면:

LDAP 구성을 수행하세요.
왼쪽 사이드바에서 아래쪽으로 이동하여 Admin을 선택하세요.
Settings > General을 선택하세요.
Visibility and access controls를 확장하세요.
Lock memberships to LDAP synchronization 확인란이 선택되었는지 확인하세요.

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

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

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

LDAP 구성을 수행하세요.
왼쪽 사이드바에서 아래쪽으로 이동하여 Admin을 선택하세요.
Settings > General을 선택하세요.
Visibility and access controls를 확장하세요.
Allow group owners to manage LDAP-related settings 확인란이 선택되지 않았는지 확인하세요.

Allow group owners to manage LDAP-related settings가 비활성화된 경우:

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

외부 그룹

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
```

Self-compiled (source)

/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 그룹 멤버십이 변경되면 더 높은 수준에서 하향 조정됩니다. 예를 들어, 사용자가 그룹에서 소유자 역할과 다음 그룹 동기화에서 개발자 역할만 가져야 한다고 판명되면 해당 사용자의 액세스는 그에 맞게 조정됩니다. 사용자가 그룹의 마지막 소유자인 경우에만 예외입니다. 관리 업무를 수행하기 위해 그룹에는 적어도 하나의 소유자가 필요합니다.

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

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

member
submember
uniquemember
memberof
memberuid

이는 그룹 동기화가 다음과 같은 객체 클래스를 사용하는 LDAP 그룹을 지원한다는 것을 의미합니다(적어도):

groupOfNames
posixGroup
groupOfUniqueNames

기타 객체 클래스는 언급된 속성 중 하나로 정의된 경우에도 작동할 수 있습니다.

Active Directory는 중첩 그룹을 지원합니다. 구성 파일에서 active_directory: true로 설정된 경우, 그룹 동기화는 멤버십을 재귀적으로 해결합니다.

중첩 그룹 멤버십

중첩 그룹 멤버십은 구성된 group_base에서 중첩 그룹이 발견될 때에만 해결됩니다. 예를 들어, GitLab이 cn=nested_group,ou=special_groups,dc=example,dc=com과 같은 중첩 그룹을 보지만 구성된 group_base가 ou=groups,dc=example,dc=com인 경우, cn=nested_group은 무시됩니다.

쿼리

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

벤치마크

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

20,000개의 LDAP 사용자, 11,000개의 LDAP 그룹, 1,000개의 GitLab 그룹(각각 10개의 LDAP 그룹 링크 포함):

초기 동기화(기존 구성원이 GitLab에 할당되지 않은 경우)에는 1.8시간이 소요되었습니다.
후속 동기화(멤버십 확인, 쓰기 없음)에는 15분이 소요되었습니다.

이러한 메트릭은 기준을 제공하는 목적으로, 성능은 여러 요소에 따라 달라질 수 있습니다. 이 벤치마크는 극단적인 경우이며 대부분의 인스턴스는 이보다 훨씬 적은 사용자 또는 그룹을 보유하고 있습니다. 디스크 속도, 데이터베이스 성능, 네트워크 및 LDAP 서버 응답 시간이 이러한 메트릭에 영향을 줄 수 있습니다.

LDAP 사용자 동기화 일정 조정

기본적으로 GitLab은 서버 시간 01:30 a.m.에 매일 한 번 작업자를 실행하여 LDAP에 대한 GitLab 사용자를 확인하고 업데이트합니다.

경고: 동기화 프로세스를 너무 자주 실행하지 마십시오. 이렇게 하면 복수의 동기화가 동시에 실행될 수 있습니다. 대부분의 설치에서는 동기화 일정을 수정할 필요가 없습니다. 자세한 내용은 LDAP 보안 문서를 참조하십시오.

아래 구성 값을 설정하여 필요에 따라 수동으로 LDAP 사용자 동기화 시간을 구성할 수 있습니다. crontab generator를 사용할 수 있습니다. 아래 예는 매 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 값(Values)을 내보냅니다:

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 그룹 동기화 일정 조정

기본적으로 GitLab은 매시 정각마다 1시간마다 그룹 동기화 프로세스를 실행합니다. 표시된 값은 크론 형식으로 나타납니다. 필요한 경우 Crontab Generator를 사용할 수 있습니다.

경고: 동기화 프로세스를 너무 자주 시작하지 마십시오. 이렇게 하면 복수의 동기화가 동시에 실행될 수 있습니다. 대부분의 설치에서는 동기화 일정을 수정할 필요가 없습니다.

아래 구성 값을 설정하여 필요에 따라 수동으로 LDAP 그룹 동기화 시간을 구성할 수 있습니다. 아래 예는 매 2시간마다 한 번씩 그룹 동기화를 실행하도록 구성하는 방법을 보여줍니다.

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 값(Values)을 내보냅니다:

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
```

Self-compiled (source)

/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

문제 해결

LDAP 문제 해결에 대한 관리자 가이드를 참조하십시오.

LDAP 동기화

속도 제한이 있는 LDAP 서버

사용자 동기화

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

차단된 사용자

그룹 동기화

그룹 링크 추가

관리자 동기화

글로벌 그룹 멤버십 잠금

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

외부 그룹

그룹 동기화 기술 세부 정보

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

중첩 그룹 멤버십

쿼리

벤치마크

LDAP 사용자 동기화 일정 조정

LDAP 그룹 동기화 일정 조정

문제 해결

도움말

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

도움받기