LDAP 동기화

Tier: Premium, Ultimate Offering: Self-managed

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

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

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

사용자 동기화

LDAP 사용자 프로필 이름 동기화 방지는 GitLab 15.11에 도입되었습니다.

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

이 프로세스는 다음과 같은 접근 확인을 실행합니다:

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

Active Directory에서 사용자는 사용자 계정 제어 속성(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 패키지 (Omnibus)

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

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

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

Helm 차트 (Kubernetes)

Helm 값(values)을 내보냅니다:

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 서버가 사용자가 로그인할 때 이용 가능하지 않은 경우.

사용자가 차단되면 해당 사용자는 로그인하거나 코드를 push 또는 pull할 수 없습니다.

사용자가 LDAP로 로그인했을 때 다음 조건을 모두 충족하면 차단 해제됩니다:

모든 접근 확인 조건이 true인 경우.
사용자가 로그인할 때 LDAP 서버가 사용 가능한 경우.

LDAP 사용자 동기화 실행시 LDAP 서버가 없을 경우 모든 사용자가 차단됩니다.

차단된 사용자는 LDAP 사용자 동기화 실행 시 LDAP 서버가 사용 가능하지 않은 경우 자동으로 차단 해제되지 않습니다.

LDAP 사용자 동기화 일정 조정

기본적으로, GitLab은 하루에 한 번씩 서버 시간 01:30에 사용자를 검사하고 LDAP에 대해 동기화합니다.

필요에 따라, 크론 포맷을 사용하여 LDAP 사용자 동기화 시간을 매뉴얼으로 설정할 수 있습니다. 아래 예는 매 12시간마다 맨 처음에 실행되도록 LDAP 사용자 동기화를 설정하는 방법을 보여줍니다.

Linux 패키지 (Omnibus)

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

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

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

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

직접 컴파일(소스)

/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은 사용자가 속해야 하는 그룹을 동기화하는 작업을 트리거합니다. 그러면 매 시간마다 동기화를 기다릴 필요 없이 바로 그룹과 프로젝트에 액세스할 수 있습니다.

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

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

Linux package (Omnibus)

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

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

파일을 저장하고 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

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

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에 대한 group CN을 지정하면 해당 LDAP 그룹의 모든 멤버에게 관리자 권한이 부여됩니다. 구성은 다음과 같습니다.

admin_group과 함께 group_base가 명시되지 않으면 관리자는 동기화되지 않습니다. 또한 admin_group의 전체 DN 대신 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
```

직접 컴파일 (소스)

/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 그룹 동기화 설정을 관리할 수 있습니다.

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

LDAP 설정을 구성합니다.
왼쪽 사이드바에서 맨 아래쪽에 있는 Admin Area를 선택합니다.
Settings > General을 선택합니다.
Visibility and access controls를 확장합니다.
Allow group owners to manage LDAP-related settings 확인란이 선택되지 않았는지 확인하세요.

Allow group owners to manage LDAP-related settings를 비활성화하면:

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

LDAP 그룹 동기화 스케줄 조정

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

동기화 프로세스를 너무 자주 시작하지 마십시오. 이렇게 하면 여러 동기화가 동시에 실행될 수 있습니다. 이 문제는 특히 많은 수의 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 쿼리와 그룹 동기화에서 기대할 수 있는 동작을 설명합니다.

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로 실행되며, 범위는 ‘베이스 객체’이며, 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 그룹 유형/속성

중첩 그룹 멤버십

쿼리

벤치마킹

문제 해결

도움말

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

도움받기