安全
- 安全风险
配置 LDAP
更新 LDAP DN 和电子邮件
禁用匿名 LDAP 身份验证
从 LDAP 中删除的用户
从 LDAP 删除用户
更新用户电子邮件地址
同步用户和群组
从 LDAP 移至 SAML
故障排查

极狐GitLab 和 LDAP 集成

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

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

Microsoft Active Directory。
Apple Open Directory。
Open LDAP。
389 Server。

极狐GitLab 并不支持 Microsoft Active Directory Trusts。

通过 LDAP 添加的用户：

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

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

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

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

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

安全

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

当用户处于以下状态时，会被任务是非活跃：

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

如要检查用户是否在 LDAP 中处于活跃或非活跃状态，用户可以使用如下 PowerShell 命令，并用 Active Directory Module 来检查 Active Directory：

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

极狐GitLab 检查 LDAP 用户的状态：

当使用任何认证的提供商进行登录。
对于使用令牌或 SSH 密钥的活跃网络会话或 Git 请求，每小时执行一次。
当使用 LDAP 用户名和密码执行 Git HTTP 请求。
在用户同步期间，每天一次。

如果用户在 LDAP 中不再活跃，他们将：

登出。
处于 ldap_blocked 状态。
不能够使用任何认证提供商进行登录，直到他们在 LDAP 被重新激活。

安全风险

您应该只使用 LDAP 集成，如果您的 LDAP 用户不能：

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

配置 LDAP

先决条件：

您必须有一个使用 LDAP 的邮件地址，无论你是否使用该电子邮件地址登录。

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

您的配置文件必须包含如下基础配置设置：
- label
- host
- port
- uid
- base
- encryption
您可以将如下选项设置包含在您的配置文件中：
您还可以配置 LDAP 以：

你所编辑的文件因你的极狐GitLab 配置而异：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' =>  'ldap.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'bind_dn' => 'CN=Gitlab,OU=Users,DC=domain,DC=com',
    'password' => '<bind_user_password>',
    'encryption' => 'simple_tls',
    'verify_certificates' => true,
    'timeout' => 10,
    'active_directory' => false,
    'user_filter' => '(employeeType=developer)',
    'base' => 'dc=example,dc=com',
    'lowercase_usernames' => 'false',
    'retry_empty_result_with_codes' => [80],
    'allow_username_or_email_login' => false,
    'block_auto_created_users' => false
  }
}

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

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'LDAP'
          host: 'ldap.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          bind_dn: 'CN=Gitlab,OU=Users,DC=domain,DC=com'
          password: '<bind_user_password>'
          encryption: 'simple_tls'
          verify_certificates: true
          timeout: 10
          active_directory: false
          user_filter: '(employeeType=developer)'
          base: 'dc=example,dc=com'
          lowercase_usernames: false
          retry_empty_result_with_codes: [80]
          allow_username_or_email_login: false
          block_auto_created_users: false

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

更多详情，可以查看如何为使用 Helm chart 安装的极狐GitLab 示例配置 LDAP。

:::TabTitle Docker

Edit docker-compose.yml:

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_enabled'] = true
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'label' => 'LDAP',
            'host' =>  'ldap.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'bind_dn' => 'CN=Gitlab,OU=Users,DC=domain,DC=com',
            'password' => '<bind_user_password>',
            'encryption' => 'simple_tls',
            'verify_certificates' => true,
            'timeout' => 10,
            'active_directory' => false,
            'user_filter' => '(employeeType=developer)',
            'base' => 'dc=example,dc=com',
            'lowercase_usernames' => 'false',
            'retry_empty_result_with_codes' => [80],
            'allow_username_or_email_login' => false,
            'block_auto_created_users' => false
          }
        }

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

:::TabTitle Self-compiled (source)

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

