Two-Factor Authentication (2FA) for GitLab and Mattermost

Getting Support

Before we dive into the topic of 2FA we would like to draw your attention to possible contacts to get support from in case you are not able to set up 2FA by yourself or if you have general questions about 2FA. Your first contact is of course the HIFIS-Support which can be reached by email; feel free to send your request or question to the HIFIS-HelpDesk via support@hifis.net. Your second contact might be your colleagues of your local IT-department who are familiar with the concept of 2FA and might be able to help you or answer your questions as well.

Brief Overview of 2FA

Two-Factor Authentication (2FA) (authentication is the technical term for logging in into an application) is a way to prove the identity of a user with two different, independent components, so-called factors. In 2FA, for example, these two factors could be “something the user knows” (knowledge factor) like a secret password and “something the user has” (possession factor) like a secret One-Time Password (OTP) from a Mobile App or a secret Security Token from a USB-dongle. 2FA is known to be much more secure than just your usual credentials (your pair of username and password) because an attacker needs to steal both the credentials and the respective second factor. There are two main approaches to create a second factor:

1. Mobile-Apps (like FreeOTP from Red Hat )
2. USB-Dongles (like YubiKey from Yubico )

Many web-applications support 2FA, but in most cases it needs to be activated explicitly by the user. This is particularly the case for GitLab and Mattermost . We strongly encourage the usage of 2FA wherever possible.

In the following section we describe the first approach and provide screenshots along the way. For more detailed explanations you can of cause always consult the GitLab user documentation .

2FA with Mobile Apps

First of all, you need to decide on which 2FA-mobile-app to install. In this example we use FreeOTP but you can use any other 2FA-mobile-app of your choice, such as:

• Authy
• Duo Mobile
• LastPass Authenticator
• Authenticator
• andOTP
• Google Authenticator
• Microsoft Authenticator
• SailOTP
• Synology Secure SignIn

FreeOTP supports two different implementations of One-Time Password (OTP) protocols which are HOTP - HMAC-based One-Time Password - and TOTP - Time-based One-Time Password.

On Android devices the FreeOTP user-interface looks much like the following:

We can see that in the upper right corner of the screen there are two buttons, one displaying a QR code and one that displays a key. You can click the button to scan a QR code, which sets all configurations automatically.

For both GitLab and Mattermost you need to enable 2FA from within your GitLab user account settings . To get a QR code to be scanned with your mobile-app you need to enable 2FA in GitLab by clicking the “Enable two-factor-authentication” button.

As a results a QR code similar to the following will be displayed:

Now with the QR code at hand you can scan it with your 2FA-mobile-app of your choice. As a result a new entry will show up in your app. You can tap on the entry and get your pin code which you need to enter into the pin code input field in GitLab. As soon as you click the button “Register with two-factor app” the registration is done and the 2FA is activated.

Finally, you will be provided with a set of recovery codes that you are asked to copy, download or print, securely store them somewhere and click the “Proceed” button.

From now on, every time you log in into GitLab or Mattermost with your credentials you will be asked to generate a pin code with your 2FA-mobile-app and enter it in the respective input field.