BigW Consortium Gitlab

two_factor_authentication.md 4.54 KB
Newer Older
Robert Speicher committed
1 2 3 4 5 6 7 8 9 10
# Two-factor Authentication (2FA)

Two-factor Authentication (2FA) provides an additional level of security to your
GitLab account. Once enabled, in addition to supplying your username and
password to login, you'll be prompted for a code generated by an application on
your phone.

By enabling 2FA, the only way someone other than you can log into your account
is to know your username and password *and* have access to your phone.

11
> **Note:**
12 13 14
When you enable 2FA, don't forget to back up your recovery codes. For your safety, if you
lose your codes for GitLab.com, we can't disable or recover them.  

15 16 17 18 19 20 21 22 23 24 25 26 27
In addition to a phone application, GitLab supports U2F (universal 2nd factor) devices as
the second factor of authentication. Once enabled, in addition to supplying your username and
password to login, you'll be prompted to activate your U2F device (usually by pressing
a button on it), and it will perform secure authentication on your behalf.

> **Note:** Support for U2F devices was added in version 8.8

The U2F workflow is only supported by Google Chrome at this point, so we _strongly_ recommend 
that you set up both methods of two-factor authentication, so you can still access your account 
from other browsers.

> **Note:** GitLab officially only supports [Yubikey] U2F devices.

Robert Speicher committed
28 29
## Enabling 2FA

30 31
### Enable 2FA via mobile application

Robert Speicher committed
32 33 34 35
**In GitLab:**

1. Log in to your GitLab account.
1. Go to your **Profile Settings**.
36
1. Go to **Account**.
Robert Speicher committed
37 38
1. Click **Enable Two-factor Authentication**.

39
![Two-factor setup](2fa.png)
Robert Speicher committed
40 41 42

**On your phone:**

43
1. Install a compatible application. We recommend [Google Authenticator]
rugk committed
44
\(proprietary\) or [FreeOTP] \(open source\).
Robert Speicher committed
45 46 47 48 49 50 51 52 53 54 55
1. In the application, add a new entry in one of two ways:
    * Scan the code with your phone's camera to add the entry automatically.
    * Enter the details provided to add the entry manually.

**In GitLab:**

1. Enter the six-digit pin number from the entry on your phone into the **Pin
   code** field.
1. Click **Submit**.

If the pin you entered was correct, you'll see a message indicating that
56
Two-Factor Authentication has been enabled, and you'll be presented with a list
Robert Speicher committed
57 58
of recovery codes.

59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
### Enable 2FA via U2F device

**In GitLab:**

1. Log in to your GitLab account.
1. Go to your **Profile Settings**.
1. Go to **Account**.
1. Click **Enable Two-Factor Authentication**.
1. Plug in your U2F device.
1. Click on **Setup New U2F Device**.
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.

![Two-Factor U2F Setup](2fa_u2f_register.png)

Robert Speicher committed
76 77 78 79 80 81 82 83
## Recovery Codes

Should you ever lose access to your phone, you can use one of the ten provided
backup codes to login to your account. We suggest copying or printing them for
storage in a safe place. **Each code can be used only once** to log in to your
account.

If you lose the recovery codes or just want to generate new ones, you can do so
84
from the **Profile Settings** > **Account** page where you first enabled 2FA.
Robert Speicher committed
85

86 87
> **Note:** Recovery codes are not generated for U2F devices.

Robert Speicher committed
88 89 90 91
## 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
92 93 94 95 96
be presented with a second prompt, depending on which type of 2FA you've enabled.

### Log in via mobile application

Enter the pin from your phone's application or a recovery code to log in.
Robert Speicher committed
97

98 99 100 101 102 103 104 105 106 107 108
![Two-Factor Authentication on sign in via OTP](2fa_auth.png)

### Log in via U2F device

1. Click **Login via U2F Device**
1. A light will start blinking on your device. Activate it by pressing its button.

You will see a message indicating that your device responded to the authentication request.
Click on **Authenticate via U2F Device** to complete the process.

![Two-Factor Authentication on sign in via U2F device](2fa_u2f_authenticate.png)
Robert Speicher committed
109 110 111 112 113

## Disabling 2FA

1. Log in to your GitLab account.
1. Go to your **Profile Settings**.
114
1. Go to **Account**.
115 116 117 118
1. Click **Disable**, under **Two-Factor Authentication**.

This will clear all your two-factor authentication registrations, including mobile
applications and U2F devices.
Robert Speicher committed
119

120 121 122 123 124
## Note to GitLab administrators

You need to take special care to that 2FA keeps working after
[restoring a GitLab backup](../raketasks/backup_restore.md).

Robert Speicher committed
125
[Google Authenticator]: https://support.google.com/accounts/answer/1066447?hl=en
126
[FreeOTP]: https://fedorahosted.org/freeotp/
127
[YubiKey]: https://www.yubico.com/products/yubikey-hardware/