InfoGrab DocsInfoGrab Docs

LDAP 동기화

요약

LDAP를 GitLab과 연동하도록 구성했다면 GitLab 이 사용자와 그룹을 자동으로 동기화할 수 있습니다. LDAP 동기화는 LDAP ID가 할당된 기존 GitLab 사용자의 사용자 정보와 그룹 정보를 갱신합니다.

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

LDAP 동기화는 LDAP ID가 할당된 기존 GitLab 사용자의 사용자 정보와 그룹 정보를 갱신합니다. LDAP를 통해 새 GitLab 사용자를 만들지는 않습니다.

동기화가 실행되는 시점은 변경할 수 있습니다.

속도 제한이 있는 LDAP 서버#

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

GitLab은 다음 대상마다 LDAP 서버에 한 번씩 쿼리합니다.

경우에 따라 LDAP 서버로 더 많은 쿼리가 발생할 수 있습니다. 예를 들어 그룹 동기화 쿼리가 memberuid 속성을 반환할 때입니다.

LDAP 서버에 속도 제한이 구성되어 있고 다음 과정에서 그 한도에 도달하면 이렇게 동작합니다.

  • 사용자 동기화 과정에서는 LDAP 서버가 오류 코드를 반환하고 GitLab 이 해당 사용자를 차단합니다.
  • 그룹 동기화 과정에서는 LDAP 서버가 오류 코드를 반환하고 GitLab 이 해당 사용자의 그룹 멤버십을 제거합니다.

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

사용자 동기화#

GitLab은 하루에 한 번 워커를 실행해 GitLab 사용자를 LDAP와 대조하고 갱신합니다.

이 과정에서 다음 액세스 검사를 수행합니다.

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

Active Directory에서는 사용자 계정 제어 속성 (userAccountControl:1.2.840.113556.1.4.803)의 비트 2가 설정되면 해당 사용자가 비활성·차단 상태로 표시됩니다.

자세한 내용은 Bitmask Searches in LDAP를 참고합니다.

이 과정에서는 다음 사용자 정보도 갱신합니다.

  • sync_name 이 true로 설정된 경우의 이름입니다. 이 동기화는 Prevent users from changing their profile name이 활성화되어 있어도 수행됩니다.
  • 이메일 주소입니다.
  • sync_ssh_keys가 설정된 경우의 SSH 공개 키입니다.
  • Kerberos가 활성화된 경우의 Kerberos ID 입니다.
Note

LDAP 서버에 속도 제한이 있으면 사용자 동기화 과정에서 그 한도에 도달할 수 있습니다. 자세한 내용은 속도 제한 문서를 확인합니다.

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

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

이 동기화를 막으려면 sync_name을 false로 설정합니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

차단된 사용자#

다음 중 하나에 해당하면 사용자가 차단됩니다.

  • 액세스 검사에 실패해 해당 사용자가 GitLab에서 ldap_blocked 상태가 된 경우입니다.
  • 사용자가 로그인할 때 LDAP 서버를 사용할 수 없는 경우입니다.

사용자가 차단되면 로그인하거나 코드를 푸시하거나 풀할 수 없습니다.

다음 조건이 모두 참이면 차단된 사용자가 LDAP로 로그인할 때 차단이 해제됩니다.

  • 모든 액세스 검사 조건이 참입니다.
  • 사용자가 로그인할 때 LDAP 서버를 사용할 수 있습니다.

LDAP 사용자 동기화를 실행할 때 LDAP 서버를 사용할 수 없으면 모든 사용자가 차단됩니다.

Note

LDAP 사용자 동기화를 실행할 때 LDAP 서버를 사용할 수 없어 모든 사용자가 차단된 경우, 이후 LDAP 사용자 동기화가 그 사용자들의 차단을 자동으로 해제하지는 않습니다.

그룹 동기화#

LDAP가 memberof 속성을 지원한다면 사용자가 처음 로그인할 때 GitLab 이 그 사용자가 속해야 할 그룹의 동기화를 실행합니다. 그러면 사용자는 그룹과 프로젝트에 대한 접근 권한을 받기 위해 매시간 동기화를 기다리지 않아도 됩니다.

그룹 동기화 과정은 매시 정각에 실행되며, 그룹 CN을 기준으로 하는 LDAP 동기화가 동작하려면 LDAP 구성에 group_base를 설정해야 합니다. 이렇게 하면 LDAP 그룹 멤버를 기준으로 GitLab 그룹 멤버십을 자동으로 갱신할 수 있습니다.

group_base 구성에는 GitLab에서 사용할 LDAP 그룹을 담고 있는 'organization' 이나 'organizational unit' 같은 기본 LDAP 'container' 를 지정합니다. 예를 들어 group_base는 ou=groups,dc=example,dc=com 이 될 수 있습니다. 구성 파일에서는 다음과 같은 형태입니다.

Note

