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

282 lines
12 KiB
Markdown
Raw Normal View History

2019-10-12 21:52:04 +05:30
---
type: howto
---
2017-08-17 22:00:37 +05:30
# Two-Factor Authentication
Two-factor Authentication (2FA) provides an additional level of security to your
GitLab account. Once enabled, in addition to supplying your username and
2018-12-05 23:21:45 +05:30
password to login, you'll be prompted for a code generated by your one time password
authenticator. For example, a password manager on one of your devices.
2017-08-17 22:00:37 +05:30
By enabling 2FA, the only way someone other than you can log into your account
2018-12-05 23:21:45 +05:30
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
2019-09-30 21:07:59 +05:30
TIP: **Tip:**
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
(universal 2nd factor) devices as the second factor of authentication. Once
2019-10-12 21:52:04 +05:30
enabled, in addition to supplying your username and password to log in, you'll
2019-09-30 21:07:59 +05:30
be prompted to activate your U2F device (usually by pressing a button on it),
and it will perform secure authentication on your behalf.
It is highly recommended that you set up 2FA with both a
[one-time password authenticator](#enable-2fa-via-one-time-password-authenticator)
and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account
2019-07-07 11:18:12 +05:30
if you lose your U2F device.
2017-08-17 22:00:37 +05:30
## Enabling 2FA
2018-12-05 23:21:45 +05:30
There are two ways to enable two-factor authentication: via a one time password authenticator
2017-08-17 22:00:37 +05:30
or a U2F device.
2018-12-05 23:21:45 +05:30
### Enable 2FA via one time password authenticator
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
To enable 2FA:
1. **In GitLab:**
1. Log in to your GitLab account.
2020-04-08 14:13:33 +05:30
1. Go to your [**Profile settings**](../index.md#profile-settings).
2019-09-30 21:07:59 +05:30
1. Go to **Account**.
1. Click **Enable Two-factor Authentication**.
1. **On your device (usually your phone):**
1. Install a compatible application, like:
- [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices.
- [andOTP](https://github.com/andOTP/andOTP): feature rich open source app for Android which supports PGP encrypted backups.
- [FreeOTP](https://freeotp.github.io/): open source app for Android.
- [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en): proprietary app for iOS and Android.
2019-12-04 20:38:33 +05:30
- [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp): open source app for SailFish OS.
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.
1. Click **Submit**.
2017-08-17 22:00:37 +05:30
If the pin you entered was correct, you'll see a message indicating that
Two-Factor Authentication has been enabled, and you'll be presented with a list
2019-09-30 21:07:59 +05:30
of [recovery codes](#recovery-codes). Make sure you download them and keep them
in a safe place.
2017-08-17 22:00:37 +05:30
### Enable 2FA via U2F device
2020-04-22 19:07:51 +05:30
GitLab officially only supports [YubiKey](https://www.yubico.com/products/)
2019-09-30 21:07:59 +05:30
U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/).
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
- Firefox (disabled by default)
- Opera
NOTE: **Note:**
For Firefox, 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`.
To set up 2FA with a U2F device:
2017-08-17 22:00:37 +05:30
1. Log in to your GitLab account.
2020-04-08 14:13:33 +05:30
1. Go to your [**Profile settings**](../index.md#profile-settings).
2017-08-17 22:00:37 +05:30
1. Go to **Account**.
1. Click **Enable Two-Factor Authentication**.
1. Plug in your U2F device.
2018-12-05 23:21:45 +05:30
1. Click on **Set up New U2F Device**.
2017-08-17 22:00:37 +05:30
1. A light will start blinking on your device. Activate it by pressing its button.
You will see a message indicating that your device was successfully set up.
Click on **Register U2F Device** to complete the process.
2019-09-30 21:07:59 +05:30
## Recovery codes
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
NOTE: **Note:**
2017-08-17 22:00:37 +05:30
Recovery codes are not generated for U2F devices.
2018-12-05 23:21:45 +05:30
CAUTION: **Caution:**
Each code can be used only once to log in to your account.
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
Immediately after successfully enabling two-factor authentication, you'll be
prompted to download a set of set recovery codes. Should you ever lose access
to your one time password authenticator, you can use one of them to log in to
your account. We suggest copying them, printing them, or downloading them using
the **Download codes** button for storage in a safe place. If you choose to
2019-12-21 20:55:43 +05:30
download them, the file will be called `gitlab-recovery-codes.txt`.
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
## Logging in with 2FA Enabled
Logging in with 2FA enabled is only slightly different than a normal login.
Enter your username and password credentials as you normally would, and you'll
be presented with a second prompt, depending on which type of 2FA you've enabled.
2019-09-30 21:07:59 +05:30
### Log in via 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
recovery code to log in.
2017-08-17 22:00:37 +05:30
### Log in via U2F device
2019-09-30 21:07:59 +05:30
To log in via 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**.
1. A light will start blinking on your device. Activate it by touching/pressing
its button.
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
You will see a message indicating that your device responded to the authentication
request and you will be automatically logged in.
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:
2017-08-17 22:00:37 +05:30
1. Log in to your GitLab account.
2020-04-08 14:13:33 +05:30
1. Go to your [**Profile settings**](../index.md#profile-settings).
2017-08-17 22:00:37 +05:30
1. Go to **Account**.
1. Click **Disable**, under **Two-Factor Authentication**.
This will clear all your two-factor authentication registrations, including mobile
applications and U2F devices.
## 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
2019-09-30 21:07:59 +05:30
[GitLab's API](../../../api/README.md). You must use a
[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).
2019-03-02 22:35:43 +05:30
- [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-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.
2017-09-10 17:25:29 +05:30
Once 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
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
2019-09-30 21:07:59 +05:30
ssh git@gitlab.example.com 2fa_recovery_codes
```
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
1. You will then be prompted to confirm that you want to generate new codes.
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.
After signing in, visit your **Profile settings > Account** immediately to set
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.
1. Go to your [**Profile settings**](../index.md#profile-settings).
1. Select **{account}** **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, click **Regenerate recovery codes**.
NOTE: **Note:**
If you regenerate 2FA recovery codes, save them. You won't be able to use any previously created 2FA codes.
2017-08-17 22:00:37 +05:30
### Ask a GitLab administrator to disable two-factor authentication on your account
If you cannot use a saved recovery code or generate new recovery codes, ask a
GitLab global administrator to disable two-factor authentication for your
account. This will temporarily leave your account in a less secure state.
Sign in and re-enable two-factor authentication as soon as possible.
## 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
the time of registration, and cannot be used for other hostnames/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
2019-07-07 11:18:12 +05:30
- The user logs in via `first.host.xyz` and registers their U2F key.
- The user logs out and attempts to log in via `first.host.xyz` - U2F authentication succeeds.
- The user logs out and attempts to log in via `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).
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.
Most authentication apps have a feature in the settings for syncing the time for the codes themselves. For Google Authenticator for example, go to `Settings > Time correction for codes`.
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. -->