diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-01-20 12:16:11 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-01-20 12:16:11 +0300 |
commit | edaa33dee2ff2f7ea3fac488d41558eb5f86d68c (patch) | |
tree | 11f143effbfeba52329fb7afbd05e6e2a3790241 /doc/user/profile/account/two_factor_authentication.md | |
parent | d8a5691316400a0f7ec4f83832698f1988eb27c1 (diff) |
Add latest changes from gitlab-org/gitlab@14-7-stable-eev14.7.0-rc42
Diffstat (limited to 'doc/user/profile/account/two_factor_authentication.md')
-rw-r--r-- | doc/user/profile/account/two_factor_authentication.md | 447 |
1 files changed, 180 insertions, 267 deletions
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 343f8e328ba..3af8c1c1b5a 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -1,59 +1,51 @@ --- stage: Manage -group: Access +group: Authentication & Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # 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), 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. Select **Account**. 1. Select **Enable Two-factor Authentication**. 1. **On your device (usually your phone):** - 1. Install a compatible application, like: + 1. Install a compatible application. For example: - [Authy](https://authy.com/) - [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) - [LastPass Authenticator](https://lastpass.com/auth/) @@ -63,37 +55,36 @@ To enable 2FA: - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) - [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp) 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 -[`Fortinet Document Library`](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). +You need a username and access token for FortiAuthenticator. The `access_token` shown below is the FortAuthenticator +access key. To get the token, see the REST API Solution Guide at +[Fortinet Document Library](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api). GitLab 13.5 has been tested with FortAuthenticator version 6.2.0. -First configure FortiAuthenticator in GitLab. On your GitLab server: +Configure FortiAuthenticator in GitLab. On your GitLab server: 1. Open the configuration file. @@ -134,43 +125,27 @@ First configure FortiAuthenticator in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - 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). -```ruby -Feature.enable(:forti_authenticator, User.find(<user ID>)) -``` +### 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. -To get these, see the `REST API Guide` at -[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api). +You need a `client_id` and `client_secret` to configure FortiToken Cloud. To get these, see the REST API Guide at +[Fortinet Document Library](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api/456035/overview). -First configure FortiToken Cloud in GitLab. On your GitLab server: +Configure FortiToken Cloud in GitLab. On your GitLab server: 1. Open the configuration file. @@ -207,215 +182,184 @@ First configure FortiToken Cloud in GitLab. On your GitLab server: ``` 1. Save the configuration file. -1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) - 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 or disable FortiToken Cloud integration - -FortiToken Cloud integration is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:forti_token_cloud, User.find(<user ID>)) -``` - -To disable it: +1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or + [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). -```ruby -Feature.disable(:forti_token_cloud, User.find(<user ID>)) -``` +### Set up a U2F device -### 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). -GitLab officially only supports [YubiKey](https://www.yubico.com/products/) -U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/) -or [Google Titan Security Key](https://cloud.google.com/titan-security-key). - -NOTE: -2FA must be configured before U2F. - -The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the -following desktop browsers: +U2F is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers: - Chrome - Edge -- Firefox 67+ - Opera +- Firefox 67+. For Firefox 47-66: -NOTE: -For Firefox 47-66, you can enable the FIDO U2F API in -[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). -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. +On GitLab.com, this feature is available. + +WebAuthn [supported by](https://caniuse.com/#search=webauthn): + +- The following desktop browsers: + - Chrome + - Edge + - Firefox + - Opera + - Safari +- 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. 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. Select **Set up New WebAuthn Device**. -1. Depending on your device, you might need to press a button or touch a sensor. +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. +A message displays indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn +devices. ## Recovery codes -NOTE: -Recovery codes are not generated for U2F / WebAuthn devices. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7, **Copy codes** and **Print codes** buttons. + +Immediately after successfully enabling 2FA with a one-time password, you're prompted to download +a set of generated recovery codes. If you ever lose access to your one-time password authenticator, you can use one of +these recovery codes to sign in to your account. WARNING: Each code can be used only once to sign in to your account. -Immediately after successfully enabling two-factor authentication, you're -prompted to download a set of generated recovery codes. Should you ever lose access -to your one-time password authenticator, you can use one of these recovery codes to sign in to -your account. We suggest copying and printing them, or downloading them using -the **Download codes** button for storage in a safe place. If you choose to -download them, the file is called `gitlab-recovery-codes.txt`. +We recommend copying and printing them, or downloading them using the **Download codes** button 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. + +If you lose the recovery codes, or want to generate new ones, you can use either: + +- The [2FA account settings](#regenerate-two-factor-authentication-recovery-codes) page. +- [SSH](#generate-new-recovery-codes-using-ssh). + +### Regenerate two-factor authentication recovery codes -The UI now includes **Copy codes** and **Print codes** buttons, for your convenience. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7. +To regenerate 2FA recovery codes, you need access to a desktop browser: -If you lose the recovery codes or just want to generate new ones, you can do so -from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or -[using SSH](#generate-new-recovery-codes-using-ssh). +1. Access your [**User settings**](../index.md#access-your-user-settings). +1. Select **Account > Two-Factor Authentication (2FA)**. +1. If you've already configured 2FA, select **Manage two-factor authentication**. +1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**. -## Signing in with 2FA Enabled +NOTE: +If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. + +## Sign in with two-factor authentication enabled -Signing in with 2FA enabled is only slightly different than the normal sign-in process. -Enter your username and password credentials as you normally would, and you're -presented with a second prompt, depending on which type of 2FA you've enabled. +Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password +and you're presented with a second prompt, depending on which type of 2FA you've enabled. -### Sign in by using a one-time password +### 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. +When asked, enter the pin from your one time password authenticator's application or a recovery code to sign in. -### Sign in by using a U2F device +### Sign in using a U2F device To sign in by using a U2F device: -1. Click **Login via 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. +A message displays indicating that your device responded to the authentication request, and you're automatically signed +in. -### Sign in by using a WebAuthn device +### Sign in using a WebAuthn device -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. +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. +A message displays indicating that your device responded to the authentication request and you're automatically signed +in. -## Disabling 2FA +## Disable two-factor authentication -If you ever need to disable 2FA: +To disable 2FA: -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. Select **Account**. 1. Select **Manage two-factor authentication**. -1. Under **Two-Factor Authentication**, enter your current password and select **Disable**. - -This clears all your two-factor authentication registrations, including mobile -applications and U2F / WebAuthn devices. +1. Under **Register Two-Factor Authenticator**, enter your current password and select **Disable two-factor + authentication**. -Support for disabling 2FA is limited, depending on your subscription level. For more information, see the -[Account Recovery](https://about.gitlab.com/support/#account-recovery) section of our website. +This clears all your 2FA registrations, including mobile applications and U2F or WebAuthn devices. -## Personal access tokens - -When 2FA is enabled, you can no longer use your normal account password to -authenticate with Git over HTTPS on the command line or when using -the [GitLab API](../../../api/index.md). You must use a -[personal access token](../personal_access_tokens.md) instead. +Support Team support for disabling 2FA is limited, depending on your subscription level. For more information, see the +[Account Recovery](https://about.gitlab.com/support/#account-recovery-and-2fa-resets) section of our website. ## Recovery options -To disable two-factor authentication on your account (for example, if you -have lost your code generation device) you can: +If you don't have access to your code generation device, you can recover access to your account: -- [Use a saved recovery code](#use-a-saved-recovery-code). -- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh). -- [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes). -- [Have 2FA disabled on your account](#have-2fa-disabled-on-your-account). +- [Use a saved recovery code](#use-a-saved-recovery-code), if you saved them when you enabled two-factor + authentication. +- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh), if you didn't save your original + recovery codes but have an SSH key. +- [Have 2FA disabled on your account](#have-two-factor-authentication-disabled-on-your-account), if you don't have your + recovery codes or an SSH key. ### Use a saved recovery code -Enabling two-factor authentication for your account generated several recovery -codes. If you saved these codes, you can use one of them to sign in. +To use a recovery code: -To use a recovery code, enter your username/email and password on the GitLab -sign-in page. When prompted for a two-factor code, enter the recovery code. +1. Enter your username or email, and password, on the GitLab sign-in page. +1. When prompted for a two-factor code, enter the recovery code. -After you use a recovery code, you cannot re-use it. You can still use the other -recovery codes you saved. +After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved. ### Generate new recovery codes using SSH -Users often forget to save their recovery codes when enabling two-factor -authentication. If an SSH key is added to your GitLab account, you can generate -a new set of recovery codes with SSH: +Users often forget to save their recovery codes when enabling 2FA. If you added an SSH key to your +GitLab account, you can generate a new set of recovery codes with SSH: -1. Run: +1. In a terminal, run: ```shell ssh git@gitlab.com 2fa_recovery_codes ``` - NOTE: - On self-managed instances, replace **`gitlab.com`** in the command above - with the GitLab server hostname (`gitlab.example.com`). + On self-managed instances, replace **`gitlab.com`** in the command above with the GitLab server hostname (`gitlab.example.com`). -1. You are prompted to confirm that you want to generate new codes. - Continuing this process invalidates previously saved codes: +1. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For + example: ```shell Are you sure you want to generate new two-factor recovery codes? @@ -441,49 +385,30 @@ a new set of recovery codes with SSH: so you do not lose access to your account again. ``` -1. Go to the GitLab sign-in page and enter your username/email and password. - When prompted for a two-factor code, enter one of the recovery codes obtained - from the command-line output. - -After signing in, visit your **User settings > Account** immediately to set -up two-factor authentication with a new device. - -### Regenerate 2FA recovery codes - -To regenerate 2FA recovery codes, you need access to a desktop browser: - -1. Navigate to GitLab. -1. Sign in to your GitLab account. -1. Go to your [**User settings**](../index.md#access-your-user-settings). -1. Select **Account > Two-Factor Authentication (2FA)**. -1. If you've already configured 2FA, click **Manage two-factor authentication**. -1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**. +1. Go to the GitLab sign-in page and enter your username or email, and password. When prompted for a two-factor code, + enter one of the recovery codes obtained from the command-line output. -NOTE: -If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes. +After signing in, immediately set up 2FA with a new device. -### Have 2FA disabled on your account +### Have two-factor authentication disabled on your account **(PREMIUM SAAS)** -If you can't use a saved recovery code or generate new recovery codes, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to -request a GitLab global administrator disable two-factor authentication for your account. Note that: +If other methods are unavailable, submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) to request +a GitLab global administrator disable 2FA for your account: - Only the owner of the account can make this request. - This service is only available for accounts that have a GitLab.com subscription. For more information, see our [blog post](https://about.gitlab.com/blog/2020/08/04/gitlab-support-no-longer-processing-mfa-resets-for-free-users/). -- 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`: @@ -492,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. @@ -510,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. --> |