{{< details >}}

  • Tier: 基础版，专业版，旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

极狐GitLab 的双重身份验证（2FA）为您的账户提供了额外的安全级别。要访问您的账户，其他人需要您的用户名和密码 以及 第二重身份验证因素的访问权限。

极狐GitLab 支持以下作为第二重身份验证因素：

  • 一次性密码验证器 (OTP)。启用后，极狐GitLab 在您登录时会提示您输入验证码。验证码由您的 OTP 验证器生成（例如，您设备上的密码管理器）。
  • WebAuthn 设备。当您提供用户名和密码登录时，系统会提示您激活 WebAuthn 设备（通常是按下其上的按钮），以便代表您执行安全验证。

如果您设置了设备，还需设置 OTP，以便在设备丢失时仍能访问您的账户。

使用个人访问令牌进行双重身份验证

启用 2FA 后，您不能使用密码通过 HTTPS 或 极狐GitLab API 进行身份验证。您可以使用 个人访问令牌 代替。

OAuth 凭据助手

以下 Git 凭据助手使用 OAuth 进行极狐GitLab 身份验证。此功能与双重身份验证兼容。首次身份验证时，助手会打开网页浏览器，极狐GitLab 会要求您授权应用。后续的身份验证无需交互。

Git 凭据管理器

Git 凭据管理器 (GCM) 默认使用 OAuth 进行身份验证。GCM 支持 JihuLab.com，无需任何手动配置。

为了避免每次推送都需要重新验证，GCM 支持缓存以及各种平台特定的凭据存储，这些存储在会话之间持久存在。无论您使用个人访问令牌还是 OAuth，此功能都很有用。

Windows 的 Git 包含 Git 凭据管理器。

Git 凭据管理器主要由 GitHub, Inc. 开发。它是一个开源项目，并由社区支持。

git-credential-oauth

git-credential-oauth 支持 JihuLab.com 和多个流行的公共主机，无需任何手动配置。

许多 Linux 发行版将 git-credential-oauth 作为软件包包含。

git-credential-oauth 是一个由社区支持的开源项目。

启用双重身份验证

您可以使用以下方式启用 2FA：

  • OTP 验证器。启用 2FA 后，备份您的恢复代码。
  • WebAuthn 设备。

您的账户电子邮件必须经过确认才能启用 2FA。

启用一次性密码验证器

要使用 OTP 验证器启用 2FA：

  1. 在极狐GitLab 中：
    1. 访问您的用户设置。
    2. 选择 账户。
    3. 选择 启用双重身份验证。
  2. 在您的设备上（通常是手机）：
    1. 安装兼容的应用程序。例如：
      • 基于云的（推荐，因为如果您丢失硬件设备，可以恢复访问）：
        • Authy。
        • Cisco Duo。
      • 其他（专有）：
        • Google Authenticator。
        • Microsoft Authenticator。
      • 其他（基础版软件）
        • Aegis Authenticator。
        • FreeOTP。
    2. 在应用程序中，通过以下两种方式之一添加新条目：
      • 使用设备的摄像头扫描极狐GitLab 显示的代码以自动添加条目。
      • 输入提供的详细信息以手动添加条目。
  3. 在极狐GitLab 中：
    1. 在 Pin 码中输入设备上的条目的六位数 PIN 码。
    2. 输入您的当前密码。
    3. 选择 提交。

如果您输入了正确的 PIN 码，极狐GitLab 会显示一组 恢复代码。下载并将其保存在安全的地方。

使用 FortiAuthenticator 启用一次性密码验证器

{{< details >}}

  • Offering: 私有化部署

{{< /details >}}

{{< alert type=”flag” >}}

在极狐GitLab 私有化部署中，默认情况下此功能不可用。为了让每位用户都可以使用此功能，管理员可以启用名为 forti_authenticator 的功能标志。在 JihuLab.com 中，此功能不可用。

{{< /alert >}}

您可以在极狐GitLab 中使用 FortiAuthenticator 作为 OTP 提供商。用户必须：

  • 在 FortiAuthenticator 和极狐GitLab 中使用相同的用户名存在。
  • 在 FortiAuthenticator 中配置 FortiToken。

