| GitLab Docs

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

---
stage: Software Supply Chain Security
group: Authentication
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
gitlab_dedicated: no
title: 将 LDAP 与 GitLab 集成
---


      Tier: Free, Premium, Ultimate

      Offering: GitLab Self-Managed



GitLab 与 [LDAP - Lightweight Directory Access Protocol](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)（轻量级目录访问协议）集成，以支持用户身份验证。

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

- Microsoft Active Directory（微软活动目录）
- Apple Open Directory（苹果开放目录）
- Open LDAP
- 389 Server


  
  
    GitLab 不支持 Microsoft Active Directory Trusts（微软活动目录信任）。




通过 LDAP 添加的用户：

- 通常使用 [授权席位](../../../subscriptions/manage_users_and_seats.md#billable-users)
- 可使用 GitLab 用户名或邮箱 + LDAP 密码进行 Git 身份验证，即使 Git 的密码认证 [已禁用](../../settings/sign_in_restrictions.md#password-authentication-enabled)

当以下情况发生时，LDAP 专有名称（DN）会与现有 GitLab 用户关联：

- 现有用户首次使用 LDAP 登录 GitLab
- LDAP 邮箱地址是现有 GitLab 用户的主邮箱地址。如果未在 GitLab 用户数据库中找到 LDAP 邮箱属性，则会创建新用户

如果现有 GitLab 用户希望启用 LDAP 登录，应：

1. 确保其 GitLab 邮箱地址与 LDAP 邮箱地址匹配
1. 使用 LDAP 凭据登录 GitLab

## 安全

GitLab 验证用户是否仍在 LDAP 中保持活跃状态。

当用户出现以下情况时，LDAP 中视为非活跃：

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

要检查用户在 LDAP 中是否活跃，请使用以下 PowerShell 命令和 [Active Directory Module](https://learn.microsoft.com/en-us/powershell/module/activedirectory/?view=windowsserver2022-ps) 检查 Active Directory：

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

GitLab 检查 LDAP 用户状态：

使用任何身份验证提供商登录时
活跃的 Web 会话或使用令牌/SSH 密钥的 Git 请求每小时检查一次
使用 LDAP 用户名和密码执行 Git over 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 部署方式，编辑的文件不同：

编辑 /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
```

导出 Helm 值：

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

编辑 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
```

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

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

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

有关各种 LDAP 选项的更多信息，请参阅 gitlab.yml.example 中的 ldap 设置。

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

基本配置设置

提供以下基本设置：

设置	必需性	类型	说明
`label`	是	String	LDAP 服务器的友好名称。显示在登录页面上。示例：`'Paris'` 或 `'Acme, Ltd.'`
`host`	是	String	LDAP 服务器的 IP 地址或域名。当 `hosts` 已定义时忽略。示例：`'ldap.mydomain.com'`
`port`	是	Integer	连接 LDAP 服务器的端口。当 `hosts` 已定义时忽略。示例：`389` 或 `636`（SSL）
`uid`	是	String	映射到用户登录名的 LDAP 属性。应为属性名而非值。不影响 GitLab 用户名（参见属性部分）。示例：`'sAMAccountName'` 或 `'uid'` 或 `'userPrincipalName'`
`base`	是	String	用户搜索的基础。示例：`'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 用户名中第一个 `@` 之后的所有内容。如果在 ActiveDirectory 上使用 `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)(
`lowercase_usernames`	否	Boolean	启用后，GitLab 将用户名转为小写
`retry_empty_result_with_codes`	否	Array	当结果/内容为空时尝试重试操作的 LDAP 查询响应代码数组。对于 Google Secure LDAP，设置为 `[80]`

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：

编辑 /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
```

导出 Helm 值：

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

编辑 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
```

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

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

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

属性配置设置

GitLab 使用这些 LDAP 属性为 LDAP 用户创建账户。指定的属性可以是：

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

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

以下所有 LDAP 属性均为可选。如果定义这些属性，必须在 attributes 哈希中定义。

设置	说明	示例
`username`	GitLab 账户将使用的 `@username`。如果值包含邮箱地址，GitLab 用户名是 `@` 前的部分。默认为指定为 `uid` 的 LDAP 属性	`['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 同步配置设置

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

以下 LDAP 同步配置均为可选，但 group_base 在配置 external_groups 时为必需：

设置	说明	示例
`group_base`	搜索组的基础。所有有效组都有此基础作为其 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`	包含用户公钥的 LDAP 属性。如果未设置则为 `false`	`'sshPublicKey'` 或 `false`

如果 Sidekiq 配置在与 Rails 服务器不同的服务器上，您必须将 LDAP 配置添加到每个 Sidekiq 服务器才能使 LDAP 同步正常工作。

使用多个 LDAP 服务器

Tier: Premium, Ultimate
Offering: GitLab Self-Managed

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

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

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

编辑 /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
```

导出 Helm 值：

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

编辑 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
```

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

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

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

有关各种 LDAP 选项的更多信息，请参阅 gitlab.yml.example 中的 ldap 设置。

此配置将导致登录页面显示以下选项卡：

GitLab AD
GitLab Secondary AD
GitLab Tertiary AD

设置 LDAP 用户过滤器

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

编辑 /etc/gitlab/gitlab.rb：

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

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

导出 Helm 值：

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

编辑 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
```

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

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

保存文件并重启 GitLab：

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

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

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

(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 可包含特殊字符。例如：

逗号：
```
OU=GitLab, Inc,DC=gitlab,DC=com
```
开闭方括号：
```
OU=GitLab (Inc),DC=gitlab,DC=com
```

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

用 C 转义逗号。例如：
```
OU=GitLabC Inc,DC=gitlab,DC=com
```
用 8 转义开括号，用 9 转义闭括号。例如：
```
OU=GitLab 8Inc9,DC=gitlab,DC=com
```

启用 LDAP 用户名小写

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

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

编辑 /etc/gitlab/gitlab.rb：

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

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

导出 Helm 值：

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

编辑 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
```

编辑 config/gitlab.yaml：

production:
  ldap:
    servers:
      main:
        lowercase_usernames: true

保存文件并重启 GitLab：

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

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

禁用 LDAP Web 登录

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

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

编辑 /etc/gitlab/gitlab.rb：

gitlab_rails['prevent_ldap_sign_in'] = true

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

导出 Helm 值：

helm get values gitlab > gitlab_values.yaml

编辑 gitlab_values.yaml：

global:
  appConfig:
    ldap:
      preventSignin: true

保存文件并应用新值：

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

编辑 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
```

编辑 config/gitlab.yaml：

production:
  ldap:
    prevent_ldap_sign_in: true

保存文件并重启 GitLab：

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

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

为 GitLab 提供智能卡身份验证

有关使用 LDAP 服务器和 GitLab 的智能卡的更多信息，请参阅智能卡身份验证。

使用加密凭据

与其将 LDAP 集成凭据以明文存储在配置文件中，您可以选择使用加密文件存储 LDAP 凭据。

先决条件：

要使用加密凭据，必须先启用加密配置

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

加密文件支持的配置项包括：

bind_dn
password

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

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

编辑加密的机密：

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

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

main:
  bind_dn: admin
  password: '123'

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

使用 Kubernetes Secret 存储 LDAP 密码。更多信息请参阅 Helm LDAP Secrets。

如果您在 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'
          }
        }

进入容器并编辑加密的机密：

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

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

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'

编辑加密的机密：

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

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

保存文件并重启 GitLab：

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

# 对于运行 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 和邮箱地址都已更改），请参阅用户 DN 和邮箱已更改

禁用匿名 LDAP 身份验证

GitLab 不支持 TLS 客户端身份验证。请在您的 LDAP 服务器上完成以下步骤：

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

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

从 LDAP 删除的用户

从 LDAP 服务器删除的用户：

立即被禁止登录 GitLab
不再占用授权席位

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

要立即删除账户，您可以手动屏蔽用户。

更新用户邮箱地址

当使用 LDAP 登录时，LDAP 服务器上的邮箱地址被视为用户信息的事实来源。

更新用户邮箱地址必须在管理用户的 LDAP 服务器上进行。GitLab 的邮箱地址在以下情况更新：

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

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

有关用户更新预期行为的更多详细信息，请参阅我们的 LDAP 故障排除部分。

Google Secure LDAP

Google Cloud Identity 提供可与 GitLab 配置用于身份验证和组同步的 Secure LDAP 服务。详细配置说明请参阅 Google Secure LDAP。

同步用户和组

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

从 LDAP 迁移到 SAML

将 SAML 配置添加到：
- Linux 包安装的 gitlab.rb
- Helm chart 安装的 values.yml
可选。从登录页面禁用 LDAP 身份验证
可选。为解决用户链接问题，您可以先删除这些用户的 LDAP 身份
确认用户能够登录其账户。如果用户无法登录，检查该用户的 LDAP 身份是否仍然存在，必要时删除。如果问题持续存在，请检查日志以识别问题
在配置文件中更改：
- omniauth_auto_link_user 仅改为 saml
- omniauth_auto_link_ldap_user 改为 false
- ldap_enabled 改为 false 您也可以注释掉 LDAP 提供者设置

故障排除

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

安全风险

配置 LDAP

基本配置设置

SSL 配置设置

属性配置设置

LDAP 同步配置设置

使用多个 LDAP 服务器

设置 LDAP 用户过滤器

在 user_filter 中转义特殊字符

启用 LDAP 用户名小写

禁用 LDAP Web 登录

为 GitLab 提供智能卡身份验证

使用加密凭据

更新 LDAP DN 和邮箱

禁用匿名 LDAP 身份验证

从 LDAP 删除的用户

更新用户邮箱地址

Google Secure LDAP

同步用户和组

从 LDAP 迁移到 SAML

故障排除

在 `user_filter` 中转义特殊字符