LDAP 서버에 속도 제한이 있으면 그룹 동기화 과정에서 그 한도에 도달할 수 있습니다. 자세한 내용은 속도 제한 문서를 확인합니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. 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',
            }
        }

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹 동기화를 활용하려면 그룹 Owner 또는 Maintainer 권한이 있는 사용자가 LDAP 그룹 링크를 하나 이상 생성해야 합니다.

Note

LDAP 서버와 GitLab 인스턴스 사이에 연결 문제가 자주 발생한다면, 그룹 동기화 워커 간격을 기본값인 1시간보다 길게 설정해 GitLab 이 LDAP 그룹 동기화를 수행하는 빈도를 낮춰 봅니다.

그룹 링크 추가#

CN과 필터를 사용해 그룹 링크를 추가하는 방법은 GitLab 그룹 문서를 참고합니다.

서비스 계정 동기화#

기본적으로 그룹 동기화는 서비스 계정의 그룹 멤버십을 관리하지 않습니다. 서비스 계정에는 대조할 LDAP ID가 없기 때문입니다.

그룹 동기화가 사람 사용자와 같은 방식으로 서비스 계정의 멤버십을 관리하게 하려면, 사용자 수정 API 엔드포인트로 서비스 계정에 provider 및 extern_uid 속성을 가진 LDAP ID를 할당합니다.

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "provider=ldapmain" \
  --data "extern_uid=uid=example-service-account,ou=people,dc=example,dc=com" \
  --url "https://gitlab.example.com/api/v4/users/<service_account_user_id>"

ID를 할당하면 그룹 동기화가 사람 사용자의 멤버십을 관리하는 것과 같은 방식으로 서비스 계정의 그룹 멤버십을 관리합니다.

전용 UI와 API 엔드포인트는 이슈 578187에서 제안되었습니다.

LDAP 그룹에 관리자 권한 할당#

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

Note

admin_group과 함께 group_base도 지정하지 않으면 관리자는 동기화되지 않습니다. 또한 admin_group에는 전체 DN 이 아니라 CN만 지정합니다. 그리고 LDAP 사용자가 admin 권한을 갖고 있지만 admin_group 그룹의 멤버가 아니라면, GitLab은 동기화 시 그 사용자의 admin 권한을 회수합니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. 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',
            }
        }

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 그룹에 감사자 권한 할당#

히스토리
  • GitLab 19.3에서 도입되었습니다.

그룹 동기화의 확장으로 감사자 권한을 가진 사용자를 자동으로 관리할 수 있습니다. audit_group에 그룹 CN을 지정하면 해당 LDAP 그룹의 모든 멤버에게 감사자 권한이 부여됩니다.

Note

audit_group과 함께 group_base도 지정하지 않으면 감사자 사용자는 동기화되지 않습니다. 또한 audit_group에는 전체 DN 이 아니라 CN만 지정합니다. 그리고 LDAP 사용자가 감사자 권한을 갖고 있지만 audit_group 그룹의 멤버가 아니라면, GitLab은 동기화 시 감사자 권한을 회수합니다.

LDAP 그룹 멤버에게 감사자 권한을 할당하는 방법은 다음과 같습니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. 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',
            'audit_group' => 'my_audit_group',
            }
        }

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 그룹에 사용자 정의 관리자 권한 할당#

외부 LDAP 그룹에서 동기화된 모든 사용자에게 사용자 정의 관리자 권한을 할당할 수 있습니다. 이 옵션은 SAML 그룹에는 제공되지 않습니다.

사용자가 서로 다른 사용자 정의 권한이 할당된 여러 LDAP 그룹에 속한다면, GitLab은 가장 먼저 연결된 LDAP 그룹에 연결된 권한을 할당합니다.

Note

동기화를 구성한 뒤 사용자 정의 관리자 권한을 가진 LDAP 사용자가 LDAP 그룹에서 제거되면, 다음 동기화 전까지는 사용자 정의 권한이 제거되지 않습니다.

사전 요구 사항:

  • 인스턴스에 통합된 LDAP 서버가 있습니다.
  • 관리자 액세스 권한이 있습니다.

LDAP CN으로 사용자 정의 관리자 권한을 할당하는 방법은 다음과 같습니다.

  1. 오른쪽 위에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > Roles and permissions를 선택합니다.
  3. LDAP Synchronization 탭에서 LDAP Server를 선택합니다.
  4. Sync method 필드에서 Group cn을 선택합니다.
  5. Group cn 필드에 그룹의 CN을 입력하기 시작합니다. 구성된 group_base에서 일치하는 CN 이 드롭다운 목록으로 표시됩니다.
  6. 드롭다운 목록에서 원하는 CN을 선택합니다.
  7. Custom admin role 필드에서 사용자 정의 관리자 권한을 선택합니다.
  8. Add를 선택합니다.

GitLab 이 일치하는 LDAP 사용자에게 권한을 연결하기 시작합니다. 이 과정은 완료까지 한 시간 이상 걸릴 수 있습니다.

