• 使用具有双重身份验证的个人访问令牌
• Git 凭证管理器（GCM）
• 启用双重验证
  • 一次性密码
  • 使用 FortiAuthenticator 启用一次性密码
  • 使用 FortiToken Cloud 启用一次性密码
  • 设置 U2F 设备
  • 设置 WebAuthn 设备
• 恢复码
  • 重新生成双重身份验证恢复码
• 在启用 2FA 的情况下登录
  • 使用一次性密码登录
  • 使用 U2F 设备登录
  • 使用 WebAuthn 设备登录
• 禁用双重认证
• 恢复选项
  • 使用保存的恢复码
  • 使用 SSH 生成新恢复码
• 管理员注意事项
• 故障排查

双重验证

双重身份验证 (2FA) 为您的帐户提供了额外的安全级别。要让其它人访问您的帐户，他们将需要您的用户名和密码以及访问您的第二个身份验证因素的权限。

极狐GitLab 支持作为身份验证的第二个因素：

• 基于时间的一次性密码 (TOTP)。启用后，系统会在您登录时提示您输入验证码。验证码由您的一次性密码验证器（例如，您的一台设备上的密码管理器）生成。
• U2F 或 WebAuthn 设备。当您提供用户名和密码进行登录时，系统会提示您激活 U2F 或 WebAuthn 设备（通常通过按下按钮）。这代表您执行安全身份验证。

如果您设置了设备，还需要设置 TOTP，以便在设备丢失时仍然可以访问您的帐户。

使用具有双重身份验证的个人访问令牌

启用 2FA 后，您无法使用密码通过 HTTPS 或 GitLab API 对 Git 进行身份验证。 您可以改用个人访问令牌。

Git 凭证管理器（GCM）

对于 Git over HTTPS，Git 凭证管理器 (GCM) 提供了个人访问令牌的替代方案。默认情况下，GCM 使用 OAuth 进行身份验证，在 Web 浏览器中打开极狐GitLab。第一次进行身份验证时，系统会要求您授权该应用程序。如果您保持登录，则后续身份验证不需要交互。

因此，您无需在每次推送时重新进行身份验证，GCM 支持缓存以及在会话之间持续存在的各种特定于平台的凭证存储。无论您使用个人访问令牌还是 OAuth，此功能都很有用。

Git Credential Manager 主要由 GitHub, Inc. 开发。它是一个开源项目，并得到社区的支持。

启用双重验证

• 帐户邮箱确认要求引入于 14.3。部署在 ensure_verified_primary_email_for_2fa 功能标志后，默认启用。
• 帐户邮箱确认要求可用，功能标志 ensure_verified_primary_email_for_2fa 移除于 14.4。

有多种方法可以启用双因素身份验证 (2FA)：

• 使用一次性密码验证器。启用 2FA 后，备份您的恢复码。
• 使用 U2F 或 WebAuthn 设备。

在 14.3 和更高版本，必须确认您的帐户电子邮件才能启用双重身份验证。

一次性密码

要使用一次性密码启用 2FA：

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

如果您输入了正确的密码，系统会显示恢复码列表。下载它们并将它们保存在安全的地方。

使用 FortiAuthenticator 启用一次性密码

您可以将 FortiAuthenticator 用作极狐GitLab 中的一次性密码 (OTP) 提供程序。用户必须：

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

您需要 FortiAuthenticator 的用户名和访问令牌。下面显示的代码示例中的 access_token 是 FortAuthenticator 访问密钥。要获取令牌，请参阅 Fortinet 文档库中的 REST API 解决方案指南。

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

1. 打开配置文件：

   对于 Omnibus 实例：

   sudo editor /etc/gitlab/gitlab.rb
   

   对于源安装实例：

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

2. 添加 provider 配置：

   对于 Omnibus 实例：

   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. 如果您通过 Omnibus 或从源安装 GitLab，重新配置或 重启极狐GitLab 使更改生效。

使用 FortiToken Cloud 启用一次性密码