production: &base
  ldap:
    enabled: true
    servers:
      main:
        label: 'LDAP'
        host: 'ldap.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        bind_dn: 'CN=Gitlab,OU=Users,DC=domain,DC=com'
        password: '<bind_user_password>'
        encryption: 'simple_tls'
        verify_certificates: true
        timeout: 10
        active_directory: false
        user_filter: '(employeeType=developer)'
        base: 'dc=example,dc=com'
        lowercase_usernames: false
        retry_empty_result_with_codes: [80]
        allow_username_or_email_login: false
        block_auto_created_users: false

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

对于不同 LDAP 选项的更多详情，可以在 gitlab.yml.example 中查看 ladp 设置。

::EndTabs

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

基本配置

以下配置设置可用：

配置项	说明	是否必须配置	举例
`label`	LDAP 服务器的人性化名称。在登录页面展示。	Yes	`'Paris'` or `'Acme, Ltd.'`
`host`	LDAP 服务器的 IP 地址或域名。当 `hosts` 被定义时被忽略。	Yes	`'ldap.mydomain.com'`
`port`	与 LDAP 服务器连接的端口。类型为整数而非字符串。当 `hosts` 被定义时被忽略。	Yes	`389` 或 `636` (用于 SSL)
`hosts`	一个包含用于打开连接的主机和端口对数组。	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'`。`simple_tls` 对应于 LDAP 库中的 “Simple TLS”。`start_tls` 对应于 StartTLS，不要与常规 TLS 混淆。如果您指定 `simple_tls`，通常它在端口 636 上，而 `start_tls` (StartTLS) 将在端口 389 上。`plain` 也在端口 389 上运行。
`verify_certificates`	如果加密方法为 `start_tls` 或 `simple_tls`，则启用 SSL 证书验证。如果设置为 false，则不会对 LDAP 服务器的 SSL 证书进行验证。默认为 true。	No	boolean
`timeout`	为 LDAP 查询设置超时时间（以秒为单位）。当 LDAP 服务器无法响应时，有助于阻止请求。`0` 值表示没有超时（默认值：`10`）	No	`10` 或 `30`
`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	`user_filter` 字段语法的一些示例： - `'(employeeType=developer)'` - `'(&(objectclass=user)(\|(samaccountname=momo)(samaccountname=toto)))'`
`lowercase_usernames`	如果启用，系统转换用户名称为小写。	No	boolean
`retry_empty_result_with_codes`	如果结果/内容为空，将尝试重试操作时的 LDAP 查询响应代码数组。	No	`[80]`
`attributes`	映射到 LDAP 的属性哈希，供极狐GitLab 使用（请参阅属性部分）。	No	`'attributes' => { 'username' => ['uid'], 'email' => ['mail', 'email'] },`

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 -----'`

以下指南写明了如何在 tls_options 中设置 ca_file 和 ssl_version：

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' =>  'ldap.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com'
    'tls_options' => {
      'ca_file' => '/path/to/ca_file.pem',
      'ssl_version' => 'TLSv1_2'
    }
  }
}

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

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'LDAP'
          host: 'ldap.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'
          tls_options:
            ca_file: '/path/to/ca_file.pem'
            ssl_version: 'TLSv1_2'

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

更多详情，可以查看如何为使用 Helm chart 安装的极狐GitLab 示例配置 LDAP。

:::TabTitle Docker

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_enabled'] = true
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'label' => 'LDAP',
            'host' =>  'ldap.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
            'tls_options' => {
              'ca_file' => '/path/to/ca_file.pem',
              'ssl_version' => 'TLSv1_2'
            }
          }
        }

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

:::TabTitle Self-compiled (source)

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

production: &base
  ldap:
    enabled: true
    servers:
      main:
        label: 'LDAP'
        host: 'ldap.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        encryption: 'simple_tls'
        base: 'dc=example,dc=com'
        tls_options:
          ca_file: '/path/to/ca_file.pem'
          ssl_version: 'TLSv1_2'

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

属性配置

