{{< details >}}

  1. Tier: 专业版，旗舰版
  2. Offering: 私有化部署

{{< /details >}}

如果您已经配置 LDAP 以与极狐GitLab 一起使用，极狐GitLab 可以自动同步用户和群组。

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

您可以更改同步发生的时间。

带有速率限制的 LDAP 服务器

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

极狐GitLab 每次查询 LDAP 服务器：

  1. 在计划的用户同步过程中查询每个用户。
  2. 在计划的群组同步过程中查询每个群组。

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

如果 LDAP 服务器配置了速率限制，并且在以下情况下达到该限制：

  1. 用户同步过程，LDAP 服务器会响应错误代码，极狐GitLab 会阻止该用户。
  2. 群组同步过程，LDAP 服务器会响应错误代码，极狐GitLab 会移除该用户的群组成员资格。

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

用户同步

{{< history >}}

  1. 防止 LDAP 用户的个人资料名称同步在极狐GitLab 15.11 中引入。

{{< /history >}}

极狐GitLab 每天运行一次工作程序，以根据 LDAP 检查和更新极狐GitLab 用户。

该过程执行以下访问检查：

  1. 确保用户仍在 LDAP 中。
  2. 如果 LDAP 服务器是 Active Directory，请确保用户处于活动状态（不是阻止/禁用状态）。仅当在 LDAP 配置中设置 active_directory: true 时才执行此检查。

在 Active Directory 中，如果用户账户控制属性（userAccountControl:1.2.840.113556.1.4.803）设置了位 2，则用户被标记为禁用/阻止。

该过程还会更新以下用户信息：

  1. 名称。由于同步问题，如果启用了阻止用户更改其个人资料名称或设置了 sync_name 为 false，则不会同步 name。
  2. 电子邮件地址。
  3. 如果设置了 sync_ssh_keys，则同步 SSH 公钥。
  4. 如果启用了 Kerberos，则同步 Kerberos 身份。

{{< alert type=”note” >}}

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

{{< /alert >}}

同步 LDAP 用户的个人资料名称

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

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

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

  1. 编辑 /etc/gitlab/gitlab.rb：

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

  2. 保存文件并重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

  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

{{< /tab >}}

{{< tab title=”Docker” >}}

  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

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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

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

  2. 保存文件并重新启动极狐GitLab：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}

被阻止的用户

如果以下任一情况发生，用户将被阻止：

  1. 访问检查失败，并且该用户在极狐GitLab 中被设置为 ldap_blocked 状态。
  2. 用户登录时 LDAP 服务器不可用。

如果用户被阻止，则该用户无法登录、推送或拉取代码。

当满足以下所有条件时，用户登录时会取消阻止被阻止的用户：

  1. 所有访问检查条件都为真。
  2. 用户登录时 LDAP 服务器可用。

如果在运行 LDAP 用户同步时 LDAP 服务器不可用，则所有用户都会被阻止。

{{< alert type=”note” >}}

如果由于在运行 LDAP 用户同步时 LDAP 服务器不可用而导致所有用户被阻止，则后续的 LDAP 用户同步不会自动取消阻止这些用户。

{{< /alert >}}

群组同步

如果您的 LDAP 支持 memberof 属性，当用户第一次登录时，极狐GitLab 会触发用户应属于的群组的同步。这样，他们无需等待每小时同步即可获得对其群组和项目的访问权限。

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

group_base 配置应该是一个基本的 LDAP “容器”，例如“组织”或“组织单位”，包含应对极狐GitLab 可用的 LDAP 群组。例如，group_base 可以是 ou=groups,dc=example,dc=com。在配置文件中，它看起来如下所示。

{{< alert type=”note” >}}

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

{{< /alert >}}

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

  1. 编辑 /etc/gitlab/gitlab.rb：

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

  2. 保存文件并重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

  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

{{< /tab >}}

{{< tab title=”Docker” >}}

  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

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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

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

  2. 保存文件并重新启动极狐GitLab：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}

为了利用群组同步，群组所有者或具有维护者角色的用户必须创建一个或多个 LDAP 群组链接。

{{< alert type=”note” >}}

如果您经常遇到 LDAP 服务器和极狐GitLab 实例之间的连接问题，请尝试通过设置群组同步工作程序间隔来减少极狐GitLab 执行 LDAP 群组同步的频率，以超过 1 小时的默认值。

{{< /alert >}}

添加群组链接

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

管理员同步

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

{{< alert type=”note” >}}

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

{{< /alert >}}

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

  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

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

  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

{{< /tab >}}

{{< tab title=”Docker” >}}

  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

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

  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：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}

全局群组成员资格锁定

极狐GitLab 管理员可以阻止群组成员邀请新成员加入其成员资格与 LDAP 同步的子群组。

