极狐 GitLab

将 LDAP 与极狐GitLab 集成

Tier: 基础版，专业版，旗舰版

Offering: 私有化部署

极狐GitLab 支持与 LDAP - 轻量级目录访问协议 集成，以实现用户认证。

该集成适用于大多数符合 LDAP 标准的目录服务器，包括：

  • Microsoft Active Directory。
  • Apple Open Directory。
  • OpenLDAP。
  • 389 Server。
极狐GitLab 不支持 [Microsoft Active Directory Trusts](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771568(v=ws.10))。

通过 LDAP 添加的用户：

在以下情况下，LDAP 专有名称 (DN) 会与现有极狐GitLab 用户关联：

  • 现有用户首次使用 LDAP 登录极狐GitLab。
  • LDAP 邮箱地址是现有极狐GitLab 用户的主要邮箱地址。如果极狐GitLab 用户数据库中找不到该 LDAP 邮箱属性，则会创建一个新用户。

如果现有极狐GitLab 用户希望启用 LDAP 登录，应执行以下操作：

  1. 确认其极狐GitLab 邮箱地址与 LDAP 邮箱地址一致。
  2. 使用其 LDAP 凭证登录极狐GitLab。
用户将 LDAP 身份关联至极狐GitLab 账户后，将不能再使用标准的用户名和密码认证流程。此后用户必须使用其 LDAP 凭证进行认证。尝试使用用户名和密码登录将导致 [无效登录或密码错误](ldap-troubleshooting.md#users-see-an-error-invalid-login-or-password)。

安全性#

极狐GitLab 会验证用户是否仍在 LDAP 中处于活跃状态。

以下情况下的用户将被视为在 LDAP 中处于非活跃状态：

  • 已完全从目录中移除。
  • 位于配置的 base DN 或 user_filter 搜索范围之外。
  • 在 Active Directory 中通过用户账户控制属性被标记为禁用或停用。这意味着属性 userAccountControl:1.2.840.113556.1.4.803 的第 2 位已置位。

要检查用户在 LDAP 中处于活跃还是非活跃状态，可使用以下 PowerShell 命令并配合 Active Directory 模块 来检查 Active Directory：

powershell
Get-ADUser -Identity <username> -Properties userAccountControl | Select-Object Name, userAccountControl

极狐GitLab 在以下时机检查 LDAP 用户状态：

  • 使用任何认证提供方登录时。
  • 对于活跃的 Web 会话或使用令牌、SSH 密钥的 Git 请求，每小时检查一次。
  • 使用 LDAP 用户名和密码通过 HTTP 执行 Git 操作时。
  • 在 用户同步 期间，每天检查一次。

如果用户不再在 LDAP 中处于活跃状态，他们将被：

  • 强制下线。
  • 置于 ldap_blocked 状态。
  • 无法使用任何认证提供方登录，直到其在 LDAP 中重新激活。

安全风险#

您应仅在以下情况下使用 LDAP 集成，即您的 LDAP 用户无法：

  • 在 LDAP 服务器上修改其 mail、email 或 userPrincipalName 属性。这些用户可能会接管您极狐GitLab 服务器上的任何账户。
  • 共享邮箱地址。具有相同邮箱地址的 LDAP 用户可以共享同一个极狐GitLab 账户。

配置 LDAP#

前提条件：

  • 无论是否使用该邮箱地址登录，使用 LDAP 都必须配置邮箱地址。

要配置 LDAP，您需要在配置文件中编辑设置：

需要编辑的文件取决于您的极狐GitLab 安装方式：

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

    ruby
    1gitlab_rails['ldap_enabled'] = true
2gitlab_rails['ldap_servers'] = {
3  'main' => {
4    'label' => 'LDAP',
5    'host' => 'ldap.mydomain.com',
6    'port' => 636,
7    'uid' => 'sAMAccountName',
8    'bind_dn' => 'CN=Gitlab,OU=Users,DC=domain,DC=com',
9    'password' => '<bind_user_password>',
10    'encryption' => 'simple_tls',
11    'verify_certificates' => true,
12    'timeout' => 10,
13    'active_directory' => false,
14    'user_filter' => '(employeeType=developer)',
15    'base' => 'dc=example,dc=com',
16    'lowercase_usernames' => 'false',
17    'retry_empty_result_with_codes' => [80],
18    'allow_username_or_email_login' => false,
19    'block_auto_created_users' => false
20  }
21}

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

    shell
    sudo gitlab-ctl reconfigure

配置 LDAP 后，使用 LDAP 检查 Rake 任务 测试配置。

基本配置设置#

以下基本设置可用：

设置是否必需类型描述
label 是StringLDAP 服务器的人类可读名称。将在登录页面显示。示例：'Paris' 或 'Acme, Ltd.'
host 是StringLDAP 服务器的 IP 地址或域名。如果定义了 hosts，则此设置被忽略。示例：'ldap.mydomain.com'
port 是Integer连接到 LDAP 服务器的端口。如果定义了 hosts，则此设置被忽略。示例：389 或 636（SSL）
uid 是String映射到用户登录用户名的 LDAP 属性。应该是属性名，而不是属性值。不会影响极狐GitLab 用户名（请参阅 属性配置部分）。示例：'sAMAccountName'、'uid' 或 'userPrincipalName'
base 是String搜索用户的基准 DN。示例：'ou=people,dc=gitlab,dc=example' 或 'DC=mydomain,DC=com'
encryption 是String加密方法（method 键已弃用，推荐使用 encryption）。可选值：'start_tls'、'simple_tls' 或 'plain'。simple_tls 对应 LDAP 库中的“Simple TLS”。start_tls 对应 StartTLS，与普通 TLS 不同。若指定 simple_tls，通常使用 636 端口；而 start_tls (StartTLS) 使用 389 端口。plain 也使用 389 端口。
hosts 否主机和端口对的数组用于建立连接的主机和端口对数组。每个配置的服务器应具有相同的数据库。此设置并非用于配置多个独立的 LDAP 服务器，而是用于配置故障转移。主机将按配置顺序依次尝试。示例：[['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]
bind_dn 否String用于绑定的用户的完整 DN。示例：'america\momo' 或 'CN=Gitlab,OU=Users,DC=domain,DC=com'
password 否String绑定用户的密码。
verify_certificates 否Boolean默认为 true。当加密方法为 start_tls 或 simple_tls 时，启用 SSL 证书验证。设置为 false 时，不验证 LDAP 服务器的 SSL 证书。
timeout 否Integer默认为 10。LDAP 查询超时时间（秒）。有助于避免 LDAP 服务器无响应时请求被阻塞。值为 0 表示无超时限制。
active_directory 否Boolean指定 LDAP 服务器是否为 Active Directory 服务器。对于非 AD 服务器，会跳过特定于 AD 的查询。如果您的 LDAP 服务器不是 AD，请设置为 false。
allow_username_or_email_login 否Boolean默认为 false。如果启用，极狐GitLab 会忽略用户在登录时提供的 LDAP 用户名中第一个 @ 之后的所有内容。如果您在 Active Directory 上使用 uid: 'userPrincipalName'，必须禁用此设置，因为 userPrincipalName 包含 @ 符号。
block_auto_created_users 否Boolean默认为 false。要严格控制极狐GitLab 安装中的计费用户数量，请启用此设置，使新创建的用户在管理员审核前保持被阻止状态。
user_filter 否String过滤 LDAP 用户。遵循 RFC 4515 格式。极狐GitLab 不支持 omniauth-ldap 的自定义过滤语法。user_filter 字段语法示例：

- '(employeeType=developer)'
- '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'
lowercase_usernames 否Boolean如果启用，极狐GitLab 会将用户名转换为小写。
retry_empty_result_with_codes 否Array当 LDAP 查询结果/内容为空时，尝试重试操作的响应码数组。对于 Google Secure LDAP，请将此值设置为 [80]。
极狐GitLab 不受 Microsoft 安全公告 [ADV190023](https://msrc.microsoft.com/update-guide/en-us/advisory/ADV190023) 中针对 Microsoft Active Directory 服务引入的更严格绑定要求的影响。更多信息，请参阅 [议题 201894](https://gitlab.com/gitlab-org/gitlab/-/issues/201894#note_2807513217)。

SSL 配置设置#

您可以在 tls_options 名称/值对下配置 SSL 配置设置。以下均为可选设置：

设置描述示例
ca_file指定包含 PEM 格式 CA 证书的文件的路径，例如，如果您需要使用内部 CA。'/etc/ca.pem'
ssl_version指定 OpenSSL 使用的 SSL 版本，如果 OpenSSL 的默认版本不合适。'TLSv1_1'
ciphers在与 LDAP 服务器通信时使用的特定 SSL 加密套件。'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'
cert客户端证书。'-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'
key客户端私钥。'-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'

以下示例演示如何在 tls_options 中设置 ca_file 和 ssl_version：

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

    ruby
    1gitlab_rails['ldap_enabled'] = true
2gitlab_rails['ldap_servers'] = {
3  'main' => {
4    'label' => 'LDAP',
5    'host' => 'ldap.mydomain.com',
6    'port' => 636,
7    'uid' => 'sAMAccountName',
8    'encryption' => 'simple_tls',
9    'base' => 'dc=example,dc=com',
10    'tls_options' => {
11      'ca_file' => '/path/to/ca_file.pem',
12      'ssl_version' => 'TLSv1_2'
13    }
14  }
15}

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

    shell
    sudo gitlab-ctl reconfigure

属性配置设置#

极狐GitLab 使用以下 LDAP 属性为 LDAP 用户创建账户。指定的属性可以是：

  • 字符串形式的属性名称。例如，'mail'。
  • 按顺序尝试的属性名称数组。例如，['mail', 'email']。

用户的 LDAP 登录凭据是 指定为 uid 的 LDAP 属性。

以下所有 LDAP 属性均为可选。如果您定义这些属性，则无需全部指定；您只需要指定与默认值不同的属性即可。例如，如果您指定了 username，则无需指定其他属性，将采用默认值。

如果您要定义其中任何属性，必须将其放在 attributes 哈希中。

设置描述默认值
username极狐GitLab 账户使用的 @username。如果值包含邮箱地址，则极狐GitLab 用户名是 @ 符号之前的部分。默认为 指定为 uid 的 LDAP 属性 (['uid', 'userid', 'sAMAccountName'])。
email用户邮箱的 LDAP 属性。['mail', 'email', 'userPrincipalName']
name用户显示名称的 LDAP 属性。如果 name 为空，则从 first_name 和 last_name 组合全名。'cn' 或 'displayName' 属性通常包含全名。或者，您可以通过指定一个不存在的属性（如 'somethingNonExistent'）来强制使用 first_name 和 last_name。'cn'
first_name用户名字的 LDAP 属性。当为 name 配置的属性不存在时使用。'givenName'
last_name用户姓氏的 LDAP 属性。当为 name 配置的属性不存在时使用。'sn'

示例配置：使用 displayName 作为用户名，并使用属性数组作为 email：

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

    ruby
    1gitlab_rails['ldap_servers'] = {
2  'main' => {
3    # 其他配置设置 ...
4    'attributes' => {
5      'username' => 'uid',
6      'email' => ['mail', 'email', 'userPrincipalName'],
7      'name' => 'displayName',
8      'first_name' => 'givenName',
9      'last_name' => 'sn'
10    }
11  }
12}

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

    shell
    sudo gitlab-ctl reconfigure

LDAP 同步配置设置#

Tier: 专业版，旗舰版

Offering: 私有化部署

这些 LDAP 同步配置设置均为可选，除了 group_base，后者在

（这句话似乎未完整，在给出的原文中是："These LDAP sync configuration settings are optional, excluding group_base which required when external_groups is configured:" 但原文在此截断了。按规则，我们保留原文截断处，可能需要等待下一部分。但按照翻译要求，我们保持不完整部分，不添加内容。）

因此，这一句翻译为：

这些 LDAP 同步配置设置均为可选，除了 group_base，后者在配置 external_groups 时是必需的：

（但原文没有继续列出设置，需等第二部分。）这些 LDAP 同步配置设置均为可选，除了 group_base，后者在配置 external_groups 时是必需的：

设置描述示例
group_base用于搜索群组的基础 DN。所有有效群组的 DN 中都包含此基础 DN。'ou=groups,dc=gitlab,dc=example'
admin_group包含极狐GitLab 管理员的群组的 CN。不是 cn=administrators 或完整 DN。'administrators'
external_groups包含应被视为外部用户的群组的 CN 数组。不是 cn=interns 或完整 DN。['interns', 'contractors']
sync_ssh_keys包含用户公共 SSH 密钥的 LDAP 属性。'sshPublicKey' 或 false（如果未设置）
如果 Sidekiq 配置在与 Rails 服务器不同的服务器上，则必须将 LDAP 配置添加到每个 Sidekiq 服务器，以便 LDAP 同步正常工作。

使用多个 LDAP 服务器#

Tier: 专业版，旗舰版

Offering: 私有化部署

如果用户在多个 LDAP 服务器上，可以配置极狐GitLab 使用它们。要添加额外的 LDAP 服务器：

  1. 复制 main LDAP 配置。
  2. 使用额外服务器的详细信息编辑每个复制的配置。
    • 为每个额外的服务器选择一个不同的提供者 ID，如 main、secondary 或 tertiary。使用小写字母数字字符。极狐GitLab 使用提供者 ID 将每个用户与特定的 LDAP 服务器关联。
    • 为每个条目使用唯一的 label 值。这些值用于登录页面上的选项卡名称。

以下示例展示了如何以最小配置配置三个 LDAP 服务器：

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

    ruby
    1gitlab_rails['ldap_enabled'] = true
2gitlab_rails['ldap_servers'] = {
3  'main' => {
4    'label' => '极狐GitLab AD',
5    'host' => 'ad.mydomain.com',
6    'port' => 636,
7    'uid' => 'sAMAccountName',
8    'encryption' => 'simple_tls',
9    'base' => 'dc=example,dc=com',
10  },
11
12  'secondary' => {
13    'label' => '极狐GitLab Secondary AD',
14    'host' => 'ad-secondary.mydomain.com',
15    'port' => 636,
16    'uid' => 'sAMAccountName',
17    'encryption' => 'simple_tls',
18    'base' => 'dc=example,dc=com',
19  },
20
21  'tertiary' => {
22    'label' => '极狐GitLab Tertiary AD',
23    'host' => 'ad-tertiary.mydomain.com',
24    'port' => 636,
25    'uid' => 'sAMAccountName',
26    'encryption' => 'simple_tls',
27    'base' => 'dc=example,dc=com',
28  }
29}

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

    shell
    sudo gitlab-ctl reconfigure

此示例生成一个登录页面，其中包含以下选项卡：

  • 极狐GitLab AD。
  • 极狐GitLab Secondary AD。
  • 极狐GitLab Tertiary AD。

设置 LDAP 用户过滤器#

要将所有极狐GitLab 访问限制为 LDAP 服务器上的 LDAP 用户子集，首先缩小配置的 base。但是，如果需要进一步过滤用户，可以设置 LDAP 用户过滤器。过滤器必须符合 RFC 4515。

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

    ruby
    gitlab_rails['ldap_servers'] = {
  'main' => {
    'user_filter' => '(employeeType=developer)'
  }
}

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

    shell
    sudo gitlab-ctl reconfigure

要将访问限制为 Active Directory 群组的嵌套成员，请使用以下语法：

plaintext
(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)

有关 LDAP_MATCHING_RULE_IN_CHAIN 过滤器的更多信息，请参阅 搜索过滤器语法。

用户过滤器中对嵌套成员的支持不应与 群组同步嵌套群组 支持混淆。

极狐GitLab 不支持 OmniAuth LDAP 使用的自定义过滤器语法。

转义 user_filter 中的特殊字符#

user_filter DN 可以包含特殊字符。例如：

  • 逗号：

    plaintext
    OU=GitLab, Inc,DC=gitlab,DC=com

  • 开括号和闭括号：

    plaintext
    OU=GitLab (Inc),DC=gitlab,DC=com

这些字符必须按照 RFC 4515 中的说明进行转义。

  • 用 \2C 转义逗号。例如：

    plaintext
    OU=GitLab\2C Inc,DC=gitlab,DC=com

  • 用 \28 转义开括号，用 \29 转义闭括号。例如：

    plaintext
    OU=GitLab \28Inc\29,DC=gitlab,DC=com

启用 LDAP 用户名小写#

某些 LDAP 服务器，根据其配置，可能返回大写用户名。 这可能导致一些令人困惑的问题，例如创建带有大写名称的链接或命名空间。

极狐GitLab 可以通过启用配置选项 lowercase_usernames 自动将 LDAP 服务器提供的用户名转为小写。默认情况下，此配置选项为 false。

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

    ruby
    gitlab_rails['ldap_servers'] = {
  'main' => {
    'lowercase_usernames' => true
  }
}

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

    shell
    sudo gitlab-ctl reconfigure

禁用 LDAP Web 登录#

当首选 SAML 等替代方案时，阻止通过 Web UI 使用 LDAP 凭据可能很有用。这允许 LDAP 用于群组同步，同时允许你的 SAML 身份提供者处理额外的检查，如自定义双重认证。

当 LDAP Web 登录被禁用时，用户不会在登录页面上看到 LDAP 选项卡。 这不会禁用使用 LDAP 凭据进行 Git 访问。

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

    ruby
    gitlab_rails['prevent_ldap_sign_in'] = true

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

    shell
    sudo gitlab-ctl reconfigure

为极狐GitLab 提供智能卡认证#

有关将智能卡与 LDAP 服务器和极狐GitLab 一起使用的更多信息，请参阅 智能卡认证。

使用加密凭据#

你可以选择使用加密文件存储 LDAP 凭据，而不是将 LDAP 集成凭据以明文形式存储在配置文件中。

前提条件：

  • 要使用加密凭据，你必须首先启用 加密配置。

LDAP 的加密配置存在于加密的 YAML 文件中。文件的未加密内容应该是 LDAP 配置中 servers 块的机密设置的子集。

加密文件支持的配置项有：

  • bind_dn
  • password

  1. 如果最初你的 LDAP 配置在 /etc/gitlab/gitlab.rb 中如下所示：

    ruby
    1  gitlab_rails['ldap_servers'] = {
2    'main' => {
3      'bind_dn' => 'admin',
4      'password' => '123'
5    }
6  }

  2. 编辑加密的机密：

    shell
    sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim

  3. 输入 LDAP 机密的未加密内容：

    yaml
    main:
  bind_dn: admin
  password: '123'

  4. 编辑 /etc/gitlab/gitlab.rb 并删除 bind_dn 和 password 的设置。

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

    shell
    sudo gitlab-ctl reconfigure

更新 LDAP DN 和电子邮件#

当 LDAP 服务器在极狐GitLab 中创建用户时，用户的 LDAP DN 作为标识符链接到其极狐GitLab 帐户。

当用户尝试使用 LDAP 登录时，极狐GitLab 尝试使用保存在该用户帐户上的 DN 查找用户。

  • 如果极狐GitLab 通过 DN 找到用户并且用户的电子邮件地址：
    • 与极狐GitLab 帐户的电子邮件地址匹配，极狐GitLab 不会采取进一步操作。
    • 已更改，极狐GitLab 会更新其记录的用户电子邮件以匹配 LDAP 中的电子邮件。
  • 如果极狐GitLab 无法通过 DN 找到用户，它会尝试通过电子邮件查找用户。如果极狐GitLab：
    • 通过电子邮件找到用户，极狐GitLab 会更新存储在用户极狐GitLab 帐户中的 DN。现在两个值都与 LDAP 中存储的信息匹配。
    • 无法通过电子邮件地址找到用户（DN 和 电子邮件地址均已更改），请参阅 用户 DN 和电子邮件已更改。

禁用匿名 LDAP 认证#

极狐GitLab 不支持 TLS 客户端认证。在你的 LDAP 服务器上完成这些步骤。

  1. 禁用匿名认证。
  2. 启用以下认证类型之一：
    • 简单认证。
    • 简单认证和安全层 (SASL) 认证。

你的 LDAP 服务器中的 TLS 客户端认证设置不能是强制性的，并且客户端不能通过 TLS 协议进行认证。

从 LDAP 删除的用户#

从 LDAP 服务器删除的用户：

但是，这些用户可以继续使用 SSH 进行 Git 操作，直到下次 LDAP 检查缓存运行。

要立即删除帐户，你可以手动 阻止用户。

更新用户电子邮件地址#

当使用 LDAP 登录时，LDAP 服务器上的电子邮件地址被视为用户的真实来源。

更新用户电子邮件地址必须在管理用户的 LDAP 服务器上完成。极狐GitLab 的电子邮件地址会在以下情况下更新：

更新后的用户之前的电子邮件地址将成为辅助电子邮件地址，以保留该用户的提交历史。

你可以在我们的 LDAP 故障排除部分 中找到有关用户更新预期行为的更多详细信息。

Google Secure LDAP#

Google Cloud Identity 提供了一项 Secure LDAP 服务，可以配置为极狐GitLab 进行认证和群组同步。 有关详细配置说明，请参阅 Google Secure LDAP。

同步用户和群组#

有关在 LDAP 和极狐GitLab 之间同步用户和群组的更多信息，请参阅 LDAP 同步。

从 LDAP 迁移到 SAML#

  1. 添加 SAML 配置 到：

  2. 可选。从登录页面禁用 LDAP 认证。

  3. 可选。要解决用户链接问题，你可以首先 删除这些用户的 LDAP 身份。

  4. 确认用户能够登录其帐户。如果用户无法登录，请检查该用户的 LDAP 是否仍然存在，如有必要将其删除。如果此问题仍然存在，请检查日志以识别问题。

  5. 在配置文件中，更改：

    • omniauth_auto_link_user 为仅 saml。
    • omniauth_auto_link_ldap_user 为 false。
    • ldap_enabled 为 false。 你也可以注释掉 LDAP 提供者设置。

故障排除#

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