LDAP 필터로 사용자 정의 관리자 권한을 할당하는 방법은 다음과 같습니다.

  1. 오른쪽 위에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > Roles and permissions를 선택합니다.
  3. LDAP Synchronization 탭에서 LDAP Server를 선택합니다.
  4. Sync method 필드에서 User filter를 선택합니다.
  5. User filter 텍스트 상자에 필터를 입력합니다. 자세한 내용은 LDAP 사용자 필터 설정을 참고합니다.
  6. Custom admin role 필드에서 사용자 정의 관리자 권한을 선택합니다.
  7. Add를 선택합니다.

GitLab 이 일치하는 LDAP 사용자에게 권한을 연결하기 시작합니다. 이 과정은 완료까지 한 시간 이상 걸릴 수 있습니다.

글로벌 LDAP 그룹 멤버십 잠금#

GitLab 관리자는 멤버십이 LDAP와 동기화되는 하위 그룹에 그룹 멤버가 새 멤버를 초대하지 못하게 막을 수 있습니다.

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

글로벌 그룹 멤버십 잠금을 활성화하면 이렇게 동작합니다.

  • 그룹이나 하위 그룹을 Code Owner로 설정할 수 없습니다. 자세한 내용은 글로벌 그룹 멤버십 잠금과의 비호환성을 참고합니다.
  • 액세스 수준을 포함해 모든 그룹의 멤버십은 관리자만 관리할 수 있습니다.
  • 사용자는 프로젝트를 다른 그룹과 공유하거나 그룹에서 만든 프로젝트에 멤버를 초대할 수 없습니다.

글로벌 그룹 멤버십 잠금을 활성화하는 방법은 다음과 같습니다.

  1. LDAP를 구성합니다.
  2. 오른쪽 위에서 Admin을 선택합니다.
  3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  4. Visibility and access controls를 확장합니다.
  5. Lock memberships to LDAP synchronization 체크박스가 선택되어 있는지 확인합니다.

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

기본적으로 Owner 권한을 가진 그룹 멤버는 LDAP 그룹 동기화 설정을 관리할 수 있습니다.

GitLab 관리자는 그룹 Owner 에게서 이 권한을 제거할 수 있습니다.

  1. LDAP를 구성합니다.
  2. 오른쪽 위에서 Admin을 선택합니다.
  3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  4. Visibility and access controls를 확장합니다.
  5. Allow group owners to manage LDAP-related settings 체크박스가 선택되어 있지 않은지 확인합니다.

Allow group owners to manage LDAP-related settings가 비활성화되면 이렇게 동작합니다.

  • 그룹 Owner는 최상위 그룹과 하위 그룹 어느 쪽에서도 LDAP 동기화 설정을 변경할 수 없습니다.
  • 인스턴스 관리자는 인스턴스의 모든 그룹에서 LDAP 그룹 동기화 설정을 관리할 수 있습니다.

외부 그룹#

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

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹을 위한 GitLab Duo 애드온#

duo_add_on_groups 설정은 LDAP로 인증하는 사용자의 GitLab Duo 애드온 시트를 자동으로 관리합니다. 이 기능을 사용하면 LDAP 그룹 멤버십을 기준으로 GitLab Duo 시트 할당 절차를 간소화할 수 있습니다.

GitLab Duo 시트 동기화는 두 가지 방식으로 이루어집니다.

  • 사용자 로그인 시: 사용자가 LDAP로 로그인하면 GitLab 이 즉시 그 사용자의 그룹 멤버십을 확인합니다.
  • 예약 동기화: GitLab은 매일 오전 2시(서버 시간)에 모든 LDAP 사용자를 자동으로 동기화해, 사용자 로그인이 없어도 시트 할당을 최신 상태로 유지합니다.

그룹의 애드온 시트 관리를 활성화하려면 GitLab 인스턴스에서 duo_add_on_groups 설정을 구성해야 합니다.

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

    gitlab_rails['ldap_servers'] = {
  'main' => {
    'duo_add_on_groups' => ['duo_group_1', 'duo_group_2'],
    }
}

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

    global:
  appConfig:
    ldap:
      servers:
        main:
          duo_add_on_groups: ['duo_group_1', 'duo_group_2']

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

    production: &base
  ldap:
    servers:
      main:
        duo_add_on_groups: ['duo_group_1', 'duo_group_2']

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹 동기화 기술적 세부 사항#

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

사용자의 LDAP 그룹 멤버십이 바뀌면 그룹 액세스 수준이 낮아질 수 있습니다. 예를 들어 사용자가 그룹에서 Owner 권한을 갖고 있는데 다음 그룹 동기화에서 Developer 권한만 가져야 하는 것으로 확인되면, 그에 맞게 액세스 수준이 조정됩니다. 유일한 예외는 그 사용자가 그룹의 마지막 Owner 인 경우입니다. 그룹에는 관리 업무를 수행할 Owner가 최소 한 명 필요합니다.

접근 제한이 있는 Minimal Access 권한 할당#

히스토리

접근 제한이 활성화되어 있고 사용할 수 있는 구독 시트가 없으면, LDAP 그룹 동기화 중에 사용자에게 Minimal Access 권한이 할당됩니다.

