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

双因素认证

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

双因素认证（2FA）为您的 GitLab 账户提供了额外的安全保护。要让他人访问您的账户，他们需要您的用户名、密码以及访问您的第二种认证因素。

GitLab 支持以下作为第二种认证因素：

一次性密码认证器（OTP）。启用后，GitLab 会在您登录时提示您输入代码。这些代码由您的 OTP 认证器生成（例如，您设备上的密码管理器）。
WebAuthn 设备。当您提供用户名和密码登录时，系统会提示您激活 WebAuthn 设备（通常需要按下设备上的按钮）。这会代表您执行安全认证。

如果您设置了设备，同时也请设置一个 OTP，这样在丢失设备时您仍然可以访问账户。

使用个人访问令牌配合双因素认证

启用 2FA 后，您无法使用密码通过 HTTPS 或 GitLab API 进行认证。您可以使用个人访问令牌代替。

OAuth 凭证助手

以下 Git 凭证助手使用 OAuth 认证到 GitLab。这与双因素认证兼容。第一次认证时，助手会打开浏览器，GitLab 会要求您授权该应用程序。后续认证无需交互。

Git 凭证管理器

Git 凭证管理器（GCM）默认使用 OAuth 认证。GCM 无需任何手动配置即可支持 GitLab.com。要在 GitLab Self-Managed 中使用 GCM，请参阅 GitLab 支持。

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

Git for Windows 包含 Git 凭证管理器。

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

git-credential-oauth

git-credential-oauth 支持 GitLab.com 和几个流行的公共主机，无需任何手动配置。要在 GitLab Self-Managed 中使用，请参阅 git-credential-oauth 自定义主机文档。

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

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

启用双因素认证

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

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

您的账户邮箱必须经过验证才能启用 2FA。

启用一次性密码认证器

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

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

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

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

Offering: GitLab Self-Managed

在 GitLab Self-Managed 上，默认情况下此功能不可用。要让每个用户都能使用此功能，管理员可以启用功能标志 forti_authenticator。在 GitLab.com 和 GitLab Dedicated 上，此功能不可用。

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

同时存在于 FortiAuthenticator 和 GitLab 中，且用户名相同。
在 FortiAuthenticator 中配置了 FortiToken。

您需要 FortiAuthenticator 的用户名和访问令牌。下面显示的 access_token 是 FortAuthenticator 访问密钥。要获取该令牌，请参阅 Fortinet 文档库中的 REST API 解决方案指南。已在 FortAuthenticator 6.2.0 版本上测试。

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

打开配置文件。

对于 Linux 包安装：

sudo editor /etc/gitlab/gitlab.rb

对于自编译安装：

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

添加提供商配置。

对于 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

保存配置文件。
重新配置（Linux 包安装）或重启（自编译安装）。

使用 Cisco Duo 启用一次性密码认证器

Offering: GitLab Self-Managed

您可以在 GitLab 中使用 Cisco Duo 作为 OTP 提供商。

DUO® 是 Cisco Systems, Inc. 及其在美国和其他某些国家的关联公司的注册商标。

先决条件

要在 GitLab 中使用 Cisco Duo 作为 OTP 提供商：

您的账户必须同时存在于 Cisco Duo 和 GitLab 中，且两个应用程序中的用户名相同。
您必须已配置 Cisco Duo 并拥有集成密钥、秘密密钥和 API 主机名。

有关更多信息，请参阅 Cisco Duo API 文档。

GitLab 15.10 已在 Cisco Duo 版本 D261.14 上测试。

在 GitLab 中配置 Cisco Duo

在您的 GitLab 服务器上：

打开配置文件。

对于 Linux 包安装：

sudo editor /etc/gitlab/gitlab.rb

对于自编译安装：

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

添加提供商配置。

对于 Linux 包安装：

 gitlab_rails['duo_auth_enabled'] = false
 gitlab_rails['duo_auth_integration_key'] = '<duo_integration_key_value>'
 gitlab_rails['duo_auth_secret_key'] = '<duo_secret_key_value>'
 gitlab_rails['duo_auth_hostname'] = '<duo_api_hostname>'

对于自编译安装：

duo_auth:
  enabled: true
  hostname: <duo_api_hostname>
  integration_key: <duo_integration_key_value>
  secret_key: <duo_secret_key_value>

保存配置文件。
对于 Linux 包安装，重新配置 GitLab。对于自编译安装，重启 GitLab。

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

Offering: GitLab Self-Managed

在 GitLab Self-Managed 上，默认情况下此功能不可用。要让每个用户都能使用此功能，管理员可以启用功能标志 forti_token_cloud。在 GitLab.com 和 GitLab Dedicated 上，此功能不可用。此功能尚未准备好用于生产环境。

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

同时存在于 FortiToken Cloud 和 GitLab 中，且用户名相同。
在 FortiToken Cloud 中配置了 FortiToken。

您需要 client_id 和 client_secret 来配置 FortiToken Cloud。要获取这些信息，请参阅 Fortinet 文档库中的 REST API 指南。

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

打开配置文件。

对于 Linux 包安装：

sudo editor /etc/gitlab/gitlab.rb

对于自编译安装：

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

添加提供商配置。

对于 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

保存配置文件。
重新配置（Linux 包安装）或重启（自编译安装）。

设置 WebAuthn 设备

WebAuthn 被以下浏览器支持：

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

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

可选。设置 OTP 认证器。
访问您的 用户设置。
选择账户。
选择 启用双因素认证。
插入您的 WebAuthn 设备。
输入设备名称，在 GitLab 15.10 及更高版本中，输入您的 GitLab 账户密码。如果您通过身份提供者登录，可能不需要输入此密码。
选择 设置新的 WebAuthn 设备。
根据您的设备，您可能需要按下按钮或触摸传感器。

您应该会收到一条消息，表明您已成功设置设备。

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

如果您是第一次设置 2FA，您必须下载恢复代码，以便在失去访问权限时可以恢复对账户的访问。

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

恢复代码

成功启用 OTP 认证器的 2FA 后，系统会立即提示您下载一组生成的恢复代码。如果您失去对 OTP 认证器的访问权限，可以使用其中一条恢复代码登录您的账户。

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

您应该复制并打印这些代码，或使用 下载代码 将其下载到安全的地方保存。如果您选择下载，文件名为 gitlab-recovery-codes.txt。

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

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

2FA 账户设置页面。
SSH。

重新生成双因素认证恢复代码

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

访问您的 用户设置。
选择 账户 > 双因素认证 (2FA)。
如果您已经配置了 2FA，请选择 管理双因素认证。
在 禁用双因素认证 部分，选择 重新生成恢复代码。
在对话框中，输入您当前的密码，然后选择 重新生成恢复代码。

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

启用双因素认证后登录

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

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

当系统提示时，输入您 OTP 认证器中的密码或恢复代码以登录。

使用 WebAuthn 设备登录

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

系统会显示一条消息，表明您的设备已响应认证请求，您将自动登录。

禁用双因素认证

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

访问您的 用户设置。
选择账户。
选择 管理双因素认证。
在 禁用双因素认证 部分，选择 禁用双因素认证。
在对话框中，输入您当前的密码，然后选择 禁用双因素认证。

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

GitLab 管理员信息

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

确保在恢复 GitLab 备份后 2FA 仍能正常工作。
为了确保 2FA 能正确通过 OTP 服务器授权，请使用 NTP 等服务同步您的 GitLab 服务器时间。否则，由于时间差异，授权可能会总是失败。
当 GitLab 实例从多个主机名或 FQDN 访问时，GitLab WebAuthn 实现无法正常工作。每个 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，请参阅强制执行双因素认证。