LDAP 동기화

Tier: Premium, Ultimate Offering: Self-Managed

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

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

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

사용자 동기화

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

매일 한 번씩, GitLab은 작업자를 실행하여 LDAP에 대해 GitLab 사용자를 확인하고 업데이트합니다.

다음의 액세스 확인을 실행합니다:

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

Active Directory에서 사용자 계정은 비활성/차단 상태로 표시되며 사용자 계정 제어 속성 (userAccountControl:1.2.840.113556.1.4.803)이 2 비트로 설정된 경우입니다.

LDAP에서 비트마스크 검색에 대해 자세한 내용은 LDAP에서 비트마스크 검색을 참조하세요.

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

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

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-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 서버가 사용 가능한 경우.

만약 LDAP 사용자 동기화 실행 시 LDAP 서버가 사용할 수 없는 경우, 모든 사용자가 차단된 채로 남아있게 되며, 이후의 LDAP 사용자 동기화는 이러한 사용자를 자동으로 차단 해제하지 않습니다.

LDAP 사용자 동기화 일정 조정

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

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

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 편집:

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

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

Helm 차트 (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-compose.yml 편집:

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

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

자체 컴파일(소스)

/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은 사용자가 속해야 할 그룹에 대해 동기화를 트리거합니다. 이렇게 하면 그들이 그룹 및 프로젝트에 액세스 권한을 기다릴 필요가 없습니다.

그룹 동기화 프로세스는 매 시간 정각에 실행되며, group_base가 설정되어야 합니다. 이는 LDAP 그룹 CN을 기반으로 하는 LDAP 동기화의 경우 GitLab 그룹 구성원을 자동으로 업데이트할 수 있도록 합니다.

group_base 구성은 LDAP 그룹이 GitLab에서 사용할 수 있어야 하는 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-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 그룹 링크를 생성해야 합니다.

LDAP 서버와 GitLab 인스턴스 간의 연결 문제를 자주 겪는 경우, GitLab이 LDAP 그룹 동기화를 1시간 이상 실행하지 않도록 그룹 동기화 작업자 간격 설정을 수정하여 시도해 보세요.

그룹 링크 추가

CN 및 필터를 사용하여 그룹 링크를 추가하는 방법에 대한 정보는 GitLab 그룹 문서를 참조하세요.

관리자 동기화

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

group_base가 지정되지 않은 경우 관리자는 동기화되지 않습니다. 또한 admin_group의 전체 DN이 아닌 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 관리자는 LDAP와 동기화된 하위 그룹의 멤버가 새로운 멤버를 초대하는 것을 방지할 수 있습니다.

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

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

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

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

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

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

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

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

LDAP 구성을 수행하세요.
왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택하세요.
설정 > 일반을 선택하세요.
가시성 및 액세스 제어를 확장하세요.
그룹 소유자에게 LDAP 관련 설정을 관리할 수 있는 권한 부여 확인란을 선택하지 않았는지 확인하세요.

그룹 소유자가 LDAP 관련 설정을 관리할 수 있는 권한을 부여하지 않았을 경우:

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

LDAP 그룹 동기화 일정 조정

기본적으로 GitLab은 매 시간마다 그룹 동기화 프로세스를 실행합니다. 표시된 값은 cron 형식으로 제공됩니다. 필요한 경우, Crontab Generator를 사용할 수 있습니다.

동기화 프로세스를 너무 자주 시작하지 마십시오. 이렇게 하면 여러 동기화가 동시에 실행될 수 있습니다. 이건 주로 많은 수의 LDAP 사용자가 있는 설치에 대한 고려입니다. 계속 진행하기 전에 LDAP 그룹 동기화 벤치마크 메트릭을 확인하여 설치가 어떻게 비교되는지 확인하십시오.

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

Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집하세요:

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

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

Helm 차트 (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 패키지 (Omnibus)

/etc/gitlab/gitlab.rb 파일을 편집하세요:

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

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

Helm 차트 (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( Lightweight Directory Access Protocol) 쿼리와 그룹 동기화로 예상되는 동작에 대해 개요합니다.

그룹 멤버 액세스는 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 DN을 가진 중첩 그룹을 본다 하더라도 구성된 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로 실행되며, ‘베이스 객체’로 범위가 설정되고, 사용자 필터가 설정되었는지에 따라 필터가 (uid=<uid_from_group>) 또는 user_filter의 결합일 수 있습니다.

벤치마크

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

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

초기 동기화(기존 멤버 할당 없음)에는 1.8시간이 걸렸습니다.
후속 동기화(멤버십 확인, 쓰기 없음)에는 15분이 걸렸습니다.

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

문제 해결

LDAP( Lightweight Directory Access Protocol) 문제 해결에 대한 관리자 가이드를 확인하십시오.여기를 눌러주세요.

LDAP 동기화

사용자 동기화

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

차단된 사용자

LDAP 사용자 동기화 일정 조정

그룹 동기화

그룹 링크 추가

관리자 동기화

전역 그룹 멤버십 잠금

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

LDAP 그룹 동기화 일정 조정

외부 그룹

그룹 동기화 기술 세부 정보

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

중첩 그룹 멤버십

쿼리

벤치마크

문제 해결

도움말

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

도움받기