双重验证 (BASIC ALL)

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

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

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

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

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

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

OAuth 凭据 helpers

以下 Git 凭据 helpers 使用 OAuth 向极狐GitLab 进行身份验证，与双重身份验证兼容。第一次进行身份验证时，helper 会打开 Web 浏览器，极狐GitLab 会要求您对应用程序进行授权，后续身份验证不需要交互。

Git 凭证管理器（GCM）

Git 凭证管理器 (GCM) 默认使用 OAuth 进行身份验证。GCM 无需任何手动配置即可支持 SaaS。要将 GCM 与私有化部署版结合使用，请参阅技术支持文档。

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

适用于 Windows 的 Git 包括 Git 凭据管理器。

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

git-credential-oauth

git-credential-oauth 支持 SaaS 和几个流行的公开 hosts，无需任何手动配置。要与私有化部署版一起使用，请参阅 git-credential-oauth 自定义 hosts 文档。

许多 Linux 发行版都将 git-credential-oauth 作为一个软件包包含在内。

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

启用双重验证

  • 账户邮箱确认要求引入于 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. 安装兼容的应用程序，例如：
    2. 在应用程序中，通过以下两种方式之一添加新条目：
      • 使用设备的相机扫描极狐GitLab 中显示的二维码以自动添加条目。
      • 输入提供的详细信息以手动添加条目。
  3. 在极狐GitLab 中：
    1. 在 Pin 码 字段中输入您设备上输入的六位数 PIN 码。
    2. 输入您的当前密码。
    3. 选择 提交。
noteDUO 不能用于 2FA。

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

使用 FortiAuthenticator 启用一次性密码

在私有化部署实例上默认禁用，要使其对每个用户可用，请让管理员启用名为 forti_authenticator 的功能标志。

您可以将 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 启用一次性密码

在私有化部署实例上默认禁用，要使其对每个用户可用，请让管理员启用名为 forti_token_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 设备的可选一次性密码身份验证功能引入于 15.10 版本，功能标志为 webauthn_without_topt。在 SaaS 和私有化部署版上默认启用。
在私有化部署实例上，默认情况下此功能可用。要禁用该功能，请让管理员禁用命名为 webauthn 的功能标志。如果您在注册 WebAuthn 设备后禁用 WebAuthn 功能标志，则在您重新启用此功能之前，这些设备将无法使用。

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。

note不会为 U2F 或 WebAuthn 设备生成恢复码。

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

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

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

  1. 访问您的用户设置。
  2. 选择 账户 > 双重身份验证 (2FA)。
  3. 如果您已经配置了 2FA，请选择 管理双重认证。
  4. 在 注册双重认证 窗格中，输入您的当前密码并选择 重新生成恢复码。
note如果您重新生成 2FA 恢复码，请保存它们。您不能使用任何以前创建的 2FA 码。

在启用 2FA 的情况下登录

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

使用一次性密码登录

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

使用 U2F 设备登录

要使用 U2F 设备登录：

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

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

使用 WebAuthn 设备登录

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

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

禁用双重认证

如果您需要禁用 2FA：

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

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

恢复选项

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

使用保存的恢复码

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

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

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

使用 SSH 生成新恢复码

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

  1. 在终端中运行： 

    ssh git@jihulab.com 2fa_recovery_codes
    note在自助实例上，将上面命令中的 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 上注册。

故障排查

错误：”HTTP Basic: Access denied. The provided password or token …”

发出请求时，您可能会收到以下错误： 

HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal
access token instead of a password.

在以下情况下会出现此错误：

相反，您可以进行身份验证：

错误：”invalid pin code”

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

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

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