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.
Note: When you enable 2FA, don't forget to back up your recovery codes.
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.
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.
There are two ways to enable two-factor authentication: via a mobile application or a U2F device.
On your phone:
In the application, add a new entry in one of two ways:
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 of recovery codes.
You will see a message indicating that your device was successfully set up. Click on Register U2F Device to complete the process.
Note: Recovery codes are not generated for U2F devices.
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 from the Profile settings ➔ Account page where you first enabled 2FA.
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.
Enter the pin from your phone's application or a recovery code to log in.
You will see a message indicating that your device responded to the authentication request. Click on Authenticate via U2F Device to complete the process.
This will clear all your two-factor authentication registrations, including mobile applications and U2F devices.
When 2FA is enabled, you can no longer use your normal account password to authenticate with Git over HTTPS on the command line, you must use a personal access token instead.
When using Git over HTTPS on the command line, enter the personal access token into the password field.
To disable two-factor authentication on your account (for example, if you have lost your code generation device) you can:
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.
Note: Once you use a recovery code, you cannot re-use it. You can still use the other recovery codes you saved.
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.
ssh [email protected] 2fa_recovery_codes.
You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes. ``` bash $ ssh 2fa_recovery_codes Are you sure you want to generate new two-factor recovery codes? Any existing recovery codes you saved will be invalidated. (yes/no)
Your two-factor authentication recovery codes are:
119135e5a3ebce8e 11f6v2a498810dcd 3924c7ab2089c902 e79a3398bfe4f224 34bd7b74adbc8861 f061691d5107df1a 169bf32a18e63e7f b510e7422e81c947 20dbed24c5e74663 df9d3b9403b9c9f0During 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. ```
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.
Note: After signing in, visit your Profile Settings -> Account immediately to set up two-factor authentication with a new device.
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.
You need to take special care to that 2FA keeps working after restoring a GitLab backup.
To ensure 2FA authorizes correctly with 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.