通用 LDAP 设置

极狐GitLab 与 LDAP 集成,以支持用户身份验证。

此集成适用于大多数 LDAP 兼容目录服务器,包括:

通过 LDAP 添加的用户:

  • 通常使用许可席位。
  • 可以使用他们的极狐GitLab 用户名或电子邮件和 LDAP 密码,对 Git 进行身份验证,即使 Git 的密码身份验证已禁用。

在以下情况下,LDAP DN 与现有的极狐GitLab 用户相关联:

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

如果现有的极狐GitLab 用户想要为自己启用 LDAP 登录,他们应该:

  1. 检查他们的极狐GitLab 电子邮件地址是否与他们的 LDAP 电子邮件地址匹配。
  2. 使用他们的 LDAP 凭据登录极狐GitLab。

安全

极狐GitLab 有多种机制来验证用户在 LDAP 中是否仍然处于活动状态。如果用户在 LDAP 中不再处于活动状态,他们将处于 ldap_blocked 状态并被注销。在 LDAP 中重新激活之前,他们无法使用任何身份验证提供程序登录。

用户在以下情况下被视为在 LDAP 中处于非活动状态:

  • 从目录中完全删除。
  • 驻留在配置的 base DN 或 user_filter 搜索之外。
  • 通过用户帐户控制属性在 Active Directory 中标记为禁用或停用。这意味着属性 userAccountControl:1.2.840.113556.1.4.803 设置了第 2 位。

出现以下情况,检查所有 LDAP 用户的状态:

  • 使用任何身份验证提供程序登录时。在 14.4 及更早版本中,仅在直接使用 LDAP 登录时检查状态。
  • 每小时一次,用于使用令牌或 SSH 密钥的活动 Web 会话或 Git 请求。
  • 使用 LDAP 用户名和密码通过 HTTP 请求执行 Git 时。
  • 用户同步期间每天一次。

安全风险

您应该只使用 LDAP 集成,如果您的 LDAP 用户不能:

  • 更改他们在 LDAP 服务器上的 mailemailuserPrincipalName 属性。这些用户可能会接管您的极狐GitLab 服务器上的任何帐户。
  • 共享电子邮件地址。具有相同电子邮件地址的 LDAP 用户可以共享相同的极狐GitLab 帐户。

配置

要启用 LDAP 集成,当使用 Omnibus GitLab 时,您必须在 /etc/gitlab/gitlab.rb 中添加 LDAP 服务器设置;当使用源安装时,您需要在 /home/git/gitlab/config/gitlab.yml 中添加 LDAP 服务器设置。

有一个 Rake 任务可用于检查 LDAP 配置。使用下方文档配置 LDAP 后,请参阅 LDAP 检查 Rake 任务获取更多信息。

noteencryption 的值 simple_tls 对应于 LDAP 库中的“Simple TLS”。start_tls 对应于 StartTLS,不要与常规 TLS 混淆。通常,如果您指定 simple_tls 在端口 636 上,而 start_tls(StartTLS)将在端口 389 上。plain 也在端口 389 上运行。删除的值:tls 被替换为 start_tlsssl 被替换为 simple_tls

LDAP 用户必须设置一个电子邮件地址,无论是否用于登录。

配置案例

Omnibus 配置

gitlab_rails['ldap_enabled'] = true
gitlab_rails['prevent_ldap_sign_in'] = false
gitlab_rails['ldap_servers'] = {
'main' => {
  'label' => 'LDAP',
  'host' =>  'ldap.mydomain.com',
  'port' => 389,
  'uid' => 'sAMAccountName',
  'encryption' => 'simple_tls',
  'verify_certificates' => true,
  'bind_dn' => '_the_full_dn_of_the_user_you_will_bind_with',
  'password' => '_the_password_of_the_bind_user',
  'tls_options' => {
    'ca_file' => '',
    'ssl_version' => '',
    'ciphers' => '',
    'cert' => '',
    'key' => ''
  },
  'timeout' => 10,
  'active_directory' => true,
  'allow_username_or_email_login' => false,
  'block_auto_created_users' => false,
  'base' => 'dc=example,dc=com',
  'user_filter' => '',
  'attributes' => {
    'username' => ['uid', 'userid', 'sAMAccountName'],
    'email' => ['mail', 'email', 'userPrincipalName'],
    'name' => 'cn',
    'first_name' => 'givenName',
    'last_name' => 'sn'
  },
  'lowercase_usernames' => false,

  # EE Only
  'group_base' => '',
  'admin_group' => '',
  'external_groups' => [],
  'sync_ssh_keys' => false
  }
}

