debian-mirror-gitlab/doc/user/profile/account/two_factor_authentication.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

477 lines
21 KiB
Markdown
Raw Normal View History

2019-10-12 21:52:04 +05:30
---
2020-06-23 00:09:42 +05:30
stage: Manage
2022-04-04 11:22:00 +05:30
group: Authentication and Authorization
2021-02-22 17:27:13 +05:30
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
2019-10-12 21:52:04 +05:30
---
2021-04-29 21:17:54 +05:30
# Two-factor authentication **(FREE)**
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
GitLab supports as a second factor of authentication:
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
- 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.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
If you set up a device, also set up a TOTP so you can still access your account if you lose the device.
2019-09-30 21:07:59 +05:30
2022-03-02 08:16:31 +05:30
## Use personal access tokens with two-factor authentication
2019-09-30 21:07:59 +05:30
2022-03-02 08:16:31 +05:30
When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/index.md).
2022-07-23 23:45:48 +05:30
You can use a [personal access token](../personal_access_tokens.md) instead.
## Git Credential Manager
For Git over HTTPS, [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) offers an alternative to personal access tokens. By default, GCM
authenticates using OAuth, opening GitLab in your web browser. The first time you authenticate, GitLab asks you to authorize the app. If you remain signed in to GitLab, subsequent
authentication requires no interaction.
So you don't need to reauthenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth.
GCM supports GitLab.com out the box. To use with self-managed GitLab, see [GitLab support](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/gitlab.md)
documentation.
Git Credential Manager is developed primarily by GitHub, Inc. It is an open-source project and is supported by the community.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
## Enable two-factor authentication
2017-08-17 22:00:37 +05:30
2021-11-18 22:05:49 +05:30
> - 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.
2021-11-11 11:23:49 +05:30
2022-03-02 08:16:31 +05:30
You can enable 2FA:
2021-11-11 11:23:49 +05:30
2022-03-02 08:16:31 +05:30
- Using a one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes).
- Using a U2F or WebAuthn device.
2021-11-11 11:23:49 +05:30
2022-03-02 08:16:31 +05:30
In GitLab 14.3 and later, your account email must be confirmed to enable 2FA.
2021-11-11 11:23:49 +05:30
2022-03-02 08:16:31 +05:30
### Enable one-time password
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
To enable 2FA with a one-time password:
2019-09-30 21:07:59 +05:30
1. **In GitLab:**
2022-03-02 08:16:31 +05:30
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Select **Account**.
2021-01-29 00:20:46 +05:30
1. Select **Enable Two-factor Authentication**.
2019-09-30 21:07:59 +05:30
1. **On your device (usually your phone):**
2022-03-02 08:16:31 +05:30
1. Install a compatible application. For example:
2022-08-27 11:52:29 +05:30
- Cloud-based (recommended because you can restore access if you lose the hardware device):
- [Authy](https://authy.com/)
- [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app)
- Other:
- [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
- [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app)
2019-09-30 21:07:59 +05:30
1. In the application, add a new entry in one of two ways:
2022-03-02 08:16:31 +05:30
- Scan the code displayed by GitLab with your device's camera to add the entry automatically.
2019-09-30 21:07:59 +05:30
- Enter the details provided to add the entry manually.
1. **In GitLab:**
2022-03-02 08:16:31 +05:30
1. Enter the six-digit pin number from the entry on your device into **Pin code**.
2021-09-30 23:02:18 +05:30
1. Enter your current password.
2021-01-29 00:20:46 +05:30
1. Select **Submit**.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them
2019-09-30 21:07:59 +05:30
in a safe place.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
### 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.
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
You can use FortiAuthenticator as a one-time password (OTP) provider in GitLab. Users must:
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
- Exist in both FortiAuthenticator and GitLab with the same username.
- Have FortiToken configured in FortiAuthenticator.
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
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).
2021-01-29 00:20:46 +05:30
GitLab 13.5 has been tested with FortAuthenticator version 6.2.0.
2022-03-02 08:16:31 +05:30
Configure FortiAuthenticator in GitLab. On your GitLab server:
2021-01-29 00:20:46 +05:30
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['forti_authenticator_enabled'] = true
gitlab_rails['forti_authenticator_host'] = 'forti_authenticator.example.com'
gitlab_rails['forti_authenticator_port'] = 443
gitlab_rails['forti_authenticator_username'] = '<some_username>'
gitlab_rails['forti_authenticator_access_token'] = 's3cr3t'
```
For installations from source:
```yaml
forti_authenticator:
enabled: true
host: forti_authenticator.example.com
port: 443
username: <some_username>
access_token: s3cr3t
```
1. Save the configuration file.
2022-03-02 08:16:31 +05:30
1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or
[restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source).
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
### Enable one-time password using FortiToken Cloud
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
> [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.
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
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.
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
You can use FortiToken Cloud as a one-time password (OTP) provider in GitLab. Users must:
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
- Exist in both FortiToken Cloud and GitLab with the same username.
- Have FortiToken configured in FortiToken Cloud.
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
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).
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
Configure FortiToken Cloud in GitLab. On your GitLab server:
2021-02-22 17:27:13 +05:30
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['forti_token_cloud_enabled'] = true
gitlab_rails['forti_token_cloud_client_id'] = '<your_fortinet_cloud_client_id>'
gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>'
```
For installations from source:
```yaml
forti_token_cloud:
enabled: true
client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID
client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET
```
1. Save the configuration file.
2022-03-02 08:16:31 +05:30
1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or
[restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source).
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
### Set up a U2F device
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
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).
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
U2F is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers:
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
- Chrome
- Edge
- Opera
2022-03-02 08:16:31 +05:30
- Firefox 67+. For Firefox 47-66:
2019-09-30 21:07:59 +05:30
2022-03-02 08:16:31 +05:30
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`.
2019-09-30 21:07:59 +05:30
To set up 2FA with a U2F device:
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Select **Account**.
1. Select **Enable Two-Factor Authentication**.
2020-10-24 23:57:45 +05:30
1. Connect your U2F device.
2022-07-23 23:45:48 +05:30
1. Select **Set up New U2F Device**.
2021-02-22 17:27:13 +05:30
1. A light begins blinking on your device. Activate it by pressing its button.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
### Set up a WebAuthn device
2021-01-29 00:20:46 +05:30
2022-01-26 12:08:38 +05:30
> - [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:
2022-03-02 08:16:31 +05:30
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**.
2021-01-29 00:20:46 +05:30
1. Select **Enable Two-Factor Authentication**.
1. Plug in your WebAuthn device.
1. Select **Set up New WebAuthn Device**.
2022-03-02 08:16:31 +05:30
1. Depending on your device, you might have to press a button or touch a sensor.
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
A message displays indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn
devices.
2021-01-29 00:20:46 +05:30
2019-09-30 21:07:59 +05:30
## Recovery codes
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
> [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.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2021-03-08 18:12:59 +05:30
Each code can be used only once to sign in to your account.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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
2021-02-22 17:27:13 +05:30
2022-03-02 08:16:31 +05:30
To regenerate 2FA recovery codes, you need access to a desktop browser:
2019-09-30 21:07:59 +05:30
2022-03-02 08:16:31 +05:30
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**.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
### Sign in using a one-time password
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
When asked, enter the pin from your one time password authenticator's application or a recovery code to sign in.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
### Sign in using a U2F device
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
To sign in by using a U2F device:
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
1. Select **Login via U2F Device**.
2021-02-22 17:27:13 +05:30
1. A light begins blinking on your device. Activate it by touching/pressing
2019-09-30 21:07:59 +05:30
its button.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
A message displays indicating that your device responded to the authentication request, and you're automatically signed
in.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
### Sign in using a WebAuthn device
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
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.
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
A message displays indicating that your device responded to the authentication request and you're automatically signed
in.
2021-01-29 00:20:46 +05:30
2022-03-02 08:16:31 +05:30
## Disable two-factor authentication
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
To disable 2FA:
2019-09-30 21:07:59 +05:30
2022-03-02 08:16:31 +05:30
1. Access your [**User settings**](../index.md#access-your-user-settings).
1. Select **Account**.
2021-09-30 23:02:18 +05:30
1. Select **Manage two-factor authentication**.
2022-03-02 08:16:31 +05:30
1. Under **Register Two-Factor Authenticator**, enter your current password and select **Disable two-factor
authentication**.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
This clears all your 2FA registrations, including mobile applications and U2F or WebAuthn devices.
2021-03-08 18:12:59 +05:30
2017-08-17 22:00:37 +05:30
## Recovery options
2022-03-02 08:16:31 +05:30
If you don't have access to your code generation device, you can recover access to your account:
2017-09-10 17:25:29 +05:30
2022-03-02 08:16:31 +05:30
- [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.
2017-08-17 22:00:37 +05:30
### Use a saved recovery code
2022-03-02 08:16:31 +05:30
To use a recovery code:
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
After you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved.
2017-08-17 22:00:37 +05:30
### Generate new recovery codes using SSH
2022-08-27 11:52:29 +05:30
If you forget to save your recovery codes when enabling 2FA, and you added an SSH key to your GitLab account, you can generate a new set of recovery codes with SSH:
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
1. In a terminal, run:
2019-07-07 11:18:12 +05:30
2020-03-13 15:44:24 +05:30
```shell
2021-03-08 18:12:59 +05:30
ssh git@gitlab.com 2fa_recovery_codes
2019-09-30 21:07:59 +05:30
```
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
On self-managed instances, replace **`gitlab.com`** in the command above with the GitLab server hostname (`gitlab.example.com`).
2021-03-08 18:12:59 +05:30
2022-03-02 08:16:31 +05:30
1. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For
example:
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-09-30 21:07:59 +05:30
Are you sure you want to generate new two-factor recovery codes?
Any existing recovery codes you saved will be invalidated. (yes/no)
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
yes
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
Your two-factor authentication recovery codes are:
119135e5a3ebce8e
11f6v2a498810dcd
3924c7ab2089c902
e79a3398bfe4f224
34bd7b74adbc8861
f061691d5107df1a
169bf32a18e63e7f
b510e7422e81c947
20dbed24c5e74663
df9d3b9403b9c9f0
During sign in, use one of the codes above when prompted for your
two-factor code. Then, visit your Profile Settings and add a new device
so you do not lose access to your account again.
```
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
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.
2020-04-08 14:13:33 +05:30
2022-03-02 08:16:31 +05:30
After signing in, immediately set up 2FA with a new device.
2020-04-08 14:13:33 +05:30
2022-03-02 08:16:31 +05:30
### Have two-factor authentication disabled on your account **(PREMIUM SAAS)**
2017-08-17 22:00:37 +05:30
2022-08-27 11:52:29 +05:30
If other methods are unavailable, have a GitLab support contact submit a [support ticket](https://support.gitlab.com) to request
2022-03-02 08:16:31 +05:30
a GitLab global administrator disable 2FA for your account:
2022-01-26 12:08:38 +05:30
- 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/).
2022-03-02 08:16:31 +05:30
- 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.
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
## Information for GitLab administrators **(FREE SELF)**
2017-08-17 22:00:37 +05:30
2022-03-02 08:16:31 +05:30
- 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.
2017-08-17 22:00:37 +05:30
2019-07-07 11:18:12 +05:30
For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
- 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
2017-08-17 22:00:37 +05:30
the U2F key has only been registered on `first.host.xyz`.
2019-10-12 21:52:04 +05:30
2022-03-02 08:16:31 +05:30
- To enforce 2FA at the system or group levels see, [Enforce two-factor authentication](../../../security/two_factor_authentication.md).
2020-04-22 19:07:51 +05:30
2019-12-21 20:55:43 +05:30
## Troubleshooting
2022-09-01 20:07:04 +05:30
### Error: "HTTP Basic: Access denied. The provided password or token ..."
When making a request, you can receive the following error:
```plaintext
HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal
access token instead of a password.
```
This error occurs in the following scenarios:
- You have 2FA enabled and have attempted to authenticate with a username and
password. For 2FA-enabled users, a [personal access token](../personal_access_tokens.md) (PAT)
must be used instead of a password. To authenticate:
- Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required.
- [GitLab Container Registry](../../packages/container_registry/index.md#authenticate-with-the-container-registry) requests, a PAT
with `read_registry` or `write_registry` scope is required.
- [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with
`read_registry` and `write_registry` scopes is required.
- You do not have 2FA enabled and have sent an incorrect username or password
with your request.
- You do not have 2FA enabled but an administrator has enabled the
[enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting.
- You do not have 2FA enabled, but an administrator has disabled the
[password authentication enabled for Git over HTTP(S)](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled)
setting. If LDAP is:
- Configured, an [LDAP password](../../../administration/auth/ldap/index.md)
or a [personal access token](../personal_access_tokens.md)
must be used to authenticate Git requests over HTTP(S).
- Not configured, you must use a [personal access token](../personal_access_tokens.md).
### Error: "invalid pin code"
2022-03-02 08:16:31 +05:30
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:
2021-09-04 01:27:46 +05:30
2021-09-30 23:02:18 +05:30
- For Android (Google Authenticator):
2021-09-04 01:27:46 +05:30
1. Go to the Main Menu in Google Authenticator.
1. Select Settings.
1. Select the Time correction for the codes.
1. Select Sync now.
- For iOS:
1. Go to Settings.
1. Select General.
1. Select Date & Time.
2021-11-11 11:23:49 +05:30
1. Enable Set Automatically. If it's already enabled, disable it, wait a few seconds, and re-enable.