summaryrefslogtreecommitdiff
path: root/doc/user/profile/account/two_factor_authentication.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/profile/account/two_factor_authentication.md')
-rw-r--r--doc/user/profile/account/two_factor_authentication.md178
1 files changed, 111 insertions, 67 deletions
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md
index b76b99b5242..fe2e2acaae3 100644
--- a/doc/user/profile/account/two_factor_authentication.md
+++ b/doc/user/profile/account/two_factor_authentication.md
@@ -14,7 +14,7 @@ GitLab supports as a second factor of authentication:
- 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
+- WebAuthn devices. You're prompted to activate your 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.
If you set up a device, also set up a TOTP so you can still access your account if you lose the device.
@@ -42,10 +42,10 @@ Git Credential Manager is developed primarily by GitHub, Inc. It is an open-sour
> - 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.
-You can enable 2FA:
+You can enable 2FA using a:
-- Using a one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes).
-- Using a U2F or WebAuthn device.
+- One-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes).
+- WebAuthn device.
In GitLab 14.3 and later, your account email must be confirmed to enable 2FA.
@@ -60,10 +60,11 @@ To enable 2FA with a one-time password:
1. **On your device (usually your phone):**
1. Install a compatible application. For example:
- Cloud-based (recommended because you can restore access if you lose the hardware device):
- - [Authy](https://authy.com/)
+ - [Authy](https://authy.com/).
+ - [Duo](https://duo.com/).
- Other:
- - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
- - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app)
+ - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en).
+ - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app).
1. In the application, add a new entry in one of two ways:
- 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.
@@ -72,9 +73,6 @@ To enable 2FA with a one-time password:
1. Enter your current password.
1. Select **Submit**.
-NOTE:
-DUO [cannot be used for 2FA](https://gitlab.com/gitlab-org/gitlab/-/issues/15760).
-
If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them
in a safe place.
@@ -141,6 +139,70 @@ Configure FortiAuthenticator in GitLab. On your GitLab server:
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 Duo
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15760) in GitLab 15.10.
+
+FLAG:
+On self-managed GitLab, by default this feature is available. On GitLab.com this feature is not available.
+
+You can use Duo as an OTP provider in GitLab.
+
+#### Prerequisites
+
+To use Duo as an OTP provider:
+
+- Your account must exist in both Duo and GitLab, with the same username in both applications.
+- You must have [configured Duo](https://admin.duosecurity.com/) and have an integration key, secret key, and API hostname.
+
+For more information, see the [Duo API documentation](https://duo.com/docs/authapi).
+
+GitLab 15.10 has been tested with Duo version D261.14
+
+#### Configure Duo in GitLab
+
+On your GitLab server:
+
+1. Open the configuration file.
+
+ For Omnibus GitLab:
+
+ ```shell
+ sudo editor /etc/gitlab/gitlab.rb
+ ```
+
+ For installations from source:
+
+ ```shell
+ cd /home/git/gitlab
+ sudo -u git -H editor config/gitlab.yml
+ ```
+
+1. Add the provider configuration:
+
+ For Omnibus package:
+
+ ```ruby
+ 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 installations from source:
+
+ ```yaml
+ duo_auth:
+ enabled: true
+ hostname: <duo_api_hostname>
+ integration_key: <duo_integration_key_value>
+ secret_key: <duo_secret_key_value>
+ ```
+
+1. Save the configuration file.
+1. For Omnibus GitLab, [reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure).
+ For installations from source, [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source).
+
### 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.
@@ -198,68 +260,61 @@ Configure FortiToken Cloud in GitLab. On your GitLab server:
1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or
[restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source).
-### Set up a U2F device
-
-GitLab officially supports [YubiKey](https://www.yubico.com/products/) U2F devices, but users have successfully used
-[SoloKeys](https://solokeys.com/) and [Google Titan Security Key](https://cloud.google.com/titan-security-key).
-
-U2F is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers:
-
-- Chrome
-- Edge
-- Opera
-- Firefox 67+. For Firefox 47-66:
-
- 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. 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. Select **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. Select **Register U2F Device** to complete the
-process. Recovery codes are not generated for U2F devices.
-
### 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.
+> - WebAuthn devices [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.
+> - WebAuthn devices [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6.
+> - Optional one-time password authentication for WebAuthn devices [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378844) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `webauthn_without_topt`. [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/issues/232671).
FLAG:
-On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to
+On self-managed GitLab, by default, WebAuthn devices are 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, WebAuthn devices are available.
+
+FLAG:
+On self-managed GitLab, by default, optional one-time password authentication for WebAuthn devices is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `webauthn_without_topt`.
On GitLab.com, this feature is available.
-WebAuthn [supported by](https://caniuse.com/#search=webauthn):
+WebAuthn is [supported by](https://caniuse.com/#search=webauthn) the following:
-- The following desktop browsers:
+- Desktop browsers:
- Chrome
- Edge
- Firefox
- Opera
- Safari
-- The following mobile browsers:
+- Mobile browsers:
- Chrome for Android
- Firefox for Android
- iOS Safari (since iOS 13.3)
To set up 2FA with a WebAuthn-compatible device:
+1. Optional. [Set up a one-time password](#enable-one-time-password).
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Select **Account**.
1. Select **Enable Two-Factor Authentication**.
1. Plug in your WebAuthn device.
+1. Enter a device name and in GitLab 15.10 and later, your GitLab account password.
+ You might not need to enter this password if you have signed in through your
+ identity provider.
1. Select **Set up New WebAuthn Device**.
1. Depending on your device, you might have to press a button or touch a sensor.
-A message displays indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn
-devices.
+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](#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.
## Recovery codes
@@ -272,11 +327,11 @@ these recovery codes to sign in to your account.
WARNING:
Each code can be used only once to sign in to your account.
-We recommend copying and printing them, or downloading them using the **Download codes** button for storage in a safe
+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:
-Recovery codes are not generated for U2F or WebAuthn devices.
+Recovery codes are not generated for WebAuthn devices.
If you lose the recovery codes, or want to generate new ones, you can use either:
@@ -302,18 +357,7 @@ and you're presented with a second prompt, depending on which type of 2FA you've
### Sign in using a one-time password
-When asked, enter the pin from your one time password authenticator's application or a recovery code to sign in.
-
-### Sign in using a U2F device
-
-To sign in by using a U2F device:
-
-1. Select **Login via U2F Device**.
-1. A light begins blinking on your device. Activate it by touching/pressing
- its button.
-
-A message displays indicating that your device responded to the authentication request, and you're automatically signed
-in.
+When asked, enter the pin from your one-time password authenticator's application or a recovery code to sign in.
### Sign in using a WebAuthn device
@@ -333,7 +377,7 @@ To disable 2FA:
1. Under **Register Two-Factor Authenticator**, enter your current password and select **Disable two-factor
authentication**.
-This clears all your 2FA registrations, including mobile applications and U2F or WebAuthn devices.
+This clears all your 2FA registrations, including mobile applications and WebAuthn devices.
## Recovery options
@@ -412,18 +456,18 @@ a GitLab global administrator disable 2FA for your account:
## Information for GitLab administrators **(FREE SELF)**
- 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
+- To ensure 2FA authorizes correctly with a time-based one-time password (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
+- 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`:
- - The user signs in by using `first.host.xyz` and registers their U2F key.
- - The user signs out and attempts to sign in by using `first.host.xyz` - U2F authentication succeeds.
- - 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 user signs in by using `first.host.xyz` and registers their WebAuthn key.
+ - The user signs out and attempts to sign in by using `first.host.xyz` - WebAuthn authentication succeeds.
+ - The user signs out and attempts to sign in by using `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](../../../security/two_factor_authentication.md).