极狐GitLab 使用这些 LDAP 属性来为 LDAP 用户创建账号。指定的属性可能是：

字符型的属性名称。比如，'mail'。
一个按顺序尝试的属性名称数组。比如，['mail', 'email']。

用户的 LDAP 登录时将 LDAP 属性指定为 uid。

以下所有的 LDAP 属性都是可选的。如果您定义了这些属性，您必须在 attributes 哈希中使用它们。

设置	描述	示例
`username`	将为极狐GitLab 账户配置的 `@username`。如果值包含邮件地址，则极狐GitLab 用户名是 `@`，用户名是该电子邮件地址中 `@` 符号之前的部分。默认的 LDAP 属性被指定为 `uid`。	`['uid', 'userid', 'sAMAccountName']`
`email`	用户邮箱的 LDAP 属性。默认为 `['mail', 'email', 'userPrincipalName']`	`['mail', 'email', 'userPrincipalName']`
`name`	用户展示名称的 LDAP 属性。如果 `name` 为空，完成的名称取自 `first_name` 和 `last_name`。默认为 `'cn'`。	属性 `'cn'` 或 `'displayName'` 通常包含完整名称。相反地。或者，你可以通过指定一个不存在的属性（例如 `somethingNonExistent`）来强制使用 `first_name` 和 `last_name`。
`first_name`	用户名字的 LDAP 属性。当配置的 `name` 属性不存在时才被使用。默认为 `'givenName'`。	`'givenName'`
`last_name`	用户姓名的 LDAP 属性。当配置的 `name` 属性不存在时才被使用。默认为 `'sn'`。	`'sn'`

LDAP 同步配置

这些 LDAP 同步配置设置是可选的，但当配置了 external_groups 时，group_base 除外，其它是必需的：

配置项	说明	是否必须配置	举例
`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（如果未设置）。

如果 Sidekiq 被配置在与 Rails 服务器不同的服务器上，为了使 LDAP 同步正常工作，你还必须将 LDAP 配置添加到每一个 Sidekiq 服务器上。

使用多 LDAP 服务器

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

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

以下示例显示了如何使用最少的配置，配置三个 LDAP 服务器：

::Tabs

:::TabTitle Linux package (Omnibus)

Edit /etc/gitlab/gitlab.rb:

gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'GitLab AD',
    'host' =>  'ad.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com',
  },

  'secondary' => {
    'label' => 'GitLab Secondary AD',
    'host' =>  'ad-secondary.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com',
  },

  'tertiary' => {
    'label' => 'GitLab Tertiary AD',
    'host' =>  'ad-tertiary.mydomain.com',
    'port' => 636,
    'uid' => 'sAMAccountName',
    'encryption' => 'simple_tls',
    'base' => 'dc=example,dc=com',
  }
}

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

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      servers:
        main:
          label: 'GitLab AD'
          host: 'ad.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'
        secondary:
          label: 'GitLab Secondary AD'
          host: 'ad-secondary.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'
        tertiary:
          label: 'GitLab Tertiary AD'
          host: 'ad-tertiary.mydomain.com'
          port: 636
          uid: 'sAMAccountName'
          base: 'dc=example,dc=com'
          encryption: 'simple_tls'

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_enabled'] = true
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'label' => 'GitLab AD',
            'host' =>  'ad.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
          },

          'secondary' => {
            'label' => 'GitLab Secondary AD',
            'host' =>  'ad-secondary.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
          },

          'tertiary' => {
            'label' => 'GitLab Tertiary AD',
            'host' =>  'ad-tertiary.mydomain.com',
            'port' => 636,
            'uid' => 'sAMAccountName',
            'encryption' => 'simple_tls',
            'base' => 'dc=example,dc=com',
          }
        }

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

:::TabTitle Self-compiled (source)

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

production: &base
  ldap:
    enabled: true
    servers:
      main:
        label: 'GitLab AD'
        host: 'ad.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        base: 'dc=example,dc=com'
        encryption: 'simple_tls'
      secondary:
        label: 'GitLab Secondary AD'
        host: 'ad-secondary.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        base: 'dc=example,dc=com'
        encryption: 'simple_tls'
      tertiary:
        label: 'GitLab Tertiary AD'
        host: 'ad-tertiary.mydomain.com'
        port: 636
        uid: 'sAMAccountName'
        base: 'dc=example,dc=com'
        encryption: 'simple_tls'

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

对于不同 LDAP 选项的更多详情，可以在 gitlab.yml.example 中查看 ladp 设置。

::EndTabs

这个示例会产生一个带有以下选项卡的登录页面：

极狐GitLab AD.
极狐GitLab Secondary AD.
极狐GitLab Tertiary AD.

设置 LDAP 用户过滤器

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

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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

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

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      servers:
        main:
          user_filter: '(employeeType=developer)'

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'user_filter' => '(employeeType=developer)'
          }
        }

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

:::TabTitle Self-compiled (source)

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

production: &base
  ldap:
    servers:
      main:
        user_filter: '(employeeType=developer)'

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

如果要限制对 Active Directory 组的嵌套成员的访问，请使用以下语法：

(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` 中的特殊字符

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。

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

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

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

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      servers:
        main:
         lowercase_usernames: true

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

