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

将 GitLab 与 Kerberos 集成

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

GitLab 可以集成 Kerberos 作为认证机制。

  • 您可以配置 GitLab，让用户使用 Kerberos 凭据登录。
  • 您可以使用 Kerberos 防止 任何人拦截或窃听传输的密码。

Kerberos 仅在使用 GitLab Enterprise Edition (EE) 的实例上可用。如果您运行的是 GitLab Community Edition (CE)，可以从 GitLab CE 升级到 GitLab EE。

除非集成设置为使用专用端口，否则 GitLab CI/CD 无法与启用 Kerberos 的 GitLab 实例协同工作。

配置

要让 GitLab 提供 Kerberos 令牌认证，请执行以下先决条件。您仍需为系统配置 Kerberos 使用，例如指定领域（realm）。GitLab 会使用系统的 Kerberos 设置。

GitLab keytab 文件

  1. 在 GitLab 服务器上为 HTTP 服务创建 Kerberos 服务主体（Service Principal）。 如果您的 GitLab 服务器是 gitlab.example.com 且 Kerberos 领域为 EXAMPLE.COM，请在 Kerberos 数据库中创建服务主体 HTTP/[email protected]。
  2. 在 GitLab 服务器上为该服务主体创建 keytab 文件。例如，/etc/http.keytab。

keytab 是敏感文件，必须可被 GitLab 用户读取。请适当设置文件所有权并保护文件：

sudo chown git /etc/http.keytab
sudo chmod 0600 /etc/http.keytab

配置 GitLab

自编译安装

对于自编译安装，请确保已安装 kerberos gem 组依赖。

  1. 编辑 gitlab.yml 中的 kerberos 部分，以启用 Kerberos 令牌认证。大多数情况下，您只需启用 Kerberos 并指定 keytab 文件位置：

    omniauth:
  enabled: true
  allow_single_sign_on: ['kerberos']

kerberos:
  # 允许 Git 客户端使用 HTTP Negotiate 认证方法
  enabled: true

  # Kerberos 5 keytab 文件。该文件必须可被 GitLab 用户读取，
  # 且应与系统中的其他 keytab 文件不同。
  #（默认：使用 Krb5 配置中的默认 keytab）
  keytab: /etc/http.keytab

  2. 重启 GitLab 使更改生效。

Linux 包安装

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

    gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']

gitlab_rails['kerberos_enabled'] = true
gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"

    为避免 GitLab 在用户首次通过 Kerberos 登录时自动创建账户，请勿将 kerberos 设置为 gitlab_rails['omniauth_allow_single_sign_on'] 的值。

  2. 重新配置 GitLab 使更改生效。

GitLab 现在为登录和 HTTP Git 访问提供 negotiate 认证方法，使支持此认证协议的 Git 客户端能够使用 Kerberos 令牌进行认证。

启用单点登录（SSO）

配置通用设置，将 kerberos 添加为单点登录提供商。这将为没有现有 GitLab 账户的用户启用即时账户预配（Just-In-Time account provisioning）。

创建并关联 Kerberos 账户

您可以将 Kerberos 账户关联到现有 GitLab 账户，或设置 GitLab 在 Kerberos 用户首次尝试登录时创建新账户。

将 Kerberos 账户关联到现有 GitLab 账户

如果您是管理员，可以将 Kerberos 账户关联到现有 GitLab 账户。操作步骤如下：

  1. 在左侧边栏底部，选择 管理员。
  2. 选择 概览 > 用户。
  3. 选择一个用户，然后选择 身份 标签页。
  4. 从 提供商 下拉列表中选择 Kerberos。
  5. 确保 标识符 与 Kerberos 用户名对应。
  6. 选择 保存更改。

如果您不是管理员：

  1. 在左侧边栏选择您的头像。
  2. 选择 编辑资料。
  3. 在左侧边栏选择 账户。
  4. 在 服务登录 部分，选择 连接 Kerberos。 如果您未看到 服务登录 的 Kerberos 选项，请遵循启用单点登录中的要求。

任一情况下，您现在都可以使用 Kerberos 凭据登录 GitLab 账户。

首次登录时创建账户

用户首次使用 Kerberos 账户登录 GitLab 时，GitLab 会创建一个匹配的账户。 继续操作前，请先阅读 Linux 包安装和自编译实例的通用配置设置选项。您还必须包含 kerberos。

掌握这些信息后：

  1. 在 allow_single_sign_on 设置中包含 'kerberos'。
  2. 暂时接受默认的 block_auto_created_users 选项（值为 true）。
  3. 当用户尝试使用 Kerberos 凭据登录时，GitLab 会创建新账户。

    1. 如果 block_auto_created_users 为 true，Kerberos 用户可能会看到类似消息：

      您的账户已被封禁。如果您认为这是错误，请联系您的 GitLab 管理员。
      1. 作为管理员，您可以确认新的已封禁账户：
        1. 在左侧边栏底部，选择 管理员。
        2. 在左侧边栏选择 概览 > 用户，并查看 已封禁 标签页。
      2. 您可以启用该用户。

    2. 如果 block_auto_created_users 为 false，Kerberos 用户将成功认证并登录 GitLab。

我们建议您保留 block_auto_created_users 的默认设置。 未经管理员知晓就在 GitLab 上创建账户的 Kerberos 用户可能带来安全风险。

关联 Kerberos 和 LDAP 账户

如果用户使用 Kerberos 登录，但同时启用了 LDAP 集成，用户在首次登录时会自动关联到其 LDAP 账户。要实现此功能，需满足以下先决条件：

