@@ -6,53 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w
...
@@ -6,53 +6,46 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Two-factor authentication **(FREE)**
# Two-factor authentication **(FREE)**
Two-factor authentication (2FA) provides an additional level of security to your
Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access
GitLab account. After being enabled, in addition to supplying your username and
your account, they would need your username and password _and_ access to your second factor of authentication.
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).
By enabling 2FA, the only way someone other than you can sign in to your account
GitLab supports as a second factor of authentication:
is to know your username and password _and_ have access to your one-time
password secret.
## 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:
If you set up a device, also set up a TOTP so you can still access your account if you lose the device.
When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)!
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
## Use personal access tokens with two-factor authentication
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.
It's highly recommended that you set up 2FA with both a [one-time password authenticator](#one-time-password)
When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md).
or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator) and a
You must use a [personal access token](../personal_access_tokens.md) instead.
[U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can
still access your account if you lose your U2F / WebAuthn device.
## 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 [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.
> - 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 one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes).
- Using a U2F / WebAuthn device.
- 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.**In GitLab:**
1. Sign in to your GitLab account.
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Go to your [**User settings**](../index.md#access-your-user-settings).
1. In the application, add a new entry in one of two ways:
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
- Scan the code displayed by GitLab with your device's camera to add the entry automatically.
entry automatically.
- Enter the details provided to add the entry manually.
- Enter the details provided to add the entry manually.
1.**In GitLab:**
1.**In GitLab:**
1. Enter the six-digit pin number from the entry on your device into the **Pin
1. Enter the six-digit pin number from the entry on your device into **Pin code**.
code** field.
1. Enter your current password.
1. Enter your current password.
1. Select **Submit**.
1. Select **Submit**.
If the pin you entered was correct, a message displays indicating that
If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them
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
in a safe place.
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.
You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must:
> - 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 exist in
- Exist in both FortiAuthenticator and GitLab with the same username.
both FortiAuthenticator and GitLab with the exact same username, and users must
- Have FortiToken configured in FortiAuthenticator.
have FortiToken configured in FortiAuthenticator.
You need a username and access token for FortiAuthenticator. The
You need a username and access token for FortiAuthenticator. The `access_token` shown below is the FortAuthenticator
`access_token` in the code samples shown below is the FortAuthenticator access
access key. To get the token, see the REST API Solution Guide at
key. To get the token, see the `REST API Solution Guide` at
1.[Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)(Omnibus GitLab) or
or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source)
[restart](../../../administration/restart_gitlab.md#installations-from-source)(GitLab installed 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:
```ruby
### Enable one-time password using 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.
FLAG:
> - It's deployed behind a feature flag, disabled by default.
On self-managed GitLab, by default this feature is not available. To make it available per user, ask an administrator to
> - It's disabled on GitLab.com.
[enable the feature flag](../../../administration/feature_flags.md) named `forti_token_cloud`. On GitLab.com, this
> - It's not recommended for production use.
feature is not available. The feature is not ready for production use.
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-fortitoken-cloud-integration).
WARNING:
You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must:
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 exist in
- Exist in both FortiToken Cloud and GitLab with the same username.
both FortiToken Cloud and GitLab with the exact same username, and users must
- Have FortiToken configured in FortiToken Cloud.
have FortiToken configured in FortiToken Cloud.
You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud.
You need a `client_id` and `client_secret` to configure FortiToken Cloud. To get these, see the REST API Guide at
Search for `security.webauth.u2f` and double click on it to toggle to `true`.
To set up 2FA with a U2F device:
To set up 2FA with a U2F device:
1. Sign in to your GitLab account.
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Go to your [**User settings**](../index.md#access-your-user-settings).
1. Select **Account**.
1. Go to **Account**.
1. Select **Enable Two-Factor Authentication**.
1. Click **Enable Two-Factor Authentication**.
1. Connect your U2F device.
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.
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.
A message displays indicating that your device was successfully set up. Select **Register U2F Device** to complete the
Click on **Register U2F Device** to complete the process.
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.
> - [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.
> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6.
FLAG:
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.
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
The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the
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
- Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor
as soon as possible.
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
- Take care that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md).
[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
- To ensure 2FA authorizes correctly with time-based one time passwords (TOTP) server, you may want to ensure
server's time using a service like NTP. Otherwise, authorization can always fail because of time differences.
your GitLab server's time is synchronized via a service like NTP. Otherwise,
- The GitLab U2F and WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames
you may have cases where authorization always fails because of time differences.
or FQDNs. Each U2F or WebAuthn registration is linked to the _current hostname_ at the time of registration, and
- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
cannot be used for other hostnames or FQDNs.
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.
For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
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
...
@@ -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 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`.
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
## 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.
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
To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example:
generates the codes. For example:
- For Android (Google Authenticator):
- For Android (Google Authenticator):
1. Go to the Main Menu in 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
...
@@ -509,15 +435,3 @@ To avoid the time sync issue, enable time synchronization in the device that gen
1. Select General.
1. Select General.
1. Select Date & Time.
1. Select Date & Time.
1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable.
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. -->