编辑 docker-compose.yml：

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'lowercase_usernames' => true
          }
        }

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

:::TabTitle Self-compiled (source)

编辑 config/gitlab.yaml：

production:
  ldap:
    servers:
      main:
        lowercase_usernames: true

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

禁用 LDAP web 登录

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

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

::Tabs

:::TabTitle Linux package (Omnibus)

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['prevent_ldap_sign_in'] = true

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

:::TabTitle Helm chart (Kubernetes)

导出 Helm values：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      preventSignin: true

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

:::TabTitle Docker

Edit docker-compose.yml:

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['prevent_ldap_sign_in'] = true

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

:::TabTitle Self-compiled (source)

Edit config/gitlab.yaml:

production:
  ldap:
    prevent_ldap_sign_in: true

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

::EndTabs

使用加密凭证

除了将 LDAP 集成凭证以明文形式存储在配置文件中，您可以选择为 LDAP 凭证使用加密文件。

先决条件：

要使用加密凭证，您必须首先启用加密配置。

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

加密文件的配置项有：

bind_dn
password

Omnibus

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

  gitlab_rails['ldap_servers'] = {
    'main' => {
      'bind_dn' => 'admin',
      'password' => '123'
    }
  }

编辑加密的 secret：

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

输入 LDAP secret 的未加密内容：

main:
  bind_dn: admin
  password: '123'

编辑 /etc/gitlab/gitlab.rb 并删除 bind_dn 和 password 的设置。
保存文件并重新配置极狐GitLab：
```
sudo gitlab-ctl reconfigure
```

Kubernetes

使用 Kubernetes 密钥存储 LDAP 密码。有关详细信息，请阅读 Helm LDAP secrets。

Docker

如果最初您在 docker-compose.yml 中的 LDAP 配置如下所示：

version: "3.6"
services:
  gitlab:
    image: 'gitlab/gitlab-ee:latest'
    restart: always
    hostname: 'gitlab.example.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['ldap_servers'] = {
          'main' => {
            'bind_dn' => 'admin',
            'password' => '123'
          }
        }

进入容器，并编辑加密的 secret：

sudo docker exec -t <container_name> bash
gitlab-rake gitlab:ldap:secret:edit EDITOR=vim

输入 LDAP secret 的未加密内容：

main:
  bind_dn: admin
  password: '123'

编辑 docker-compose.yml 并删除 bind_dn 和 password 的设置。
保存文件并重启极狐GitLab：
```
docker compose up -d
```

源安装

如果最初您在 /home/git/gitlab/config/gitlab.yml 中的 LDAP 配置如下所示：

