Help us learn about your current experience with the documentation. Take the survey.

LDAP 同步

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

如果您已配置 LDAP 与 GitLab 协同工作，GitLab 可自动同步用户和组。

LDAP 同步会更新已分配 LDAP 身份的现有 GitLab 用户的用户和组信息。它不会通过 LDAP 创建新的 GitLab 用户。

您可以更改同步的执行时间。

有速率限制的 LDAP 服务器

某些 LDAP 服务器配置了速率限制。

GitLab 在以下情况下会查询 LDAP 服务器：

在计划的用户同步过程中，每个用户查询一次。
在计划的组同步过程中，每个组查询一次。

某些情况下可能会触发更多 LDAP 服务器查询。例如，当组同步查询返回 memberuid 属性时。

如果 LDAP 服务器配置了速率限制，并在以下过程中达到限制：

用户同步过程中，LDAP 服务器返回错误代码，GitLab 会阻止该用户。
组同步过程中，LDAP 服务器返回错误代码，GitLab 会移除该用户的组成员资格。

配置 LDAP 同步时，必须考虑 LDAP 服务器的速率限制，以防止意外的用户阻止和组成员资格移除。

用户同步

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 身份。

如果您的 LDAP 服务器有速率限制，在用户同步过程中可能会达到该限制。有关更多信息，请查看速率限制文档。

同步 LDAP 用户个人资料名称

默认情况下，GitLab 会同步 LDAP 用户的个人资料名称字段。

要阻止此同步，您可以将 sync_name 设置为 false。

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

导出 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 支持 memberof 属性，当用户首次登录时， GitLab 会触发该用户所属组的同步。这样用户无需等待每小时同步，即可获得对其组和项目的访问权限。

组同步过程每小时整点运行一次，并且必须在 LDAP 配置中设置 group_base，才能使基于组 CN 的 LDAP 同步正常工作。这允许根据 LDAP 组成员自动更新 GitLab 组成员资格。

group_base 配置应是一个基础 LDAP “容器”（如 “组织” 或 “组织单位”），其中包含应提供给 GitLab 的 LDAP 组。例如，group_base 可以是 ou=groups,dc=example,dc=com。在配置文件中，它看起来如下所示。

如果您的 LDAP 服务器有速率限制，在组同步过程中可能会达到该限制。有关更多信息，请查看速率限制文档。

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

导出 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 实例之间的连接问题，请尝试通过设置组同步工作进程间隔大于默认的 1 小时，来减少 GitLab 执行 LDAP 组同步的频率。

添加组链接

有关使用 CN 和过滤器添加组链接的信息，请参阅 GitLab 组文档。

将自定义管理员角色与 LDAP 组关联

有关使用 CN 和过滤器添加自定义管理员角色链接的信息，请参阅使用 LDAP 管理用户文档。

管理员同步

作为组同步的扩展，您可以自动管理全局 GitLab 管理员。为 admin_group 指定组 CN，该 LDAP 组的所有成员都将获得管理员权限。配置如下所示。

除非同时指定 group_base 和 admin_group，否则不会同步管理员。此外，只需指定 admin_group 的 CN（而非完整 DN）。另外，如果 LDAP 用户具有 admin 角色但不是 admin_group 组的成员， GitLab 会在同步时撤销其 admin 角色。

编辑 /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 值：

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。
在左侧边栏底部，选择 管理员区域。
选择 设置 > 通用。
展开 可见性和访问控制。
确保 锁定成员资格以进行 LDAP 同步 复选框已选中。

更改 LDAP 组同步设置管理

默认情况下，具有拥有者角色的组成员可以管理 LDAP 组同步设置。

GitLab 管理员可以撤销组拥有者的此权限：

配置 LDAP。
在左侧边栏底部，选择 管理员区域。
选择 设置 > 通用。
展开 可见性和访问控制。
确保 允许组拥有者管理 LDAP 相关设置 复选框未选中。

当禁用 允许组拥有者管理 LDAP 相关设置 时：

组拥有者无法更改顶级组和子组的 LDAP 同步设置。
实例管理员可以管理实例上所有组的 LDAP 组同步设置。

外部组

使用 external_groups 设置可以将属于这些组的所有用户标记为外部用户。组成员资格通过 LdapGroupSync 后台任务定期检查。

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

导出 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-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

GitLab Duo 组附加组件

duo_add_on_groups 设置可自动管理通过 LDAP 认证用户的 Duo 附加组件席位。此功能帮助组织根据 LDAP 组成员资格简化 GitLab Duo 席位分配流程。

要为组启用附加组件席位管理，您必须在 GitLab 实例中配置 duo_add_on_groups 设置：

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

导出 Helm 值：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

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

保存文件并应用新值：

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' => {
              'duo_add_on_groups' => ['duo_group_1', 'duo_group_2'],
          }
        }

保存文件并重启 GitLab：
```
docker compose up -d
```

编辑 /home/git/gitlab/config/gitlab.yml：

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

保存文件并重启 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 会为每个成员执行另一个 LDAP 查询以获取其完整 DN。这些查询使用基础 base、范围 “base object” 以及取决于是否设置了 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 在服务器时间每天凌晨 1:30 运行一次工作进程，根据 LDAP 检查并更新 GitLab 用户。

不要过于频繁地运行同步过程，因为这可能导致多个同步进程并发运行。大多数安装无需修改同步计划。更多信息，请参阅 LDAP 安全文档。

您可以通过设置以下 cron 格式的配置值来手动配置 LDAP 用户同步时间。如需要，可以使用 crontab 生成器。以下示例展示如何设置 LDAP 用户同步每 12 小时在整点运行一次。

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

导出 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 生成器。

不要过于频繁地启动同步过程，因为这可能导致多个同步进程并发运行。大多数安装无需修改同步计划。

您可以通过设置以下配置值来手动配置 LDAP 组同步时间。以下示例展示如何设置组同步每两小时在整点运行一次。

编辑 /etc/gitlab/gitlab.rb：

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

保存文件并重新配置 GitLab：
```
sudo gitlab-ctl reconfigure
```

导出 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 故障排除指南。