GitLab : enable 2-Factor Authentication (2FA)

Aug 20, 2021 by Thibault Debatty | 4928 views


GitLab is a very powerful tool, and it also implements decent security measures and protections. But still, by default all your work on GitLab is protected by a single password, which could be guessed or stolen. To add an additional layer of protection, you can (and should) configure 2-Factor Authentication (2FA).

How it works

When 2FA is enabled, your identity is verified twice when you login (with 2 factors):

  • using something you only should know: your password
  • and using something you only should own: usually your smartphone

To show you are the owner of the smartphone, you must use an app called a One-Time-Password generator (OTP). This app generates a PIN code that you must enter when you login. Unlike a classical password, this generated PIN code changes overtime. If the PIN code you type is correct, it means you are the owner of the smartphone (or at least that you are able to unlock the smartphone). If the password AND the PIN code you type are correct, your are properly authenticated.

When you create your account you must define your password, such that the GitLab server can verify your identity when you come back. In the same way, to use 2FA you must first link (synchronize) your smartphone with the GitLab server, such that the server can later check that you still own this smartphone. This is done by typing in the smartphone app a long token generated by the server, or using a QR code where the token is encoded.

This complete process is defined in 2 standards:

  • Time-based One-Time Password (TOTP) algorithm, standardized by IETF RFC 6238 and
  • HMAC-based One-Time Password (HOTP) algorithm, standardized by IETF RFC 4226.

This means that multiple apps exist that you can use to generate the PIN code (and enable 2FA): Google Authenticator, Authy, LastPass, Duo Mobile etc.

For this post we will use FreeOTP because:

  • it's open source and ad-free;
  • it's available for Android and iOS;
  • it's maintained by Red Hat, a trustworthy Linux contributor.

In practice

To enable 2FA for your account in GitLab:

  1. Install FreeOTP from Google Play or from the App Store;


  1. In GitLab, open the personal menu in the top-right corner, and click on "Edit profile";


  1. In the left menu, click on "Account";


  1. Click on "Enable two-factor authentication";


  1. Use FreeOTP to scan the QR code;


  1. A new tile will appear in FreeOTP. Tap on the tile to generate a first PIN code, enter the code in the interface of GitLab, and click on "Register with two-factor app".


Your are done! Each time you tap the tile it will generate a unique PIN code, that you must use to login into GitLab...

This blog post is licensed under CC BY-SA 4.0

This website uses cookies. More information about the use of cookies is available in the cookies policy.