자세한 내용은 SAML, SCIM, 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 그룹은 base를 group_base로, 필터를 (cn=<cn_from_group_link>)로 두고 최대 한 번 쿼리됩니다.
  • LDAP 그룹에 memberuid 속성이 있으면 GitLab은 각 사용자의 전체 DN을 얻기 위해 멤버마다 LDAP 쿼리를 한 번 더 실행합니다. 이 쿼리는 base를 base로, scope를 baseObject로 두고 실행하며, 필터는 user_filter 설정 여부에 따라 달라집니다. 필터는 (uid=<uid_from_group>) 이거나 user_filter를 결합한 형태일 수 있습니다.

벤치마크#

그룹 동기화는 성능을 최대한 높이도록 작성되었습니다. 데이터는 캐시되고 데이터베이스 쿼리는 최적화되며 LDAP 쿼리는 최소화됩니다. 마지막 벤치마크 실행에서는 다음 지표가 확인되었습니다.

LDAP 사용자 20,000 명, LDAP 그룹 11,000 개, LDAP 그룹 링크가 각각 10 개인 GitLab 그룹 1,000 개를 기준으로 합니다.

  • 초기 동기화(GitLab에 할당된 기존 멤버 없음)에 1.8 시간이 걸렸습니다
  • 이후 동기화(멤버십 확인만 하고 쓰기 없음)에 15 분이 걸렸습니다

이 지표는 기준선을 제시하기 위한 것이며 여러 요인에 따라 성능이 달라질 수 있습니다. 이 벤치마크는 극단적인 조건이며 대부분의 인스턴스는 이만큼 많은 사용자나 그룹을 보유하지 않습니다. 디스크 속도, 데이터베이스 성능, 네트워크와 LDAP 서버 응답 시간이 이 지표에 영향을 줍니다.

LDAP 동기화 일정 조정#

LDAP가 사용자, 그룹, GitLab Duo 애드온 시트를 동기화하는 시각과 간격을 변경할 수 있습니다.

사용자의 경우#

기본적으로 GitLab은 서버 시간 기준 오전 1시 30분에 하루 한 번 워커를 실행해 GitLab 사용자를 LDAP와 대조하고 갱신합니다.

Warning

동기화 과정을 너무 자주 실행하면 여러 동기화가 동시에 실행될 수 있으므로 그렇게 하지 않습니다. 대부분의 설치 환경에서는 동기화 일정을 변경할 필요가 없습니다. 자세한 내용은 LDAP 보안 문서를 참고합니다.

다음 구성 값을 cron 형식으로 설정해 LDAP 사용자 동기화 시각을 직접 구성할 수 있습니다. 필요하다면 crontab 생성기를 사용할 수 있습니다. 다음 예시는 LDAP 사용자 동기화를 12시간마다 정각에 한 번씩 실행하도록 설정하는 방법을 보여 줍니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹의 경우#

기본적으로 GitLab은 매시 정각에 그룹 동기화 과정을 실행합니다. 표시된 값은 cron 형식입니다. 필요하다면 crontab 생성기를 사용할 수 있습니다.

Warning

동기화 과정을 너무 자주 시작하면 여러 동기화가 동시에 실행될 수 있으므로 그렇게 하지 않습니다. 대부분의 설치 환경에서는 동기화 일정을 변경할 필요가 없습니다.

다음 구성 값을 설정해 LDAP 그룹 동기화 시각을 직접 구성할 수 있습니다. 다음 예시는 그룹 동기화를 두 시간마다 정각에 한 번씩 실행하도록 설정하는 방법을 보여 줍니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

GitLab Duo 애드온 시트의 경우#

기본적으로 GitLab은 서버 시간 기준 오전 2시에 하루 한 번 GitLab Duo 애드온 시트 동기화 과정을 실행해 LDAP 그룹 멤버십을 확인하고 그에 따라 GitLab Duo 애드온 시트를 할당하거나 회수합니다.

Warning

동기화 과정을 너무 자주 시작하면 여러 동기화가 동시에 실행될 수 있으므로 그렇게 하지 않습니다. 대부분의 설치 환경에서는 동기화 일정을 변경할 필요가 없습니다.

구성 값을 설정해 LDAP GitLab Duo 애드온 시트 동기화 시각을 직접 구성할 수 있습니다. 다음 예시는 동기화를 네 시간마다 한 번씩 실행하도록 설정하는 방법을 보여 줍니다.

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

    gitlab_rails['ldap_add_on_seat_sync_worker_cron'] = "0 */4 * * *"

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

    global:
  appConfig:
    cron_jobs:
      ldap_add_on_seat_sync_worker:
        cron: "0 */4 * * *"

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

    production: &base
  ee_cron_jobs:
    ldap_add_on_seat_sync_worker:
      cron: "0 */4 * * *"

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 동기화

GitLab v19.4
Tier: Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

LDAP를 GitLab과 연동하도록 구성했다면 GitLab 이 사용자와 그룹을 자동으로 동기화할 수 있습니다. LDAP 동기화는 LDAP ID가 할당된 기존 GitLab 사용자의 사용자 정보와 그룹 정보를 갱신합니다.

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