源安装配置

production:
  # snip...
  ldap:
    enabled: false
    prevent_ldap_sign_in: false
    servers:
      main:
        label: 'LDAP'
        ...

基本配置

hosts 配置设置引入于 14.7 版本。

您可以配置以下二者之一:

  • 使用 hostport 的单个 LDAP 服务器。
  • 多 LDAP 服务器使用 hosts。此设置优先于 hostport。系统尝试按指定的顺序使用 LDAP 服务器,并使用第一个可访问的 LDAP 服务器。

以下配置设置可用:

配置项 说明 是否必须配置 举例
label LDAP 服务器的人性化名称。在登录页面展示。 Yes 'Paris' or 'Acme, Ltd.'
host LDAP 服务器的 IP 地址或域名。当 hosts 被定义时被忽略。 Yes 'ldap.mydomain.com'
port 与 LDAP 服务器连接的端口。类型为整数而非字符串。当 hosts 被定义时被忽略。 Yes 389636 (用于 SSL)
hosts(14.7 及更高版本) 一个包含用于打开连接的主机和端口对数组。 No [['ldap1.mydomain.com', 636], ['ldap2.mydomain.com', 636]]
uid 用户名的 LDAP 属性。应该是属性,而不是映射到 uid 的值。 Yes 'sAMAccountName''uid''userPrincipalName'
bind_dn 绑定用户的完整 DN。 No 'america\momo''CN=Gitlab,OU=Users,DC=domain,DC=com'
password 绑定用户的密码。 No 'your_great_password'
encryption 加密方法。method 已废弃。 Yes 'start_tls''simple_tls''plain'
verify_certificates 如果加密方法为 start_tlssimple_tls,则启用 SSL 证书验证。如果设置为 false,则不会对 LDAP 服务器的 SSL 证书进行验证。默认为 true。 No boolean
timeout 为 LDAP 查询设置超时时间(以秒为单位)。当 LDAP 服务器无法响应时,有助于阻止请求。0 值表示没有超时(默认值:10 No 1030
active_directory 该设置指定 LDAP 服务器是否为 Active Directory LDAP 服务器。对于非 AD 服务器,会跳过 AD 特定查询。如果您的 LDAP 服务器不是 AD,请将其设置为 false。 No boolean
allow_username_or_email_login 如果启用,系统将忽略用户在登录时提交的 LDAP 用户名中第一个 @ 之后的所有内容。如果您在 ActiveDirectory 上使用 uid: 'userPrincipalName',您必须禁用这个设置,因为 userPrincipalName 包含一个 @ No boolean
block_auto_created_users 为了严格控制计费用户数量,请启用此设置阻止新用户直到他们被管理员清除(默认值:false)。 No boolean
base 搜索用户的基础路径。 Yes 'ou=people,dc=gitlab,dc=example' or 'DC=mydomain,DC=com'
user_filter 过滤 LDAP 用户。格式:RFC 4515 注意: 不支持 omniauth-ldap 的自定义过滤器语法。 No 查阅用户过滤器的案例
lowercase_usernames 如果启用,系统转换用户名称为小写。 No boolean
retry_empty_result_with_codes 如果结果/内容为空,将尝试重试操作时的 LDAP 查询响应代码数组。 No [80]

用户过滤器样例

user_filter 字段语法的一些示例:

  • '(employeeType=developer)'
  • '(&(objectclass=user)(|(samaccountname=momo)(samaccountname=toto)))'

SSL 配置

配置项 说明 是否必须配置 举例
ca_file 例如,当您需要使用内部 CA 时,指定 PEM 格式的 CA 证书文件的路径。 No '/etc/ca.pem'
ssl_version 如果 OpenSSL 默认值不合适,指定 OpenSSL 的 SSL 版本。 No 'TLSv1_1'
ciphers 用于与 LDAP 服务器通信的特定 SSL 密码。 No 'ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2'
cert 客户凭证。 No '-----BEGIN CERTIFICATE----- <REDACTED> -----END CERTIFICATE -----'
key 客户私钥。 No '-----BEGIN PRIVATE KEY----- <REDACTED> -----END PRIVATE KEY -----'

属性配置

系统为 LDAP 用户创建账户时,使用的 LDAP 属性。指定的属性可以是字符串形式的属性名称(例如,'mail'),也可以是要按顺序尝试的属性名称数组(例如,['mail', 'email'])。用户的 LDAP 登录时指定为 uid 的属性。

配置项 说明 是否必须配置 举例
username 用户名用于用户自己项目的路径 (例如 gitlab.example.com/username/project) ,以及在议题、合并请求和评论中提及时 (例如 @username)。如果 username 包含电子邮件地址, 则地址中 @ 之前的部分作为极狐GitLab 用户名。 No ['uid', 'userid', 'sAMAccountName']
email 用户电子邮件的 LDAP 属性。 No ['mail', 'email', 'userPrincipalName']
name 用户显示名称的 LDAP 属性。如果 name 为空, 完整的显示名称从 first_namelast_name 获取。 No 'cn''displayName' 属性通常带有全名。或者,您可以通过指定不存在的属性,例如 'somethingNonExistent',来强制使用 first_namelast_name
first_name 用户 first name 的 LDAP 属性。当 name 属性不存在时使用。 No 'givenName'
last_name 用户 last name 的 LDAP 属性。当 name 属性不存在时使用。 No 'sn'

LDAP 同步配置

配置项 说明 是否必须配置 举例
group_base 搜索用户组的基础路径。 No 'ou=groups,dc=gitlab,dc=example'
admin_group 包含 GitLab 管理员的组的 CN。注意:不是cn=administrators 或完整的DN。 No 'administrators'
external_groups 包含应被视为外部用户的组 CN 数组。 注意:不是 cn=interns 或完整的 DN。 No ['interns', 'contractors']
sync_ssh_keys 包含用户的公共 SSH 密钥的 LDAP 属性。 No 'sshPublicKey' 或者 false(如果未设置)。

使用多 LDAP 服务器

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

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

多 LDAP 服务器示例

下面的例子展示了如何在 gitlab.rb 中配置三个 LDAP 服务器:

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
'main' => {
  'label' => 'GitLab AD',
  'host' =>  'ad.example.org',
  'port' => 636,
  ...
  },

'secondary' => {
  'label' => 'GitLab Secondary AD',
  'host' =>  'ad-secondary.example.net',
  'port' => 636,
  ...
  },

'tertiary' => {
  'label' => 'GitLab Tertiary AD',
  'host' =>  'ad-tertiary.example.net',
  'port' => 636,
  ...
  }

}

