LDAP 동기화

Tier: Premium, Ultimate 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 서버의 속도 제한을 고려해야 합니다.

사용자 동기화

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

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

이 프로세스는 다음 액세스 검사를 수행합니다:

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

Active Directory에서 사용자는 사용자 계정 제어 속성(userAccountControl:1.2.840.113556.1.4.803)의 비트 2가 설정되어 있는 경우 비활성/차단으로 표시됩니다.

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

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

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

참고:
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 서버가 사용할 수 없기 때문에 모든 사용자가 차단된 경우, 이후 LDAP 사용자 동기화가 그 사용자들을 자동으로 차단 해제하지 않습니다.

그룹 동기화

LDAP에서 memberof 속성을 지원하는 경우, 사용자가 처음 로그인할 때 GitLab은 사용자가 멤버로 있어야 하는 그룹에 대한 동기화를 트리거합니다.
이렇게 하면 사용자가 그룹 및 프로젝트에 대한 액세스를 부여받기 위해 매시간 동기화를 기다릴 필요가 없습니다.

그룹 동기화 프로세스는 매시간 정각에 실행되며, group_base는 그룹 CN을 기반으로 한 LDAP 동기화가 작동하도록 LDAP 구성에서 설정해야 합니다. 이로 인해 GitLab 그룹 멤버십이 LDAP 그룹 구성원 기반으로 자동으로 업데이트될 수 있습니다.

group_base 구성은 GitLab에서 사용할 수 있는 LDAP 그룹을 포함하는 LDAP ‘컨테이너’(예: ‘조직’ 또는 ‘조직 단위’)여야 합니다. 예를 들어, group_base는 ou=groups,dc=example,dc=com이 될 수 있습니다. 구성 파일에서는 다음과 같이 보입니다.

LDAP 서버에 요금 제한이 있는 경우, 그룹 동기화 프로세스 중에 그 제한에 도달할 수 있습니다. 자세한 내용은 요금 제한 문서를 확인하세요.

리눅스 패키지 (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시간 기본값보다 더 높은 값으로 줄여보세요.

그룹 링크 추가

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

관리자 동기화

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

참고: admin_group과 함께 group_base도 지정되지 않으면 관리자가 동기화되지 않습니다. 또한, 전체 DN이 아닌 admin_group의 CN만 지정해야 합니다.

추가로, LDAP 사용자가 admin 역할을 가지고 있지만 admin_group 그룹의 구성원이 아닌 경우, GitLab은 동기화할 때 그들의 admin 역할을 취소합니다.

리눅스 패키지 (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
```

헬름 차트 (Kubernetes)

헬름 값을 내보냅니다:

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-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 구성하기.
왼쪽 사이드바에서 맨 아래의 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 패키지 (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이 DN 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, 범위 ‘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 사용자 동기화 일정 조정

기본적으로 GitLab은 매일 오전 1시 30분 서버 시간에 워커를 실행하여 LDAP에 대해 GitLab 사용자를 확인하고 업데이트합니다.

경고:

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

다음 구성 값을 설정하여 LDAP 사용자 동기화 시간을 수동으로 구성할 수 있습니다. 필요에 따라 crontab 생성기를 사용할 수 있습니다. 아래 예시는 LDAP 사용자 동기화가 매 12시간마다 정시에 실행되도록 설정하는 방법을 보여줍니다.

리눅스 패키지 (Omnibus)

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

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

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

헬름 차트 (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 그룹 동기화 일정 조정

기본적으로 GitLab은 매시간 정각마다 그룹 동기화 프로세스를 실행합니다.

표시된 값은 cron 형식입니다. 필요에 따라 Crontab Generator를 사용할 수 있습니다.

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

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

리눅스 패키지 (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-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  

문제 해결

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

LDAP 동기화

속도 제한이 있는 LDAP 서버

사용자 동기화

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

차단된 사용자

그룹 동기화

그룹 링크 추가

관리자 동기화

전역 그룹 멤버십 잠금

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

외부 그룹

그룹 동기화 기술 세부정보

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

중첩 그룹 멤버십

쿼리

성능 기준

LDAP 사용자 동기화 일정 조정

LDAP 그룹 동기화 일정 조정

문제 해결

도움말

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

도움받기