您需要 FortiAuthenticator 的用户名和访问令牌。以下显示的 access_token 是 FortAuthenticator 访问密钥。已在 FortAuthenticator 版本 6.2.0 上测试。

在极狐GitLab 中配置 FortiAuthenticator。在您的极狐GitLab 服务器上：

  1. 打开配置文件。

    对于 Linux 软件包安装：

    sudo editor /etc/gitlab/gitlab.rb

    对于自行编译的安装：

    cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml

  2. 添加提供商配置。

    对于 Linux 软件包安装：

    gitlab_rails['forti_authenticator_enabled'] = true
gitlab_rails['forti_authenticator_host'] = 'forti_authenticator.example.com'
gitlab_rails['forti_authenticator_port'] = 443
gitlab_rails['forti_authenticator_username'] = '<some_username>'
gitlab_rails['forti_authenticator_access_token'] = 's3cr3t'

    对于自行编译的安装：

    forti_authenticator:
  enabled: true
  host: forti_authenticator.example.com
  port: 443
  username: <some_username>
  access_token: s3cr3t
  3. 保存配置文件。
  4. 重新配置（Linux 软件包安装）或 重启（自行编译的安装）。

使用 FortiToken Cloud 启用一次性密码验证器

{{< details >}}

  • Offering: 私有化部署

{{< /details >}}

{{< alert type=”flag” >}}

在极狐GitLab 私有化部署中，默认情况下此功能不可用。为了让每位用户都可以使用此功能，管理员可以启用名为 forti_token_cloud 的功能标志。在 JihuLab.com，此功能不可用。此功能尚未准备好用于生产环境。

{{< /alert >}}

您可以在极狐GitLab 中使用 FortiToken Cloud 作为 OTP 提供商。用户必须：

  • 在 FortiToken Cloud 和极狐GitLab 中使用相同的用户名存在。
  • 在 FortiToken Cloud 中配置 FortiToken。

在极狐GitLab 中配置 FortiToken Cloud。在您的极狐GitLab 服务器上：

  1. 打开配置文件。

    对于 Linux 软件包安装：

    sudo editor /etc/gitlab/gitlab.rb

    对于自行编译的安装：

    cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml

  2. 添加提供商配置。

    对于 Linux 软件包安装：

    gitlab_rails['forti_token_cloud_enabled'] = true
gitlab_rails['forti_token_cloud_client_id'] = '<your_fortinet_cloud_client_id>'
gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>'

    对于自行编译的安装：

    forti_token_cloud:
  enabled: true
  client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID
  client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET
  3. 保存配置文件。
  4. 重新配置（Linux 软件包安装）或 重启（自行编译的安装）。

设置 WebAuthn 设备

{{< history >}}

{{< /history >}}

WebAuthn 由以下支持：

  • 桌面浏览器：
    • Chrome
    • Edge
    • Firefox
    • Opera
    • Safari
  • 移动浏览器：
    • Android 的 Chrome
    • Android 的 Firefox
    • iOS Safari（自 iOS 13.3 起）

要使用 WebAuthn 兼容设备设置 2FA：

  1. 可选。设置 OTP 验证器。
  2. 访问您的 用户设置。
  3. 选择 账户。
  4. 选择 启用双重身份验证。
  5. 插入您的 WebAuthn 设备。
  6. 输入设备名称，在极狐GitLab 15.10 及更高版本中，输入您的极狐GitLab 账户密码。 如果您通过身份提供商登录，可能不需要输入此密码。
  7. 选择 设置新 WebAuthn 设备。
  8. 根据您的设备，可能需要按下按钮或触摸传感器。

您应该收到一条消息，指示您已成功设置设备。

当您使用 WebAuthn 兼容设备设置 2FA 时，该设备链接到特定计算机上的特定浏览器。根据浏览器和 WebAuthn 设备，您可能可以配置设置以在不同浏览器或计算机上使用 WebAuthn 设备。

