Skip to content

G
gitlab-ce
Commit 232c173b authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'eread/ctrt-user-2fa-documentation' into 'master' 

Update topic for CTRT

See merge request gitlab-org/gitlab!77927
parents 45cfec0f 85cbb2ba
Hide whitespace changes
Inline Side-by-side
Showing with 184 additions and 266 deletions
doc/.vale/gitlab/SubstitutionWarning.yml
View file @ 232c173b
......@@ -11,6 +11,7 @@ link: https://about.gitlab.com/handbook/communication/#top-misused-terms
level: warning
ignorecase: true
swap:
click: select
code base: codebase
config: configuration
distro: distribution
......
doc/.vale/gitlab/Uppercase.yml
View file @ 232c173b
......@@ -53,6 +53,7 @@ exceptions:
- EOL
- EXIF
- FAQ
- FIDO
- FIFO
- FIPS
- FLAG
......@@ -179,6 +180,7 @@ exceptions:
- TLS
- TODO
- TOML
- TOTP
- TTL
- UID
- UDP
......
doc/.vale/gitlab/spelling-exceptions.txt
View file @ 232c173b
......@@ -221,6 +221,7 @@ Fluentd
Flycheck
Forgerock
formatters
Fortinet
Fugit
fuzzer
Gantt
......
doc/topics/authentication/index.md
View file @ 232c173b
......@@ -11,7 +11,7 @@ This page gathers all the resources for the topic **Authentication** within GitL
## GitLab users
- [SSH](../../ssh/index.md)
- [Two-factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication)
- [Two-factor authentication](../../user/profile/account/two_factor_authentication.md)
- [Why do I keep getting signed out?](../../user/profile/index.md#why-do-i-keep-getting-signed-out)
- **Articles:**
- [Support for Universal 2nd Factor Authentication - YubiKeys](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/)
......
doc/user/profile/account/two_factor_authentication.md
View file @ 232c173b
......@@ -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. 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/)
......@@ -62,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.
......@@ -133,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.
......@@ -206,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?
......@@ -440,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`:
......@@ -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. -->
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7