@@ -6,53 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Two-factor authentication **(FREE)**
Two-factor authentication (2FA) provides an additional level of security to your
GitLab account. After being enabled, in addition to supplying your username and
password to sign in, you are prompted for a code generated by your one-time
password authenticator (for example, a password manager on one of your devices).
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.
By enabling 2FA, the only way someone other than you can sign in to your account
is to know your username and password _and_ have access to your one-time
password secret.
GitLab supports as a second factor of authentication:
## Overview
- Time-based one-time passwords ([TOTP](https://datatracker.ietf.org/doc/html/rfc6238)). When enabled, GitLab prompts
you for a code when you sign in. Codes are generated by your one-time password authenticator (for example, a password
manager on one of your devices).
- U2F or WebAuthn devices. You're prompted to activate your U2F or WebAuthn device (usually by pressing a button on it) when
you supply your username and password to sign in. This performs secure authentication on your behalf.
NOTE:
When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)!
If you set up a device, also set up a TOTP so you can still access your account if you lose the device.
In addition to time-based one-time passwords ([TOTP](https://datatracker.ietf.org/doc/html/rfc6238)), GitLab supports WebAuthn devices as the second factor of authentication. After being enabled, in addition to supplying your username
and password to sign in, you're prompted to activate your U2F / WebAuthn device
(usually by pressing a button on it) which performs secure authentication on
your behalf.
## Use personal access tokens with two-factor authentication
It's highly recommended that you set up 2FA with both a [one-time password authenticator](#one-time-password)
or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator) and a
[U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can
still access your account if you lose your U2F / WebAuthn device.
When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md).
You must use a [personal access token](../personal_access_tokens.md) instead.
## Enabling 2FA
## Enable two-factor authentication
> - Account email confirmation requirement [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3. [Deployed behind the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md), enabled by default.
> - Account email confirmation requirement generally available and [feature flag `ensure_verified_primary_email_for_2fa` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340151) in GitLab 14.4.
There are multiple ways to enable two-factor authentication (2FA):
You can enable 2FA:
- Using a one-time password authenticator.
- Using a U2F / WebAuthn device.
- Using a one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes).
- Using a U2F or WebAuthn device.
In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication.
In GitLab 14.3 and later, your account email must be confirmed to enable 2FA.
### One-time password
### Enable one-time password
To enable 2FA:
To enable 2FA with a one-time password:
1.**In GitLab:**
1. Sign in to your GitLab account.
1. Go to your [**User settings**](../index.md#access-your-user-settings).
1. Go to **Account**.
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. In the application, add a new entry in one of two ways:
- Scan the code presented in GitLab with your device's camera to add the
entry automatically.
- Scan the code displayed by GitLab with your device's camera to add the entry automatically.
- Enter the details provided to add the entry manually.
1.**In GitLab:**
1. Enter the six-digit pin number from the entry on your device into the **Pin
code** field.
1. Enter the six-digit pin number from the entry on your device into **Pin code**.
1. Enter your current password.
1. Select **Submit**.
If the pin you entered was correct, a message displays indicating that
two-factor authentication has been enabled, and you're shown a list
of [recovery codes](#recovery-codes). Be sure to download them and keep them
If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them
in a safe place.
### One-time password via FortiAuthenticator
### Enable one-time password using FortiAuthenticator
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5 [with a flag](../../../administration/feature_flags.md) named `forti_authenticator`. Disabled by default.
FLAG:
On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to
[enable the feature flag](../../../administration/feature_flags.md) named `forti_authenticator`. On GitLab.com, this
feature is not available.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212312) in GitLab 13.5.
> - It's deployed behind a feature flag, disabled by default.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration).
You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must:
You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must exist in
both FortiAuthenticator and GitLab with the exact same username, and users must
have FortiToken configured in FortiAuthenticator.
- Exist in both FortiAuthenticator and GitLab with the same username.
- Have FortiToken configured in FortiAuthenticator.
You need a username and access token for FortiAuthenticator. The
`access_token` in the code samples shown below is the FortAuthenticator access
key. To get the token, see the `REST API Solution Guide` at
or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source)
for the changes to take effect if you installed GitLab via Omnibus or from
source respectively.
#### Enable FortiAuthenticator integration
This feature comes with the `:forti_authenticator` feature flag disabled by
default.
To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags)
to run the following command:
1.[Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)(Omnibus GitLab) or
[restart](../../../administration/restart_gitlab.md#installations-from-source)(GitLab installed from source).
### Enable one-time password using FortiToken Cloud
### One-time password via FortiToken Cloud
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7.
> - It's deployed behind a feature flag, disabled by default.
> - It's disabled on GitLab.com.
> - It's not recommended for production use.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-fortitoken-cloud-integration).
FLAG:
On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to
[enable the feature flag](../../../administration/feature_flags.md) named `forti_token_cloud`. On GitLab.com, this
feature is not available. The feature is not ready for production use.
WARNING:
This feature might not be available to you. Check the **version history** note above for details.
You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must:
You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must exist in
both FortiToken Cloud and GitLab with the exact same username, and users must
have FortiToken configured in FortiToken Cloud.
- Exist in both FortiToken Cloud and GitLab with the same username.
- Have FortiToken configured in FortiToken Cloud.
You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud.
Search for `security.webauth.u2f` and double click on it to toggle to `true`.
1. Enable the FIDO U2F API in [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
1. Search for `security.webauth.u2f` and select it to toggle to `true`.
To set up 2FA with a U2F device:
1. Sign in to your GitLab account.
1. Go to your [**User settings**](../index.md#access-your-user-settings).
1. Go to **Account**.
1. Click **Enable Two-Factor Authentication**.
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Select **Account**.
1. Select **Enable Two-Factor Authentication**.
1. Connect your U2F device.
1.Click on **Set up New U2F Device**.
1.Select on **Set up New U2F Device**.
1. A light begins blinking on your device. Activate it by pressing its button.
A message displays, indicating that your device was successfully set up.
Click on **Register U2F Device** to complete the process.
A message displays indicating that your device was successfully set up. Select **Register U2F Device** to complete the
process. Recovery codes are not generated for U2F devices.
### WebAuthn device
### Set up a WebAuthn device
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `webauthn`. Disabled by default.
> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6.
FLAG:
On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to[disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. On GitLab.com, this feature is available.
The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the
following desktop browsers:
- Chrome
- Edge
-Firefox
- Opera
- Safari
and the following mobile browsers:
-Chrome for Android
- Firefox for Android
- iOS Safari (since iOS 13.3)
To set up 2FA with a WebAuthn compatible device:
1. Sign in to your GitLab account.
1.Go to your [**User settings**](../index.md#access-your-user-settings).
1.Go to**Account**.
On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to
[disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn
feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature.
- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor authentication
as soon as possible.
- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor
authentication as soon as possible.
## Note to GitLab administrators
## Information for GitLab administrators **(FREE SELF)**
- You need to take special care to that 2FA keeps working after
[restoring a GitLab backup](../../../raketasks/backup_restore.md).
- To ensure 2FA authorizes correctly with time-based one time passwords (TOTP) server, you may want to ensure
your GitLab server's time is synchronized via a service like NTP. Otherwise,
you may have cases where authorization always fails because of time differences.
- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to
WebAuthn registrations.
- Take care that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md).
- To ensure 2FA authorizes correctly with a time-based one time passwords (TOTP) server, synchronize your GitLab
server's time using a service like NTP. Otherwise, authorization can always fail because of time differences.
- The GitLab U2F and WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames
or FQDNs. Each U2F or 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`:
...
...
@@ -491,13 +417,13 @@ request a GitLab global administrator disable two-factor authentication for your
- The user signs out and attempts to sign in by using `second.host.xyz` - U2F authentication fails, because
the U2F key has only been registered on `first.host.xyz`.
- To enforce 2FA at the system or group levels see[Enforce Two-factor Authentication](../../../security/two_factor_authentication.md).
- To enforce 2FA at the system or group levels see, [Enforce two-factor authentication](../../../security/two_factor_authentication.md).
## Troubleshooting
If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself.
To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example:
If you receive an `invalid pin code` error, this can indicate that there is a time sync issue between the authentication
application and the GitLab instance itself. To avoid the time sync issue, enable time synchronization in the device that
generates the codes. For example:
- For Android (Google Authenticator):
1. Go to the Main Menu in Google Authenticator.
...
...
@@ -509,15 +435,3 @@ To avoid the time sync issue, enable time synchronization in the device that gen
1. Select General.
1. Select Date & Time.
1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
