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

538 lines
20 KiB
Markdown
Raw Normal View History

2019-10-12 21:52:04 +05:30
---
2020-06-23 00:09:42 +05:30
stage: Manage
group: Access
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
2020-07-28 23:09:34 +05:30
Two-factor authentication (2FA) provides an additional level of security to your
2021-01-29 00:20:46 +05:30
GitLab account. After being enabled, in addition to supplying your username and
2021-02-22 17:27:13 +05:30
password to sign in, you are prompted for a code generated by your one-time
2021-01-29 00:20:46 +05:30
password authenticator (for example, a password manager on one of your devices).
2017-08-17 22:00:37 +05:30
2021-01-29 00:20:46 +05:30
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.
2017-08-17 22:00:37 +05:30
## Overview
2021-02-22 17:27:13 +05:30
NOTE:
2019-09-30 21:07:59 +05:30
When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)!
In addition to time-based one time passwords (TOTP), GitLab supports U2F
2021-02-22 17:27:13 +05:30
(universal 2nd factor) and WebAuthn (experimental) 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.
2019-09-30 21:07:59 +05:30
2021-02-22 17:27:13 +05:30
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.
2017-08-17 22:00:37 +05:30
## Enabling 2FA
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
There are multiple ways to enable two-factor authentication (2FA):
- Using a one-time password authenticator.
- Using a U2F / WebAuthn device.
In GitLab 14.3 and later, your account email must be confirmed to enable two-factor authentication.
2021-01-29 00:20:46 +05:30
### One-time password
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
To enable 2FA:
1. **In GitLab:**
2021-01-29 00:20:46 +05:30
1. Sign in to your GitLab account.
2021-04-17 20:07:23 +05:30
1. Go to your [**User settings**](../index.md#access-your-user-settings).
2019-09-30 21:07:59 +05:30
1. Go to **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):**
1. Install a compatible application, like:
2021-04-17 20:07:23 +05:30
- [Authy](https://authy.com/)
- [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app)
2021-06-08 01:23:25 +05:30
- [LastPass Authenticator](https://lastpass.com/auth/)
2021-04-17 20:07:23 +05:30
- [Authenticator](https://mattrubin.me/authenticator/)
- [andOTP](https://github.com/andOTP/andOTP)
- [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
2021-12-11 22:18:48 +05:30
- [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app)
2021-04-17 20:07:23 +05:30
- [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp)
2019-09-30 21:07:59 +05:30
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.
- 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.
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
2021-02-22 17:27:13 +05:30
If the pin you entered was correct, a message displays indicating that
two-factor authentication has been enabled, and you're shown a list
2021-01-29 00:20:46 +05:30
of [recovery codes](#recovery-codes). Be sure to 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
2021-01-29 00:20:46 +05:30
### One-time password via FortiAuthenticator
> - Introduced in [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/212312)
> - 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 an 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.
2021-02-22 17:27:13 +05:30
You need a username and access token for FortiAuthenticator. The
2021-01-29 00:20:46 +05:30
`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).
GitLab 13.5 has been tested with FortAuthenticator version 6.2.0.
First configure FortiAuthenticator in GitLab. On your GitLab server:
1. Open the configuration file.
For Omnibus GitLab:
```shell
sudo editor /etc/gitlab/gitlab.rb
```
For installations from source:
```shell
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
1. Add the provider configuration:
For Omnibus package:
```ruby
gitlab_rails['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.
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:
```ruby
Feature.enable(:forti_authenticator, User.find(<user ID>))
```
2021-02-22 17:27:13 +05:30
### One-time password via FortiToken Cloud
> - Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/212313).
> - 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).
WARNING:
This feature might not be available to you. Check the **version history** note above for details.
You can use FortiToken Cloud as an 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.
You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud.
To get these, see the `REST API Guide` at
2021-04-17 20:07:23 +05:30
[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api).
2021-02-22 17:27:13 +05:30
First configure FortiToken Cloud in GitLab. On your GitLab server:
1. Open the configuration file.
For Omnibus GitLab:
```shell
sudo editor /etc/gitlab/gitlab.rb
```
For installations from source:
```shell
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
```
1. Add the provider configuration:
For Omnibus package:
```ruby
gitlab_rails['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.
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:
```ruby
Feature.disable(:forti_token_cloud, User.find(<user ID>))
```
2021-01-29 00:20:46 +05:30
### U2F device
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
GitLab officially only supports [YubiKey](https://www.yubico.com/products/)
2020-06-23 00:09:42 +05:30
U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/)
or [Google Titan Security Key](https://cloud.google.com/titan-security-key).
2019-09-30 21:07:59 +05:30
2021-12-11 22:18:48 +05:30
NOTE:
2FA must be configured before U2F.
2019-09-30 21:07:59 +05:30
The U2F workflow 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
2020-06-23 00:09:42 +05:30
- Firefox 67+
2019-09-30 21:07:59 +05:30
- Opera
2021-02-22 17:27:13 +05:30
NOTE:
2020-06-23 00:09:42 +05:30
For Firefox 47-66, you can enable the FIDO U2F API in
2021-03-11 19:13:27 +05:30
[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
2019-09-30 21:07:59 +05:30
Search for `security.webauth.u2f` and double click on it to toggle to `true`.
To set up 2FA with a U2F device:
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
1. Sign in to your GitLab account.
2021-04-17 20:07:23 +05:30
1. Go to your [**User settings**](../index.md#access-your-user-settings).
2017-08-17 22:00:37 +05:30
1. Go to **Account**.
1. Click **Enable Two-Factor Authentication**.
2020-10-24 23:57:45 +05:30
1. Connect your U2F device.
2018-12-05 23:21:45 +05:30
1. Click on **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
2021-02-22 17:27:13 +05:30
A message displays, indicating that your device was successfully set up.
2017-08-17 22:00:37 +05:30
Click on **Register U2F Device** to complete the process.
2021-01-29 00:20:46 +05:30
### WebAuthn device
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4.
> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
> - It's disabled on GitLab.com.
> - It's not recommended for production use.
2021-03-11 19:13:27 +05:30
> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(FREE SELF)**
2021-01-29 00:20:46 +05:30
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.
2021-04-17 20:07:23 +05:30
1. Go to your [**User settings**](../index.md#access-your-user-settings).
2021-01-29 00:20:46 +05:30
1. Go to **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.
2021-02-22 17:27:13 +05:30
A message displays, indicating that your device was successfully set up.
2021-01-29 00:20:46 +05:30
Recovery codes are not generated for WebAuthn devices.
2019-09-30 21:07:59 +05:30
## Recovery codes
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-29 00:20:46 +05:30
Recovery codes are not generated for U2F / WebAuthn devices.
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
2021-02-22 17:27:13 +05:30
Immediately after successfully enabling two-factor authentication, you're
2020-10-24 23:57:45 +05:30
prompted to download a set of generated recovery codes. Should you ever lose access
2021-03-08 18:12:59 +05:30
to your one-time password authenticator, you can use one of these recovery codes to sign in to
2020-10-24 23:57:45 +05:30
your account. We suggest copying and printing them, or downloading them using
2019-09-30 21:07:59 +05:30
the **Download codes** button for storage in a safe place. If you choose to
2021-02-22 17:27:13 +05:30
download them, the file is called `gitlab-recovery-codes.txt`.
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.
2019-09-30 21:07:59 +05:30
2017-08-17 22:00:37 +05:30
If you lose the recovery codes or just want to generate new ones, you can do so
2020-04-08 14:13:33 +05:30
from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or
2018-11-18 11:00:15 +05:30
[using SSH](#generate-new-recovery-codes-using-ssh).
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
## Signing in with 2FA Enabled
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
Signing in with 2FA enabled is only slightly different than the normal sign-in process.
2021-02-22 17:27:13 +05:30
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.
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
### Sign in by using a one-time password
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
When asked, enter the pin from your one time password authenticator's application or a
2021-03-08 18:12:59 +05:30
recovery code to sign in.
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
### Sign in by 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
2019-09-30 21:07:59 +05:30
1. Click **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
2021-02-22 17:27:13 +05:30
A message displays, indicating that your device responded to the authentication
2021-03-08 18:12:59 +05:30
request, and you're automatically signed in.
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
### Sign in by using a WebAuthn device
2021-01-29 00:20:46 +05:30
In supported browsers you should be automatically prompted to activate your WebAuthn device
(e.g. by touching/pressing its button) after entering your credentials.
2021-02-22 17:27:13 +05:30
A message displays, indicating that your device responded to the authentication
2021-03-08 18:12:59 +05:30
request and you're automatically signed in.
2021-01-29 00:20:46 +05:30
2017-08-17 22:00:37 +05:30
## Disabling 2FA
2019-09-30 21:07:59 +05:30
If you ever need to disable 2FA:
2021-03-08 18:12:59 +05:30
1. Sign in to your GitLab account.
2021-04-17 20:07:23 +05:30
1. Go to your [**User settings**](../index.md#access-your-user-settings).
2017-08-17 22:00:37 +05:30
1. Go to **Account**.
2021-09-30 23:02:18 +05:30
1. Select **Manage two-factor authentication**.
1. Under **Two-Factor Authentication**, enter your current password and select **Disable**.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
This clears all your two-factor authentication registrations, including mobile
2021-01-29 00:20:46 +05:30
applications and U2F / WebAuthn devices.
2017-08-17 22:00:37 +05:30
2021-03-08 18:12:59 +05:30
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.
2017-08-17 22:00:37 +05:30
## Personal access tokens
When 2FA is enabled, you can no longer use your normal account password to
2017-09-10 17:25:29 +05:30
authenticate with Git over HTTPS on the command line or when using
2021-09-30 23:02:18 +05:30
the [GitLab API](../../../api/index.md). You must use a
2019-09-30 21:07:59 +05:30
[personal access token](../personal_access_tokens.md) instead.
2017-08-17 22:00:37 +05:30
## Recovery options
To disable two-factor authentication on your account (for example, if you
have lost your code generation device) you can:
2017-09-10 17:25:29 +05:30
2019-03-02 22:35:43 +05:30
- [Use a saved recovery code](#use-a-saved-recovery-code).
- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh).
2020-04-08 14:13:33 +05:30
- [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes).
2021-11-11 11:23:49 +05:30
- [Have 2FA disabled on your account](#have-2fa-disabled-on-your-account).
2017-08-17 22:00:37 +05:30
### 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, enter your username/email and password on the GitLab
sign-in page. When prompted for a two-factor code, enter the recovery code.
2021-03-11 19:13:27 +05:30
After you use a recovery code, you cannot re-use it. You can still use the other
2017-09-10 17:25:29 +05:30
recovery codes you saved.
2017-08-17 22:00:37 +05:30
### 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
2019-09-30 21:07:59 +05:30
a new set of recovery codes with SSH:
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
1. 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
2021-03-08 18:12:59 +05:30
NOTE:
On self-managed instances, replace **`gitlab.com`** in the command above
with the GitLab server hostname (`gitlab.example.com`).
2021-02-22 17:27:13 +05:30
1. You are prompted to confirm that you want to generate new codes.
2019-09-30 21:07:59 +05:30
Continuing this process invalidates previously saved codes:
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
2019-02-15 15:39:39 +05:30
1. Go to the GitLab sign-in page and enter your username/email and password.
2017-09-10 17:25:29 +05:30
When prompted for a two-factor code, enter one of the recovery codes obtained
from the command-line output.
2021-03-11 19:13:27 +05:30
After signing in, visit your **User settings > Account** immediately to set
2017-09-10 17:25:29 +05:30
up two-factor authentication with a new device.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
### 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.
2021-04-17 20:07:23 +05:30
1. Go to your [**User settings**](../index.md#access-your-user-settings).
2021-03-11 19:13:27 +05:30
1. Select **Account > Two-Factor Authentication (2FA)**.
2020-04-08 14:13:33 +05:30
1. If you've already configured 2FA, click **Manage two-factor authentication**.
2021-09-30 23:02:18 +05:30
1. In the **Register Two-Factor Authenticator** pane, enter your current password and select **Regenerate recovery codes**.
2020-04-08 14:13:33 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes.
2020-04-08 14:13:33 +05:30
2021-11-11 11:23:49 +05:30
### Have 2FA disabled on your account
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
If you cannot use a saved recovery code or generate new recovery codes then please submit a [support ticket](https://support.gitlab.com/hc/en-us/requests/new) requesting that a GitLab global administrator disables two-factor authentication for your account. Please note that only the actual owner of the account can make this request and that disabling this setting will temporarily leave your account in a less secure state. You should therefore sign in and re-enable two-factor authentication as soon as possible.
2017-08-17 22:00:37 +05:30
## Note to GitLab administrators
- You need to take special care to that 2FA keeps working after
2017-09-10 17:25:29 +05:30
[restoring a GitLab backup](../../../raketasks/backup_restore.md).
2017-08-17 22:00:37 +05:30
- To ensure 2FA authorizes correctly with TOTP server, you may want to ensure
2019-07-07 11:18:12 +05:30
your GitLab server's time is synchronized via a service like NTP. Otherwise,
2017-09-10 17:25:29 +05:30
you may have cases where authorization always fails because of time differences.
2017-08-17 22:00:37 +05:30
- The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
2017-09-10 17:25:29 +05:30
multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
2021-01-29 00:20:46 +05:30
the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to
WebAuthn registrations.
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
2020-04-22 19:07:51 +05:30
- To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md).
2021-03-11 19:13:27 +05:30
## Enable or disable WebAuthn **(FREE SELF)**
2021-01-29 00:20:46 +05:30
Support for WebAuthn 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(:webauthn)
```
To disable it:
```ruby
Feature.disable(:webauthn)
```
2019-12-21 20:55:43 +05:30
## 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.
2021-09-04 01:27:46 +05:30
To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example:
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.
2019-12-21 20:55:43 +05:30
2019-10-12 21:52:04 +05:30
<!-- ## 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. -->