LDAP 동기화는 LDAP ID가 할당된 기존 GitLab 사용자의 사용자 정보와 그룹 정보를 갱신합니다. LDAP를 통해 새 GitLab 사용자를 만들지는 않습니다.

동기화가 실행되는 시점은 변경할 수 있습니다.

속도 제한이 있는 LDAP 서버#

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

GitLab은 다음 대상마다 LDAP 서버에 한 번씩 쿼리합니다.

경우에 따라 LDAP 서버로 더 많은 쿼리가 발생할 수 있습니다. 예를 들어 그룹 동기화 쿼리가 memberuid 속성을 반환할 때입니다.

LDAP 서버에 속도 제한이 구성되어 있고 다음 과정에서 그 한도에 도달하면 이렇게 동작합니다.

  • 사용자 동기화 과정에서는 LDAP 서버가 오류 코드를 반환하고 GitLab 이 해당 사용자를 차단합니다.
  • 그룹 동기화 과정에서는 LDAP 서버가 오류 코드를 반환하고 GitLab 이 해당 사용자의 그룹 멤버십을 제거합니다.

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

사용자 동기화#

GitLab은 하루에 한 번 워커를 실행해 GitLab 사용자를 LDAP와 대조하고 갱신합니다.

이 과정에서 다음 액세스 검사를 수행합니다.

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

Active Directory에서는 사용자 계정 제어 속성 (userAccountControl:1.2.840.113556.1.4.803)의 비트 2가 설정되면 해당 사용자가 비활성·차단 상태로 표시됩니다.

자세한 내용은 Bitmask Searches in LDAP를 참고합니다.

이 과정에서는 다음 사용자 정보도 갱신합니다.

  • sync_name 이 true로 설정된 경우의 이름입니다. 이 동기화는 Prevent users from changing their profile name이 활성화되어 있어도 수행됩니다.
  • 이메일 주소입니다.
  • sync_ssh_keys가 설정된 경우의 SSH 공개 키입니다.
  • Kerberos가 활성화된 경우의 Kerberos ID 입니다.
Note

LDAP 서버에 속도 제한이 있으면 사용자 동기화 과정에서 그 한도에 도달할 수 있습니다. 자세한 내용은 속도 제한 문서를 확인합니다.

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

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

이 동기화를 막으려면 sync_name을 false로 설정합니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

차단된 사용자#

다음 중 하나에 해당하면 사용자가 차단됩니다.

  • 액세스 검사에 실패해 해당 사용자가 GitLab에서 ldap_blocked 상태가 된 경우입니다.
  • 사용자가 로그인할 때 LDAP 서버를 사용할 수 없는 경우입니다.

사용자가 차단되면 로그인하거나 코드를 푸시하거나 풀할 수 없습니다.

다음 조건이 모두 참이면 차단된 사용자가 LDAP로 로그인할 때 차단이 해제됩니다.

  • 모든 액세스 검사 조건이 참입니다.
  • 사용자가 로그인할 때 LDAP 서버를 사용할 수 있습니다.

LDAP 사용자 동기화를 실행할 때 LDAP 서버를 사용할 수 없으면 모든 사용자가 차단됩니다.

Note

LDAP 사용자 동기화를 실행할 때 LDAP 서버를 사용할 수 없어 모든 사용자가 차단된 경우, 이후 LDAP 사용자 동기화가 그 사용자들의 차단을 자동으로 해제하지는 않습니다.

그룹 동기화#

LDAP가 memberof 속성을 지원한다면 사용자가 처음 로그인할 때 GitLab 이 그 사용자가 속해야 할 그룹의 동기화를 실행합니다. 그러면 사용자는 그룹과 프로젝트에 대한 접근 권한을 받기 위해 매시간 동기화를 기다리지 않아도 됩니다.

그룹 동기화 과정은 매시 정각에 실행되며, 그룹 CN을 기준으로 하는 LDAP 동기화가 동작하려면 LDAP 구성에 group_base를 설정해야 합니다. 이렇게 하면 LDAP 그룹 멤버를 기준으로 GitLab 그룹 멤버십을 자동으로 갱신할 수 있습니다.

group_base 구성에는 GitLab에서 사용할 LDAP 그룹을 담고 있는 'organization' 이나 'organizational unit' 같은 기본 LDAP 'container' 를 지정합니다. 예를 들어 group_base는 ou=groups,dc=example,dc=com 이 될 수 있습니다. 구성 파일에서는 다음과 같은 형태입니다.

Note

LDAP 서버에 속도 제한이 있으면 그룹 동기화 과정에서 그 한도에 도달할 수 있습니다. 자세한 내용은 속도 제한 문서를 확인합니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. 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',
            }
        }

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹 동기화를 활용하려면 그룹 Owner 또는 Maintainer 권한이 있는 사용자가 LDAP 그룹 링크를 하나 이상 생성해야 합니다.

Note

