Overview

Documentation

This is a rewritten version of the Google Authenticator Connector module from Roeland Salij. Some alterations have been made to make it work with Mendix 8>. The module requires an authenticator app to be installed on the users mobile phone (Google, Microsoft or another to your liking).

Demystifying 2-factor authentication

Before implementing the module, I’ll first briefly explain how 2-factor authentication (2fa) works. Keep in mind that the explanation is in a nutshell, so some statements could seem a bit shortsighted. However, the short explanation could be an eye opener to some (as it was to me).

The name 2-factor comes from the fact that the authentication consists of two parts: a secret key (an alphanumerical string) and the exact time (in Unix Epoch units).

The 6 digit code that changes every period of time – usually 30 seconds – is the result of a series of mathematical transformation, with the two factors as input parameters. Nothing more, nothing less.

1. Implementation

Below is explained how to import the 2fa module in your Mendix project. The process consists of 6 steps.  

1.1 Import module

The first step is to import the module package in your project. Right click in the project explorer, click import module package… and select the module.

1.2 Solve errors

Fix al the errors that occur after importing. Errors that most likely occur are:

• Page doesn’t exist – change the ‘show page’ action in the imported microflows to the page the homepage of the application.
• Attribute doesn’t exist – add the attribute LastLogin2FA to the Account entity

1.3 Connect application roles to module roles

The module contains two roles: Admin and User.

Connect the role that needs to generate the secret key to the Admin role

Connect all other roles to User.

1.4 Make generate QR functionality accessible for administrator

Connect a microflow somewhere from an Account dataview to the following Microflow: ACT_GoogleCredentials_RetrieveAndShowPage

Advised pages to create the button for the microflow are:

• Account edit
• Account new

1.5 Adjust Login logic to the one in the module

The module contains a microflow named Login_CheckLastLogin_RedirectToCorrectHome. You can use this microflow in two ways:

1. Use microflow directly as home for users – in Navigation, set this microflow as homepage
2. Inject microflow in existing login logic – use the microflow call action to place the above mentioned microflow in your existing logic

1.6 Set constants

The module contains two constants:

1. IssuerMFA – Set this to the name of the Mendix application (or whatever you want the issuer name to be in the authenticator app.
2. DaysBeforeExpiry – Standard is set to 7. Adjust constant to set time for re-entering 2fa (optional)

2 Usage

Some in-app actions also need to be performed by an administrator in order to make things work. Please note that MxAdmin does not use/need 2fa, so the first action should be carried out by the MxAdmin user.

2.1 Generate a Secret (and QR)

Without a generated secret, a user cannot login, for he then receives the message that no secret key has been set for him yet.

To enable users to login, the administrator has to start the action created in paragraph 1.4 to generate a secret (and QR) code for the specified user.

The user can then either scan the code with his phone (with an authenticator app on it) or enter the secret key in said app.

2.2 Login with code

After obtaining the secret key, the user can now login. First, he/she enters the normal credentials, after which the code that is continuously generated in the app must be inserted.

After successfully loging in, the user doesn’t have to use 2fa for another week (or longer/shorter if set with the DaysBeforeExpiry constant).

3 Troubleshooting

Some problems may occur when you use the module:

No QR is generated and when trying to login with 2fa you receive the error ‘class …  signer information does not match signer information of other classes in the same package’

The issue to this error is multiple .jar files in your Userlib folder use the same java class. To resolve this error, you must delete outdated .jar files from your folder.