production:
  ldap:
    servers:
      main:
        bind_dn: admin
        password: '123'

编辑加密的 secret：

bundle exec rake gitlab:ldap:secret:edit EDITOR=vim RAILS_ENVIRONMENT=production

输入 LDAP secret 的未加密内容：
```
main:
 bind_dn: admin
 password: '123'
```
编辑 /home/git/gitlab/config/gitlab.yml 并删除 bind_dn 和 password 的设置。

保存文件并重启极狐GitLab：

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

更新 LDAP DN 和电子邮件

当 LDAP 服务器在极狐GitLab 中创建用户时，用户的 LDAP 专有名称 (DN) 作为标识符关联到他们的极狐GitLab 账户。

当用户尝试使用 LDAP 登录时，极狐GitLab 会尝试使用保存在该用户账户中的 DN 来查找该用户。

如果极狐GitLab 通过 DN 找到了用户，并且用户的电子邮件：
- 与极狐GitLab 账户的电子邮件地址相匹配，极狐GitLab 不会采取任何进一步的操作。
- 已更改，极狐GitLab 更新其用户电子邮件记录以匹配 LDAP 中的电子邮件。
如果极狐GitLab 无法通过 DN 找到用户，它会尝试通过电子邮件找到用户。如果极狐GitLab：
- 通过电子邮件查找用户，极狐GitLab 更新存储在用户极狐GitLab 账户中的 DN。这两个值现在都与存储在 LDAP 中的信息匹配。
- 无法通过电子邮件地址找到用户（DN 和电子邮件地址已更改），请查看 User DN and email have changed.

禁用匿名 LDAP 身份验证

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

禁用匿名身份验证。
启用以下身份验证类型之一：
- 简单的身份验证。
- 简单身份验证和安全层 (SASL) 身份验证。

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

从 LDAP 中删除的用户

用户从 LDAP 服务器被删除：

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

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

要立即删除账户，您可以手动阻止用户。

从 LDAP 删除用户

从 LDAP 服务器删除用户：

被立即阻塞，无法登录极狐GitLab。
不在消耗许可证。

然而，这些用户还可以继续使用 Git SSH，直到下一次 LDAP 检查缓存运行。

要立即删除账号，您可以手动阻塞用户。

更新用户电子邮件地址

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

用户下次登录时。
下次运行用户同步时。

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

同步用户和群组

在 LDAP 和极狐GitLab 之间同步用户和群组的更多信息，可以查看 LDAP 同步。

从 LDAP 移至 SAML

添加 SAML 配置至：
- 在 Linux 软件包安装中的 gitlab.rb 文件。
- 在 Helm chart 安装的 values.yml 文件。
可选。从登录页面禁用 LDAP auth。
可选。要修复此问题，您可以首先移除那些用户的 LDAP 身份识别。
确认他们的用户不能够登录到他们的账号。如果用户无法登录，需要确认用户的 LDAP 是否还在并在需要的时候移除它。如果此问题还在继续，检查日志来排查问题。
在配置文件中，修改：
- omniauth_auto_link_user 为 saml。
- omniauth_auto_link_ldap_user 为 false。
- ldap_enabled 为 false。你也可以将 LDAP 提供商设置注释掉。

故障排查

查看我们的 LDAP 故障排查。

极狐GitLab 和 LDAP 集成

安全

安全风险

配置 LDAP

基本配置

SSL 配置

属性配置

LDAP 同步配置

使用多 LDAP 服务器

设置 LDAP 用户过滤器

转义 user_filter 中的特殊字符

启用 LDAP 用户名小写

禁用 LDAP web 登录

使用加密凭证

更新 LDAP DN 和电子邮件

禁用匿名 LDAP 身份验证

从 LDAP 中删除的用户

从 LDAP 删除用户

更新用户电子邮件地址

同步用户和群组

从 LDAP 移至 SAML

故障排查

转义 `user_filter` 中的特殊字符