LDAP 서버와 GitLab 인스턴스 사이에 연결 문제가 자주 발생한다면, 그룹 동기화 워커 간격을 기본값인 1시간보다 길게 설정해 GitLab 이 LDAP 그룹 동기화를 수행하는 빈도를 낮춰 봅니다.

그룹 링크 추가#

CN과 필터를 사용해 그룹 링크를 추가하는 방법은 GitLab 그룹 문서를 참고합니다.

서비스 계정 동기화#

기본적으로 그룹 동기화는 서비스 계정의 그룹 멤버십을 관리하지 않습니다. 서비스 계정에는 대조할 LDAP ID가 없기 때문입니다.

그룹 동기화가 사람 사용자와 같은 방식으로 서비스 계정의 멤버십을 관리하게 하려면, 사용자 수정 API 엔드포인트로 서비스 계정에 provider 및 extern_uid 속성을 가진 LDAP ID를 할당합니다.

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "provider=ldapmain" \
  --data "extern_uid=uid=example-service-account,ou=people,dc=example,dc=com" \
  --url "https://gitlab.example.com/api/v4/users/<service_account_user_id>"

ID를 할당하면 그룹 동기화가 사람 사용자의 멤버십을 관리하는 것과 같은 방식으로 서비스 계정의 그룹 멤버십을 관리합니다.

전용 UI와 API 엔드포인트는 이슈 578187에서 제안되었습니다.

LDAP 그룹에 관리자 권한 할당#

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

Note

admin_group과 함께 group_base도 지정하지 않으면 관리자는 동기화되지 않습니다. 또한 admin_group에는 전체 DN 이 아니라 CN만 지정합니다. 그리고 LDAP 사용자가 admin 권한을 갖고 있지만 admin_group 그룹의 멤버가 아니라면, GitLab은 동기화 시 그 사용자의 admin 권한을 회수합니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. 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',
            }
        }

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 그룹에 감사자 권한 할당#

히스토리
  • GitLab 19.3에서 도입되었습니다.

그룹 동기화의 확장으로 감사자 권한을 가진 사용자를 자동으로 관리할 수 있습니다. audit_group에 그룹 CN을 지정하면 해당 LDAP 그룹의 모든 멤버에게 감사자 권한이 부여됩니다.

Note

audit_group과 함께 group_base도 지정하지 않으면 감사자 사용자는 동기화되지 않습니다. 또한 audit_group에는 전체 DN 이 아니라 CN만 지정합니다. 그리고 LDAP 사용자가 감사자 권한을 갖고 있지만 audit_group 그룹의 멤버가 아니라면, GitLab은 동기화 시 감사자 권한을 회수합니다.

LDAP 그룹 멤버에게 감사자 권한을 할당하는 방법은 다음과 같습니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. 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',
            'audit_group' => 'my_audit_group',
            }
        }

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

LDAP 그룹에 사용자 정의 관리자 권한 할당#

외부 LDAP 그룹에서 동기화된 모든 사용자에게 사용자 정의 관리자 권한을 할당할 수 있습니다. 이 옵션은 SAML 그룹에는 제공되지 않습니다.

사용자가 서로 다른 사용자 정의 권한이 할당된 여러 LDAP 그룹에 속한다면, GitLab은 가장 먼저 연결된 LDAP 그룹에 연결된 권한을 할당합니다.

Note

동기화를 구성한 뒤 사용자 정의 관리자 권한을 가진 LDAP 사용자가 LDAP 그룹에서 제거되면, 다음 동기화 전까지는 사용자 정의 권한이 제거되지 않습니다.

사전 요구 사항:

  • 인스턴스에 통합된 LDAP 서버가 있습니다.
  • 관리자 액세스 권한이 있습니다.

LDAP CN으로 사용자 정의 관리자 권한을 할당하는 방법은 다음과 같습니다.

  1. 오른쪽 위에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > Roles and permissions를 선택합니다.
  3. LDAP Synchronization 탭에서 LDAP Server를 선택합니다.
  4. Sync method 필드에서 Group cn을 선택합니다.
  5. Group cn 필드에 그룹의 CN을 입력하기 시작합니다. 구성된 group_base에서 일치하는 CN 이 드롭다운 목록으로 표시됩니다.
  6. 드롭다운 목록에서 원하는 CN을 선택합니다.
  7. Custom admin role 필드에서 사용자 정의 관리자 권한을 선택합니다.
  8. Add를 선택합니다.

GitLab 이 일치하는 LDAP 사용자에게 권한을 연결하기 시작합니다. 이 과정은 완료까지 한 시간 이상 걸릴 수 있습니다.

LDAP 필터로 사용자 정의 관리자 권한을 할당하는 방법은 다음과 같습니다.

  1. 오른쪽 위에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Settings > Roles and permissions를 선택합니다.
  3. LDAP Synchronization 탭에서 LDAP Server를 선택합니다.
  4. Sync method 필드에서 User filter를 선택합니다.
  5. User filter 텍스트 상자에 필터를 입력합니다. 자세한 내용은 LDAP 사용자 필터 설정을 참고합니다.
  6. Custom admin role 필드에서 사용자 정의 관리자 권한을 선택합니다.
  7. Add를 선택합니다.

