User guide of module TOTP 2FA LOGIN (Two-Factor Authentication) for Dolibarr

Note: Version française de ce guide.

Nota: versión en español de esta guía.

What is this module for?

Once the module is installed and activated, a third text box will appear on the access or login page:

Considerations for populate this third box:

• Answering it is OPTIONAL: it will only be validated if the user you are trying to access with has activated the use of TOTP 2FA. For the other users, it will simply continue to validate only the username and password.
   
• A 6-digit TOTP code must be entered, one of those generated from apps such as Aegis (Android) or other multiplatform applications as Authy or Google Authenticator.
   
• This authentication system depends on both the server where Dolibarr is installed and the device where the user has the code generator app installed, having their internal clock synchronized with the time on the Internet. Normally this is not exact, and the code generated by the app is ahead or behind with respect to the server, so there is no need to despair if we do not enter the first time.
  
  In these cases, try to use the access code at the beginning of the 30-second period that the app gives you, or at the end. Normally it will work for you at one of the two extremes. If not, you should check which one does not have the correct time: your app or your Dolibarr server (normally the problem is with the app or the time of the phone where you have the app).

LOGIN RECEIVING THE CODE BY MAIL

This is possible since version 1.7 (Dec. 2022). It is aN alternative way to use the TOTp 6-digit codes, that each user who wants to use it must activate. Once activated, to enter you must:

1. enter the correct username and password, and leave the code box blank
2. by pressing the LOGIN button, the system will refresh the access form and if the credentials were correct then it will show a link to send the email
3. By clicking on this emailing link, the system sends the 6-digit temporary code to the user's email and confirms it on the screen
4. When receiving the email, you must write the code received within 30 seconds and press the LOGIN button again

Obviously, this mechanism is also useful to gain access when you do not have access to the TOTp generator. But it will also be the preferred mechanism for many of your users, who are still not used to using a TOTp code generator app. 😅

Activate a user's TOTP key

We will go to our user card (nobody can activate it for us) and there we will see an ACTIVATE button:

When pressed, the browser will request a 16-digit TOTP key and its corresponding QR code from the server. You must open your code generator app and look for the "add new account" option. If it's a mobile app it will usually give you the option to "scan a QR code", but if not, you can always copy the 16-digit key by hand:

In order for this key to be LINKED TO YOUR USER, you must use that code generator app to take your first TOTP code and validate it (see above). You can try as many times as necessary. If you couldn't get any codes to validate, then check your device's time settings (or maybe your server too, though it's rare for a server to be "out of time").

Once you acomplished to validate a code, the key is LINKED:

From this moment on, if you or someone tries to access with your username and password without entering a correct TOTP code, they will no longer be able to access Dolibarr:

You can define your own secret key

Especially useful for those of us who manage several Dolibarr instances is being able to use the same secret key in all those instances for 2FA. To do this, the module provides it in the following way (as of version 1.2): when we try to activate 2FA, it generates a random token and shows us its QR code, as we have seen above. At that moment we must press the button with the pencil, just above the QR code, beside the generator token:

And so we can manually edit the secret key:

By pressing the tiny button with the QR code (or by doing ENTER), the validation and activation process continues as in the case above:

Security considerations

Please note the following:

• Each user must activate their own 16-digit TOTP key. No one can do it for him, not even an admin user.
• Admin users can see which users have activated their TOTP key, but they cannot know the key itself. With this we avoid risks of identity theft when accessing Dolibarr.
• However, an administrator user can DISABLE the TOTP key of other users. This is done as a simple TOTP key deactivation mechanism in case a user loses his key and needs access to generate another one. Obviously all users can change their password whenever they want, as long as they have access to the system.

This is how it looks indicated in the List of users who have a 2FA key activated:

Although if some other user (even an administrator) access to a thrid user's card then they will see the semi-hidden password:

Deactivation of a user's TOTP key

On the other hand, when you go to visit your own user file, you can perfectly see your password and even scan the code with other apps:

To deactivate the active TOTP key you have to Modify your user card:

Note: in fact, if an administrator user accesses Modify another user's card, they will also see the same DEACTIVATE button.

FILTER VISITORS DEPENDING ON THEIR COUNTRY OF ORIGIN

This improvement was introduced with version 1.4 and aims to limit access to your Dolibarr from any IP that is not in the country that you define. And for this, in the configuration section you can define a WHITE LIST OF COUNTRIES.

Obviously, the visitor who is detected as coming from another country will not be told the country from which he has to access. Well, the idea is to make it difficult for unwanted intruders and bots. In other words, this measure alone is an interesting barrier for the vast majority of bots that are exploring wildly where to get into. Obviously, if someone attacks you, they will know what your country is and will use a VPN to try to break in.

If you leave that list of countries empty then the module will simply not look at the IP of those trying to access it.

Technical note: it is necessary to have the mod_geoip PHP module installed and activated on your server (for example installing php7.4-geoip package in the case of PHP 7.4). If you didn't have it installed, then the module will tell you this on tab "IP Configuration".

Remember a device as safe

Since version 1.5, the module allows you to define a period of time (1 day/week/month) during which your web browser will be remembered and you will not be asked for the 6-digit TOTP code again. You can also define that the TOTP code is ALWAYS requested. In fact, it is the default option.

Although it is a new feature that greatly improves the usability of TOTP codes, especially when you manage several instances of Dolibarr throughout the week, you must remember that the GREATER COMFORT we always have LESS SECURITY... unfortunately they are inversely proportional "always" . So, I recommend that you evaluate the security environment from which your users access when you decide to relax the use of TOTP.

What's more: as this system works THANKS TO COOKIES, it will stop working if you visit your Dolibarr from an incognito tab or if you delete the cookies in your browser after your visit. Which I recommend if you're not on your machine, for example. The module can remember for a user as many devices as he wants to use. So by momentarily signing in from an incognito tab on a new device, the module will not forget any of your other already used devices.

Sure, always limited to the expiration time you define in the module configuration:

So, how should I access Dolibarr now?

If you have defined a period of time to remember devices, then my recommendation is that you login in the following way:

In short: you just have to enter the username and password and press ENTER. And from time to time (when the remembering period expires) you will be asked for the 6-digit TOTP code. Comfortable, right?