全局群组成员资格锁定仅适用于配置了 LDAP 同步的顶级群组的子群组。没有用户可以修改为 LDAP 同步配置的顶级群组的成员资格。

启用全局群组成员资格锁定时：

  1. 只有管理员可以管理任何群组的成员资格，包括访问级别。
  2. 不允许用户与其他群组共享项目或邀请成员加入在群组中创建的项目。

要启用全局群组成员资格锁定：

  1. 配置 LDAP。
  2. 在左侧边栏的底部，选择 管理员。
  3. 选择 设置 > 常规。
  4. 展开 可见性和访问控制。
  5. 确保已选择 将成员资格锁定到 LDAP 同步 复选框。

更改 LDAP 群组同步设置管理

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

极狐GitLab 管理员可以从群组所有者中移除此权限：

  1. 配置 LDAP。
  2. 在左侧边栏的底部，选择 管理员。
  3. 选择 设置 > 常规。
  4. 展开 可见性和访问控制。
  5. 确保未选中 允许群组所有者管理与 LDAP 相关的设置 复选框。

禁用 允许群组所有者管理与 LDAP 相关的设置 时：

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

外部群组

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

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

  1. 编辑 /etc/gitlab/gitlab.rb：

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

  2. 保存文件并重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

  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

{{< /tab >}}

{{< tab title=”Docker” >}}

  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

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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

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

  2. 保存文件并重新启动极狐GitLab：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}

群组同步技术细节

本节概述了执行的 LDAP 查询以及您可以从群组同步中期望的行为。

如果其 LDAP 群组成员身份更改，群组成员的访问权限将从较高级别降级。例如，如果用户在群组中具有所有者角色，并且下一次群组同步显示他们应仅具有开发者角色，则将相应地调整其访问权限。唯一的例外是如果用户是群组中的最后一个所有者。群组需要至少一个所有者来履行管理职责。

支持的 LDAP 群组类型/属性

极狐GitLab 支持使用成员属性的 LDAP 群组：

  1. member
  2. submember
  3. uniquemember
  4. memberof
  5. memberuid

这意味着群组同步支持（至少）具有以下对象类的 LDAP 群组：

  1. groupOfNames
  2. posixGroup
  3. 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。

查询

  1. 每个 LDAP 群组最多查询一次，使用基于 group_base 的过滤器 (cn=<cn_from_group_link>)。
  2. 如果 LDAP 群组具有 memberuid 属性，极狐GitLab 会为每个成员执行另一个 LDAP 查询以获取每个用户的完整 DN。这些查询使用基于 base 的范围“基本对象”执行，并根据是否设置了 user_filter 来过滤。过滤器可能是 (uid=<uid_from_group>) 或 user_filter 的连接。

基准

群组同步的编写尽可能高效。数据被缓存，数据库查询被优化，LDAP 查询被最小化。最后一次基准测试显示了以下指标：

对于 20,000 个 LDAP 用户、11,000 个 LDAP 群组和 1,000 个极狐GitLab 群组，每个群组有 10 个 LDAP 群组链接：

  1. 初始同步（极狐GitLab 中没有分配的现有成员）耗时 1.8 小时
  2. 后续同步（检查成员身份，无写入）耗时 15 分钟

这些指标旨在提供基准，性能可能会因任何多个因素而异。此基准测试是极端的，大多数实例没有这么多的用户或群组。磁盘速度、数据库性能、网络和 LDAP 服务器响应时间会影响这些指标。

调整 LDAP 用户同步计划

默认情况下，极狐GitLab 每天在服务器时间 01:30 运行一次工作程序，以根据 LDAP 检查和更新极狐GitLab 用户。

{{< alert type=”warning” >}}

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

{{< /alert >}}

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

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

  1. 编辑 /etc/gitlab/gitlab.rb：

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

  2. 保存文件并重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

  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

{{< /tab >}}

{{< tab title=”Docker” >}}

  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

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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

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

  2. 保存文件并重新启动极狐GitLab：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}

调整 LDAP 群组同步计划

默认情况下，极狐GitLab 每小时整点运行一次群组同步过程。显示的值为 cron 格式。

{{< alert type=”warning” >}}

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

{{< /alert >}}

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

{{< tabs >}}

{{< tab title=”Linux 软件包 (Omnibus)” >}}

  1. 编辑 /etc/gitlab/gitlab.rb：

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

  2. 保存文件并重新配置极狐GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=”Helm chart (Kubernetes)” >}}

  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

{{< /tab >}}

{{< tab title=”Docker” >}}

  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

{{< /tab >}}

{{< tab title=”自编译 (源代码)” >}}

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

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

  2. 保存文件并重新启动极狐GitLab：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}

故障排除

请参阅我们的LDAP 故障排除管理员指南。