GitLab 이 일치하는 LDAP 사용자에게 권한을 연결하기 시작합니다. 이 과정은 완료까지 한 시간 이상 걸릴 수 있습니다.

글로벌 LDAP 그룹 멤버십 잠금#

GitLab 관리자는 멤버십이 LDAP와 동기화되는 하위 그룹에 그룹 멤버가 새 멤버를 초대하지 못하게 막을 수 있습니다.

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

글로벌 그룹 멤버십 잠금을 활성화하면 이렇게 동작합니다.

  • 그룹이나 하위 그룹을 Code Owner로 설정할 수 없습니다. 자세한 내용은 글로벌 그룹 멤버십 잠금과의 비호환성을 참고합니다.
  • 액세스 수준을 포함해 모든 그룹의 멤버십은 관리자만 관리할 수 있습니다.
  • 사용자는 프로젝트를 다른 그룹과 공유하거나 그룹에서 만든 프로젝트에 멤버를 초대할 수 없습니다.

글로벌 그룹 멤버십 잠금을 활성화하는 방법은 다음과 같습니다.

  1. LDAP를 구성합니다.
  2. 오른쪽 위에서 Admin을 선택합니다.
  3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  4. Visibility and access controls를 확장합니다.
  5. Lock memberships to LDAP synchronization 체크박스가 선택되어 있는지 확인합니다.

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

기본적으로 Owner 권한을 가진 그룹 멤버는 LDAP 그룹 동기화 설정을 관리할 수 있습니다.

GitLab 관리자는 그룹 Owner 에게서 이 권한을 제거할 수 있습니다.

  1. LDAP를 구성합니다.
  2. 오른쪽 위에서 Admin을 선택합니다.
  3. 왼쪽 사이드바에서 Settings > General을 선택합니다.
  4. Visibility and access controls를 확장합니다.
  5. Allow group owners to manage LDAP-related settings 체크박스가 선택되어 있지 않은지 확인합니다.

Allow group owners to manage LDAP-related settings가 비활성화되면 이렇게 동작합니다.

  • 그룹 Owner는 최상위 그룹과 하위 그룹 어느 쪽에서도 LDAP 동기화 설정을 변경할 수 없습니다.
  • 인스턴스 관리자는 인스턴스의 모든 그룹에서 LDAP 그룹 동기화 설정을 관리할 수 있습니다.

외부 그룹#

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

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹을 위한 GitLab Duo 애드온#

duo_add_on_groups 설정은 LDAP로 인증하는 사용자의 GitLab Duo 애드온 시트를 자동으로 관리합니다. 이 기능을 사용하면 LDAP 그룹 멤버십을 기준으로 GitLab Duo 시트 할당 절차를 간소화할 수 있습니다.

GitLab Duo 시트 동기화는 두 가지 방식으로 이루어집니다.

  • 사용자 로그인 시: 사용자가 LDAP로 로그인하면 GitLab 이 즉시 그 사용자의 그룹 멤버십을 확인합니다.
  • 예약 동기화: GitLab은 매일 오전 2시(서버 시간)에 모든 LDAP 사용자를 자동으로 동기화해, 사용자 로그인이 없어도 시트 할당을 최신 상태로 유지합니다.

그룹의 애드온 시트 관리를 활성화하려면 GitLab 인스턴스에서 duo_add_on_groups 설정을 구성해야 합니다.

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

    gitlab_rails['ldap_servers'] = {
  'main' => {
    'duo_add_on_groups' => ['duo_group_1', 'duo_group_2'],
    }
}

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

    global:
  appConfig:
    ldap:
      servers:
        main:
          duo_add_on_groups: ['duo_group_1', 'duo_group_2']

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

    production: &base
  ldap:
    servers:
      main:
        duo_add_on_groups: ['duo_group_1', 'duo_group_2']

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹 동기화 기술적 세부 사항#

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

사용자의 LDAP 그룹 멤버십이 바뀌면 그룹 액세스 수준이 낮아질 수 있습니다. 예를 들어 사용자가 그룹에서 Owner 권한을 갖고 있는데 다음 그룹 동기화에서 Developer 권한만 가져야 하는 것으로 확인되면, 그에 맞게 액세스 수준이 조정됩니다. 유일한 예외는 그 사용자가 그룹의 마지막 Owner 인 경우입니다. 그룹에는 관리 업무를 수행할 Owner가 최소 한 명 필요합니다.

접근 제한이 있는 Minimal Access 권한 할당#

히스토리

접근 제한이 활성화되어 있고 사용할 수 있는 구독 시트가 없으면, LDAP 그룹 동기화 중에 사용자에게 Minimal Access 권한이 할당됩니다.