您可以使用 FortiToken Cloud 作为 GitLab 中的一次性密码 (OTP) 提供程序。 用户必须：

• 以相同的用户名存在于 FortiToken Cloud 和 GitLab。
• 在 FortiToken Cloud 中配置 FortiToken。

您需要一个 client_id 和 client_secret 来配置 FortiToken Cloud。要获取这些信息，请参阅 [Fortinet 文档库] (https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api/456035/overview) 上的 REST API 指南。

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

1. 打开配置文件：

   对于 Omnibus 实例：

   sudo editor /etc/gitlab/gitlab.rb
   

   对于源安装实例：

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

2. 添加 provider 配置：

   对于 Omnibus 实例：

   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. 如果您通过 Omnibus 或从源安装 GitLab，重新配置或重启极狐GitLab 以使更改生效。

设置 U2F 设备

官方只支持 YubiKey U2F 设备，但用户已经成功使用过 SoloKeys 或 Google Titan Security Key。

U2F 工作流由以下桌面浏览器支持：

• Chrome
• Edge
• Opera
• Firefox 67+，对于 Firefox 47-66：
  1. 在 about:config 中启用 FIDO U2F API。
  2. 搜索 security.webauth.u2f 并选择它，切换到 true。

要使用 U2F 设备设置 2FA：

1. 访问您的用户设置。
2. 选择 帐户。
3. 选择 启用双重认证。
4. 连接您的 U2F 设备。
5. 选择 设置新的 U2F 设备。
6. 设备上的灯开始闪烁。通过按下它的按钮来激活它。

将显示一条消息，表明您的设备已成功设置。 单击 注册 U2F 设备 完成该过程。不会为 U2F 设备生成恢复代码。

设置 WebAuthn 设备

• 引入于 13.4 版本，功能标志为 webauthn，默认禁用。
• 在自助管理版上启用于 14.6 版本。

WebAuthn 工作流由以下桌面浏览器支持：

• Chrome
• Edge
• Firefox
• Opera
• Safari

以及以下移动浏览器：

• Chrome for Android
• Firefox for Android
• iOS Safari (since iOS 13.3)

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

1. 访问您的用户设置。
2. 选择 帐户。
3. 选择 启用双重认证。
4. 插入您的 WebAuthn 设备。
5. 选择 设置新的 WebAuthn 设备。
6. 根据您的设备，您可能需要按下按钮或触摸传感器。

将显示一条消息，表明您的设备已成功设置。 不会为 WebAuthn 设备生成恢复码。

恢复码

使用一次性密码成功启用 2FA 后，系统会立即提示您下载一组生成的恢复码。如果您无法访问一次性密码验证器，您可以使用这些恢复码之一登录您的帐户。

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

如果您丢失了恢复码，或者想要生成新码，您可以使用以下任一方法：

• 2FA 帐户设置页面。
• SSH。

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

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

1. 访问您的用户设置。
2. 选择 帐户 > 双重身份验证 (2FA)。
3. 如果您已经配置了 2FA，请选择 管理双重认证。
4. 在 注册双重认证 窗格中，输入您的当前密码并选择 重新生成恢复码。

在启用 2FA 的情况下登录

在启用 2FA 的情况下登录仅与正常登录过程略有不同。输入您的用户名和密码，您会看到第二个提示，具体取决于您启用的 2FA 类型。

使用一次性密码登录

当系统询问时，输入来自一次性密码验证器应用程序的 PIN 码或恢复码以登录。

使用 U2F 设备登录

要使用 U2F 设备登录：

1. 选择 通过 U2F 设备登录。
2. 设备上的灯开始闪烁。通过触摸/按下其按钮激活它。

将显示一条消息，表明您的设备已响应身份验证请求，并且您已自动登录。

使用 WebAuthn 设备登录

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

将显示一条消息，表明您的设备已响应身份验证请求并且您已自动登录。

禁用双重认证

如果您需要禁用 2FA：