如果这是您首次设置 2FA，您必须下载恢复代码，以便在丢失访问权限时恢复访问您的账户。

{{< alert type=”warning” >}}

如果您清除浏览器数据，可能会失去访问账户的权限。

{{< /alert >}}

恢复代码

在使用 OTP 验证器成功启用 2FA 后，系统会提示您下载一组生成的恢复代码。如果您丢失 OTP 验证器的访问权限，可以使用这些恢复代码之一登录您的账户。

{{< alert type=”warning” >}}

每个代码只能用于一次登录您的账户。

{{< /alert >}}

您应该复制和打印这些代码，或使用 下载代码 下载它们以便存储在安全的地方。如果您选择下载，文件名为 gitlab-recovery-codes.txt。

  • WebAuthn 设备不会生成恢复代码。
  • gitlab-sshd 不适合重新生成恢复代码。

如果您丢失了恢复代码，或希望生成新的代码，可以使用以下任意一种方式：

重新生成双重身份验证恢复代码

要重新生成 2FA 恢复代码，您需要访问桌面浏览器：

  1. 访问您的 用户设置。
  2. 选择 账户 > 双重身份验证 (2FA)。
  3. 如果您已经配置了 2FA，选择 管理双重身份验证。
  4. 在 禁用双重身份验证 部分，选择 重新生成恢复代码。
  5. 在对话框中，输入您的当前密码并选择 重新生成恢复代码。

{{< alert type=”note” >}}

如果您重新生成 2FA 恢复代码，请保存它们。您无法使用任何先前创建的 2FA 代码。

{{< /alert >}}

使用启用双重身份验证登录

启用 2FA 登录与典型的登录过程略有不同。输入您的用户名和密码后，您会根据启用的 2FA 类型收到第二个提示。

使用一次性密码验证器登录

当被要求时，输入您的 OTP 验证器提供的 PIN 码或恢复代码以登录。

使用 WebAuthn 设备登录

在支持的浏览器中，您应该在输入凭据后自动提示激活您的 WebAuthn 设备（例如，触摸或按下其按钮）。

系统显示一条消息，指示您的设备已响应身份验证请求并自动登录。

禁用双重身份验证

{{< history >}}

  • 单独或同时禁用 OTP 验证器和 WebAuthn 设备的能力在极狐GitLab 17.6 中引入。

{{< /history >}}

您可以单独或同时禁用 OTP 验证器和 WebAuthn 设备。要同时禁用它们：

  1. 访问您的 用户设置。
  2. 选择 账户。
  3. 选择 管理双重身份验证。
  4. 在 禁用双重身份验证 部分，选择 禁用双重身份验证。
  5. 在对话框中，输入您的当前密码并选择 禁用双重身份验证。

这会清除您所有的 2FA 注册，包括移动应用和 WebAuthn 设备。

极狐GitLab 管理员信息

{{< details >}}

  • Tier: 基础版，专业版，旗舰版
  • Offering: 私有化部署

{{< /details >}}

  • 注意确保在恢复极狐GitLab 备份后 2FA 继续工作。
  • 为确保 2FA 正确授权 OTP 服务器，请使用像 NTP 这样的服务同步您的极狐GitLab 服务器时间。否则，由于时间差异，授权可能始终失败。

  • 极狐GitLab 的 WebAuthn 实现在极狐GitLab 实例从多个主机名或 FQDN 访问时无法正常工作。每个 WebAuthn 注册链接到注册时的 当前主机名，无法用于其他主机名或 FQDN。

    例如，如果用户尝试从 first.host.xyz 和 second.host.xyz 访问极狐GitLab 实例：

    • 用户使用 first.host.xyz 登录并注册其 WebAuthn 密钥。
    • 用户注销并尝试使用 first.host.xyz 登录 - WebAuthn 身份验证成功。
    • 用户注销并尝试使用 second.host.xyz 登录 - WebAuthn 身份验证失败，因为 WebAuthn 密钥仅在 first.host.xyz 上注册。
  • 要在系统或群组级别强制执行 2FA，请参阅强制双重身份验证。