此示例生成以下登录页面:

Multiple LDAP servers sign in

设置 LDAP 用户过滤器

如果您想要 LDAP 服务器上的一部分 LDAP 用户具有访问极狐GitLab 的权限,第一步应该缩小配置的 base 范围。但是,有时必须进一步过滤用户。在这种情况下,您可以设置 LDAP 用户过滤器。过滤器必须符合 RFC 4515

Omnibus 配置

gitlab_rails['ldap_servers'] = {
'main' => {
  # snip...
  'user_filter' => '(employeeType=developer)'
  }
}

源安装配置

production:
  ldap:
    servers:
      main:
        # snip...
        user_filter: '(employeeType=developer)'

如果要限制对 Active Directory 组的嵌套成员的访问,请使用以下语法: plaintext (memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com) 获取 LDAP_MATCHING_RULE_IN_CHAIN 过滤器的更多信息,请参阅 Microsoft 搜索过滤器语法 文档。

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

转义特殊字符

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

  • 逗号:

    OU=GitLab, Inc,DC=gitlab,DC=com
    
  • 括号:

    OU=Gitlab (Inc),DC=gitlab,DC=com
    

    这些字符必须按照 RFC 4515 文档所述进行转义。

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

    OU=GitLab\2C Inc,DC=gitlab,DC=com
    
  • 同样地,使用 \28\29 转义括号。例如:

    OU=Gitlab \28Inc\29,DC=gitlab,DC=com
    