1. 访问您的用户设置。
2. 进入 帐户。
3. 选择 管理双重认证。
4. 在 注册双重认证下，输入您当前的密码并选择 禁用双重认证。

将清除您所有的双重身份验证注册，包括移动应用程序和 U2F/WebAuthn 设备。

恢复选项

如果您无权访问您的代码生成设备，您可以使用以下方法恢复对您帐户的访问权限：

• 使用保存的恢复码，如果您在启用双重身份认证时保存了它们。
• 使用 SSH 生成新的恢复码，如果您没有保存原始恢复码但有 SSH 密钥。

使用保存的恢复码

为您的帐户启用双重身份验证会生成多个恢复码。如果您保存了这些代码，则可以使用其中之一登录。

要使用恢复代码，请在登录页面上输入您的用户名/电子邮件和密码。当提示输入双重码时，输入恢复码。

使用恢复码后，您将无法重复使用它。您仍然可以使用您保存的其他恢复码。

使用 SSH 生成新恢复码

用户在启用双重身份验证时经常忘记保存他们的恢复码。如果将 SSH 密钥添加到您的帐户，您可以使用 SSH 生成一组新的恢复码：

1. 在终端中运行：

   ssh git@jihulab.com 2fa_recovery_codes
   

   在自助实例上，将上面命令中的 jihulab.com 替换为 GitLab 服务器主机名（gitlab.example.com）。

2. 系统会提示您确认要生成新码。继续这个过程会使之前保存的码失效：

   Are you sure you want to generate new two-factor recovery codes?
   Any existing recovery codes you saved will be invalidated. (yes/no)
   
   yes
   
   Your two-factor authentication recovery codes are:
   
   119135e5a3ebce8e
   11f6v2a498810dcd
   3924c7ab2089c902
   e79a3398bfe4f224
   34bd7b74adbc8861
   f061691d5107df1a
   169bf32a18e63e7f
   b510e7422e81c947
   20dbed24c5e74663
   df9d3b9403b9c9f0
   
   During sign in, use one of the codes above when prompted for your
   two-factor code. Then, visit your Profile Settings and add a new device
   so you do not lose access to your account again.
   

3. 转到登录页面并输入您的用户名/电子邮件和密码。当提示输入双重认证码时，输入从命令行输出中获得的恢复码之一。

登录后，立即使用新设备设置 2FA。

管理员注意事项

• 您需要特别注意在 恢复 GitLab 备份后 2FA 继续工作。
• 为确保 2FA 与 TOTP 服务器正确授权，您可能需要确保您的 GitLab 服务器的时间通过 NTP 等服务同步。否则，您可能会遇到由于时差导致授权总是失败的情况。

• 当 GitLab 实例从多个主机名或 FQDN 访问时，GitLab U2F 和 WebAuthn 实现不会工作。每个 U2F 或 WebAuthn 注册都链接到注册时的当前主机名，并且不能用于其他主机名/FQDN。这同样适用于 WebAuthn 注册。

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

  • 用户使用 first.host.xyz 登录并注册他们的 U2F 密钥。
  • 用户注销并尝试使用 first.host.xyz 登录 - U2F 身份验证成功。
  • 用户注销并尝试使用 second.host.xyz 登录 - U2F 身份验证失败，因为 U2F 密钥仅在 first.host.xyz 上注册。

故障排查

如果您收到 invalid pin code 错误，这可能表明身份验证应用程序和实例本身之间存在时间同步问题。

为避免时间同步问题，请在生成代码的设备中启用时间同步。 例如：

• 对于 Android（谷歌身份验证器）：
  1. 进入 Google Authenticator 的主菜单。
  2. 选择设置。
  3. 选择代码的时间校正。
  4. 选择立即同步。
• 对于 iOS：
  1. 进入设置。
  2. 选择常规。
  3. 选择日期和时间。
  4. 启用自动设置。如果已启用，请将其禁用，等待几秒钟，然后重新启用。