doc/user/profile/account/two_factor_authentication.md
{{< details >}}
{{< /details >}}
Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access your account, they would need your username and password and access to your second factor of authentication.
GitLab supports the following 2FA methods:
If you set up a device, also set up an OTP so you can still access your account if you lose the device.
To enable 2FA, verify your email address and register an OTP authenticator, a WebAuthn device, or email OTP.
[!warning] If you lose access to your OTP authenticator, you might be locked out of your account.
To minimize this risk:
- Enable cloud backup in your authenticator app.
- Save your backup passwords, secret keys, or recovery credentials in a secure location.
- Review the documentation for your specific OTP authenticator.
To register an OTP authenticator:
If you entered the correct pin, GitLab displays a list of recovery codes. Download them and keep them in a safe place.
If your OTP authenticator supports cloud backups, consider configuring the feature now. For more information, see the documentation for your specific authenticator.
{{< history >}}
webauthn_without_totp.webauthn_without_totp removed.{{< /history >}}
WebAuthn is supported by the following:
To register a WebAuthn-compatible device:
You should receive a message indicating that you successfully set up your device.
When you set up 2FA with a WebAuthn-compatible device, that device is linked to a specific browser on a specific computer. Depending on the browser and WebAuthn device, you might be able to configure settings to use the WebAuthn device on a different browser or computer.
If this is the first time you have set up 2FA, you must download recovery codes so you can recover access to your account if you lose access.
[!warning] You can lose access to your account if you clear your browser data.
{{< history >}}
email_based_mfa. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
Email OTP allows you to verify your identity by sending a six-digit verification code to your email address.
To enable email OTP for your account:
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
You can use Cisco Duo as an OTP provider in GitLab.
DUO® is a registered trademark of Cisco Systems, Inc., and/or its affiliates in the United States and certain other countries.
Prerequisites:
For more information, see the Cisco Duo API documentation.
Open the GitLab configuration file.
For Linux package installations:
sudo editor /etc/gitlab/gitlab.rb
For self-compiled installations:
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
Add the provider configuration.
For Linux package installations:
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>'
For self-compiled installations:
duo_auth:
enabled: true
hostname: <duo_api_hostname>
integration_key: <duo_integration_key_value>
secret_key: <duo_secret_key_value>
Save the configuration file.
For Linux package installations, reconfigure GitLab. For self-compiled installations, restart GitLab.
{{< details >}}
{{< /details >}}
[!flag] On GitLab Self-Managed, by default this feature is not available. To make it available per user, an administrator can enable the feature flag named
forti_authenticator. On GitLab.com and GitLab Dedicated, this feature is not available.
You can use FortiAuthenticator as an OTP provider in GitLab. Users must:
You need a username and access token for FortiAuthenticator. The access_token shown below is the FortiAuthenticator
access key. To get the token, see the REST API Solution Guide at
Fortinet Document Library.
Tested with FortiAuthenticator version 6.2.0.
Configure FortiAuthenticator in GitLab. On your GitLab server:
Open the configuration file.
For Linux package installations:
sudo editor /etc/gitlab/gitlab.rb
For self-compiled installations:
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
Add the provider configuration.
For Linux package installations:
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'
For self-compiled installations:
forti_authenticator:
enabled: true
host: forti_authenticator.example.com
port: 443
username: <some_username>
access_token: s3cr3t
Save the configuration file.
Reconfigure (Linux package installations) or restart (self-compiled installations).
{{< details >}}
{{< /details >}}
[!flag] On GitLab Self-Managed, by default this feature is not available. To make it available per user, an administrator can enable the feature flag named
forti_token_cloud. On GitLab.com and GitLab Dedicated, this feature is not available. This feature is not ready for production use.
You can use FortiToken Cloud as an OTP provider in GitLab. Users must:
You need a client_id and client_secret to configure FortiToken Cloud. To get these, see the REST API Guide at
Fortinet Document Library.
Configure FortiToken Cloud in GitLab. On your GitLab server:
Open the configuration file.
For Linux package installations:
sudo editor /etc/gitlab/gitlab.rb
For self-compiled installations:
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
Add the provider configuration.
For Linux package installations:
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>'
For self-compiled installations:
forti_token_cloud:
enabled: true
client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID
client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET
Save the configuration file.
Reconfigure (Linux package installations) or restart (self-compiled installations).
Immediately after successfully enabling 2FA with an OTP authenticator, you're prompted to download a set of generated recovery codes. If you ever lose access to your OTP authenticator, you can use one of these recovery codes to sign in to your account.
You should copy and print the codes, or use Download codes to download them for storage in a safe
place. If you choose to download them, the file is called gitlab-recovery-codes.txt.
[!note]
- You can use each code only once to sign in to your account.
- Recovery codes are not generated for WebAuthn devices.
For information on regenerating or restoring your recovery codes, see recovery options and 2FA reset.
When 2FA is enabled, you enter your username and password, then use your second authentication method to confirm your identity. The sign in process differs slightly depending on which 2FA method you registered.
When prompted, enter the pin from your OTP authenticator or a recovery code to sign in.
In supported browsers, you should be automatically prompted to activate your WebAuthn device (for example, by touching or pressing its button) after entering your credentials.
A message displays indicating that your device responded to the authentication request and you're automatically signed in.
When prompted, enter the six-digit verification code that is sent to your email. The code remains valid for 60 minutes.
If you are unable to use the access code, you can:
When 2FA is enabled, you cannot use your password to authenticate with Git over HTTPS or the GitLab API. You must use a personal access token instead.
{{< history >}}
{{< /history >}}
You can disable the OTP authenticator and WebAuthn devices individually or simultaneously. To disable them simultaneously:
Group or instance settings might require your account to use 2FA. On GitLab.com, password-based sign-ins must complete email OTP verification.
The following Git credential helpers authenticate to GitLab using OAuth. This is compatible with two-factor authentication. The first time you authenticate, the helper opens the web browser and GitLab asks you to authorize the app. Subsequent authentication requires no interaction.
Git Credential Manager (GCM) authenticates by default using OAuth. GCM supports GitLab.com without any manual configuration. To use GCM with GitLab Self-Managed, see GitLab support.
So you do not need to re-authenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth.
Git for Windows includes Git Credential Manager.
Git Credential Manager is developed primarily by GitHub, Inc. It is an open-source project and is supported by the community.
git-credential-oauth supports GitLab.com and several popular public hosts without any manual configuration needed. To use with GitLab Self-Managed, see the git-credential-oauth custom hosts documentation.
Many Linux distributions include git-credential-oauth as a package.
git-credential-oauth is an open-source project supported by the community.
{{< details >}}
{{< /details >}}
Take care that 2FA keeps working after restoring a GitLab backup.
To ensure 2FA authorizes correctly with an OTP server, synchronize your GitLab server's time using a service like NTP. Otherwise, authorization can always fail because of time differences.
The GitLab WebAuthn implementation does not work when the GitLab instance is accessed from multiple hostnames or FQDNs. Each WebAuthn registration is linked to the current hostname at the time of registration, and cannot be used for other hostnames or FQDNs.
For example, if a user is trying to access a GitLab instance from first.host.xyz and second.host.xyz:
first.host.xyz and registers their WebAuthn key.first.host.xyz - WebAuthn authentication succeeds.second.host.xyz - WebAuthn authentication fails, because
the WebAuthn key has only been registered on first.host.xyz.To enforce 2FA at the system or group levels see, Enforce two-factor authentication.