Kerberos 用户名必须与 LDAP 用户的 UID 匹配。您可以在 GitLab LDAP 配置中选择用作 UID 的 LDAP 属性，但对于 Active Directory，应使用 sAMAccountName。

Kerberos 领域必须与 LDAP 用户可分辨名称（Distinguished Name）的域名部分匹配。例如，如果 Kerberos 领域是 AD.EXAMPLE.COM，则 LDAP 用户的可分辨名称应以 dc=ad,dc=example,dc=com 结尾。

综合这些规则，仅当用户的 Kerberos 用户名格式为 [email protected] 且其 LDAP 可分辨名称为 sAMAccountName=foo,dc=ad,dc=example,dc=com 时，关联才能生效。

自定义允许的领域

当用户的 Kerberos 领域与用户 LDAP DN 中的域名不匹配时，您可以配置自定义允许的领域。配置值必须指定用户可能拥有的所有域名。其他域名将被忽略，且不会关联 LDAP 身份。

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

    gitlab_rails['kerberos_simple_ldap_linking_allowed_realms'] = ['example.com','kerberos.example.com']

  2. 保存文件并重新配置 GitLab 使更改生效。

  1. 编辑 config/gitlab.yml：

    kerberos:
  simple_ldap_linking_allowed_realms: ['example.com','kerberos.example.com']

  2. 保存文件并重启 GitLab 使更改生效。

HTTP Git 访问

关联的 Kerberos 账户允许您使用 Kerberos 账户执行 git pull 和 git push，也可以使用标准的 GitLab 凭据。

关联了 Kerberos 账户的 GitLab 用户还可以使用 Kerberos 令牌执行 git pull 和 git push，即无需在每次操作时发送密码。

libcurl 低于版本 7.64.1 存在已知问题，在协商认证时不会重用连接。当推送内容大于 http.postBuffer 配置时会导致授权问题。请确保 Git 使用至少 libcurl 7.64.1 以避免此问题。要检查安装的 libcurl 版本，请运行 curl-config --version。

使用 Kerberos 令牌进行 HTTP Git 访问（无密码认证）

由于当前 Git 版本中的缺陷，git CLI 命令仅使用 negotiate 认证方法（如果 HTTP 服务器提供此方法），即使该方法失败（例如客户端没有 Kerberos 令牌）。因此，如果 Kerberos 认证失败，无法回退到嵌入式用户名和密码（也称为 basic）认证。

为了让 GitLab 用户能够使用当前 Git 版本的 basic 或 negotiate 认证，可以在不同端口（例如 8443）上提供 Kerberos 令牌认证，而标准端口仅提供 basic 认证。

Git 2.4 及更高版本支持在用户名和密码通过交互方式或凭据管理器传递时回退到 basic 认证。当用户名和密码作为 URL 的一部分传递时，回退会失败。例如，在使用 CI/CD 作业令牌进行认证的 GitLab CI/CD 作业中可能发生这种情况。

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

    gitlab_rails['kerberos_use_dedicated_port'] = true
gitlab_rails['kerberos_port'] = 8443
gitlab_rails['kerberos_https'] = true

  2. 重新配置 GitLab 使更改生效。

  1. 编辑 GitLab 的 NGINX 配置文件（例如 /etc/nginx/sites-available/gitlab-ssl），配置 NGINX 在标准 HTTPS 端口之外监听 8443 端口：

    server {
  listen 0.0.0.0:443 ssl;
  listen [::]:443 ipv6only=on ssl default_server;
  listen 0.0.0.0:8443 ssl;
  listen [::]:8443 ipv6only=on ssl;

  2. 更新 gitlab.yml 中的 kerberos 部分：

    kerberos:
  # 专用端口：Git 2.4 以下版本在 Negotiate 失败时不会回退到 Basic 认证。
  # 要在旧版 Git 中同时支持 Basic 和 Negotiate 方法，请配置
  # nginx 在额外端口（例如：8443）上代理 GitLab，并取消注释以下行
  # 以将该端口专用于 Kerberos 认证。（默认：false）
  use_dedicated_port: true
  port: 8443
  https: true

  3. 重启 GitLab 和 NGINX 使更改生效。

更改后，Git 远程 URL 需更新为 https://gitlab.example.com:8443/mygroup/myproject.git 以使用 Kerberos 令牌认证。

从基于密码升级到基于令牌的 Kerberos 登录

在 GitLab 的早期版本中，用户登录时必须向 GitLab 提交其 Kerberos 用户名和密码。

我们在 GitLab 15.0 中移除了基于密码的 Kerberos 登录方式。

支持 Active Directory Kerberos 环境

在 Active Directory 域中使用 Kerberos 令牌认证时，可能需要增加 NGINX 允许的最大标头大小，因为 Kerberos 协议的扩展可能导致 HTTP 认证标头超过默认的 8 kB。在NGINX 配置中将 large_client_header_buffers 设置为更大的值。

使用仅使用 AES 加密创建的 Keytab 与 Windows AD 配合使用

当您使用仅采用高级加密标准（AES）的加密创建 keytab 时，必须在 AD 服务器上为该账户选择 此账户支持 Kerberos AES <128/256> 位加密 复选框。复选框是 128 位还是 256 位取决于创建 keytab 时使用的加密强度。要检查此设置，在 Active Directory 服务器上：

  1. 打开 用户和组 工具。
  2. 找到用于创建 keytab 的账户。
  3. 右键单击该账户，选择 属性。
  4. 在 账户 标签页的 账户选项 中，选择相应的 AES 加密支持复选框。
  5. 保存并关闭。