启用 LDAP 用户名小写

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

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

Omnibus 配置

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

    gitlab_rails['ldap_servers'] = {
    'main' => {
      # snip...
      'lowercase_usernames' => true
      }
    }
    
  2. 重新配置极狐GitLab 使更改生效。

Source configuration

  1. 编辑 config/gitlab.yaml:

    production:
      ldap:
        servers:
          main:
            # snip...
            lowercase_usernames: true
    
  2. 重启极狐GitLab 使更改生效。

禁用 LDAP web 登录

当首选 SAML 等替代方法时,阻止通过 Web UI 使用 LDAP 凭据会很有用。 这允许 LDAP 用于组同步,同时还允许您的 SAML 身份提供商处理额外的检查,如自定义 2FA。

禁用 LDAP Web 登录后,用户在登录页面上看不到 LDAP 选项。这不会禁用使用 LDAP 凭据进行 Git 访问。

Omnibus 配置

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

    gitlab_rails['prevent_ldap_sign_in'] = true
    
  2. 重新配置极狐GitLab 使配置生效。

源安装配置

  1. 编辑 config/gitlab.yaml

    production:
      ldap:
        prevent_ldap_sign_in: true
    
  2. 重启极狐GitLab 使配置生效。

使用加密凭证

除了将 LDAP 集成凭证以明文形式存储在配置文件中,您可以选择为 LDAP 凭证使用加密文件。要使用该功能,首先必须启用 GitLab 加密配置。

LDAP 的加密配置存放于加密的 YAML 文件中。默认情况下,该文件将在 shared/encrypted_configuration/ldap.yaml.enc 中创建,位置可以配置。

文件中的未加密内容应该是 LDAP 配置中 servers 的密钥配置。

加密文件的配置项有:

  • bind_dn
  • password

可以使用 LDAP 密钥编辑 Rake 命令配置加密内容。

Omnibus 配置

如果最初 LDAP 配置如下:

  1. /etc/gitlab/gitlab.rb 中:
    gitlab_rails['ldap_servers'] = {
    'main' => {
      # snip...
      'bind_dn' => 'admin',
      'password' => '123'
      }
    }
  1. 编辑加密密钥:

    sudo gitlab-rake gitlab:ldap:secret:edit EDITOR=vim
    
  2. LDAP 密钥的未加密内容应按以下案例配置:

    main:
      bind_dn: admin
      password: '123'
    
  3. 编辑 /etc/gitlab/gitlab.rb 并移除 bind_dnpassword 设置。

  4. 重新配置极狐GitLab 使更改生效。

源安装配置

如果最初 LDAP 配置如下:

  1. config/gitlab.yaml 中:

    production:
      ldap:
        servers:
          main:
            # snip...
            bind_dn: admin
            password: '123'
    
  2. 编辑加密密钥:

    bundle exec rake gitlab:ldap:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production
    
  3. LDAP 密钥的未加密内容应按以下案例配置:

    main:
     bind_dn: admin
     password: '123'
    
  4. 编辑 config/gitlab.yaml 并移除 bind_dnpassword 设置。

  5. 重启极狐GitLab 使更改生效。

禁用匿名 LDAP 身份验证

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

  1. 禁用匿名身份验证。
  2. 启用以下身份验证类型之一:
    • 简单的身份验证。
    • 简单身份验证和安全层 (SASL) 身份验证。

LDAP 服务器中的 TLS 客户端身份验证设置不能是强制性的,并且客户端无法使用 TLS 协议进行身份验证。

从 LDAP 中删除的用户

用户从 LDAP 服务器被删除:

  • 立即被阻止登录极狐GitLab。
  • 不再使用许可证。

但是,这些用户可以继续通过 SSH 使用 Git,直到下一次 LDAP 检查缓存运行。

要立即删除帐户,您可以手动阻止用户。

更新用户电子邮件地址

当使用 LDAP 登录时,LDAP 服务器上的电子邮件地址被认为是用户的真实来源。更新用户电子邮件地址必须在管理用户的 LDAP 服务器上完成。极狐GitLab 的电子邮件地址将更新于:

更新后的用户以前的电子邮件地址成为次要电子邮件地址,用来保留该用户的提交历史记录。