자세한 내용은 SAML, SCIM, 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 그룹은 base를 group_base로, 필터를 (cn=<cn_from_group_link>)로 두고 최대 한 번 쿼리됩니다.
  • LDAP 그룹에 memberuid 속성이 있으면 GitLab은 각 사용자의 전체 DN을 얻기 위해 멤버마다 LDAP 쿼리를 한 번 더 실행합니다. 이 쿼리는 base를 base로, scope를 baseObject로 두고 실행하며, 필터는 user_filter 설정 여부에 따라 달라집니다. 필터는 (uid=<uid_from_group>) 이거나 user_filter를 결합한 형태일 수 있습니다.

벤치마크#

그룹 동기화는 성능을 최대한 높이도록 작성되었습니다. 데이터는 캐시되고 데이터베이스 쿼리는 최적화되며 LDAP 쿼리는 최소화됩니다. 마지막 벤치마크 실행에서는 다음 지표가 확인되었습니다.

LDAP 사용자 20,000 명, LDAP 그룹 11,000 개, LDAP 그룹 링크가 각각 10 개인 GitLab 그룹 1,000 개를 기준으로 합니다.

  • 초기 동기화(GitLab에 할당된 기존 멤버 없음)에 1.8 시간이 걸렸습니다
  • 이후 동기화(멤버십 확인만 하고 쓰기 없음)에 15 분이 걸렸습니다

이 지표는 기준선을 제시하기 위한 것이며 여러 요인에 따라 성능이 달라질 수 있습니다. 이 벤치마크는 극단적인 조건이며 대부분의 인스턴스는 이만큼 많은 사용자나 그룹을 보유하지 않습니다. 디스크 속도, 데이터베이스 성능, 네트워크와 LDAP 서버 응답 시간이 이 지표에 영향을 줍니다.

LDAP 동기화 일정 조정#

LDAP가 사용자, 그룹, GitLab Duo 애드온 시트를 동기화하는 시각과 간격을 변경할 수 있습니다.

사용자의 경우#

기본적으로 GitLab은 서버 시간 기준 오전 1시 30분에 하루 한 번 워커를 실행해 GitLab 사용자를 LDAP와 대조하고 갱신합니다.

Warning

동기화 과정을 너무 자주 실행하면 여러 동기화가 동시에 실행될 수 있으므로 그렇게 하지 않습니다. 대부분의 설치 환경에서는 동기화 일정을 변경할 필요가 없습니다. 자세한 내용은 LDAP 보안 문서를 참고합니다.

다음 구성 값을 cron 형식으로 설정해 LDAP 사용자 동기화 시각을 직접 구성할 수 있습니다. 필요하다면 crontab 생성기를 사용할 수 있습니다. 다음 예시는 LDAP 사용자 동기화를 12시간마다 정각에 한 번씩 실행하도록 설정하는 방법을 보여 줍니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

그룹의 경우#

기본적으로 GitLab은 매시 정각에 그룹 동기화 과정을 실행합니다. 표시된 값은 cron 형식입니다. 필요하다면 crontab 생성기를 사용할 수 있습니다.

Warning

동기화 과정을 너무 자주 시작하면 여러 동기화가 동시에 실행될 수 있으므로 그렇게 하지 않습니다. 대부분의 설치 환경에서는 동기화 일정을 변경할 필요가 없습니다.

다음 구성 값을 설정해 LDAP 그룹 동기화 시각을 직접 구성할 수 있습니다. 다음 예시는 그룹 동기화를 두 시간마다 정각에 한 번씩 실행하도록 설정하는 방법을 보여 줍니다.

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

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

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

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

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

GitLab Duo 애드온 시트의 경우#

기본적으로 GitLab은 서버 시간 기준 오전 2시에 하루 한 번 GitLab Duo 애드온 시트 동기화 과정을 실행해 LDAP 그룹 멤버십을 확인하고 그에 따라 GitLab Duo 애드온 시트를 할당하거나 회수합니다.

Warning

동기화 과정을 너무 자주 시작하면 여러 동기화가 동시에 실행될 수 있으므로 그렇게 하지 않습니다. 대부분의 설치 환경에서는 동기화 일정을 변경할 필요가 없습니다.

구성 값을 설정해 LDAP GitLab Duo 애드온 시트 동기화 시각을 직접 구성할 수 있습니다. 다음 예시는 동기화를 네 시간마다 한 번씩 실행하도록 설정하는 방법을 보여 줍니다.

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

    gitlab_rails['ldap_add_on_seat_sync_worker_cron'] = "0 */4 * * *"

  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure

  1. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml

  2. gitlab_values.yaml을 편집합니다.

    global:
  appConfig:
    cron_jobs:
      ldap_add_on_seat_sync_worker:
        cron: "0 */4 * * *"

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

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

  1. docker-compose.yml을 편집합니다.

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

  2. 파일을 저장하고 GitLab을 재시작합니다.

    docker compose up -d

  1. /home/git/gitlab/config/gitlab.yml을 편집합니다.

    production: &base
  ee_cron_jobs:
    ldap_add_on_seat_sync_worker:
      cron: "0 */4 * * *"

  2. 파일을 저장하고 GitLab을 재시작합니다.

    # For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart