Spring Boot Two-Factor Authentication

A few days ago I wrote a story on JWT and social authentication using Spring Boot, check it out if you haven't yet.

This story is an extension to the above story, which, we will add a two-factor authentication.

Two-factor authentication is a way to increase the security of your product by adding an extra layer of security by asking the user to provide a second form of identification alongside username and password.

In this story we will use TOTP (Time-based One Time Password) as the second form of identification. This TOTP is generated by an app on user mobile device, like Google authenticator or Microsoft authenticator.

The below video shows what we are about to achieve.

How two-factor authentication (TOTP) works

When the user enable the two-factor authentication, a secret key is generated and sent to the user in a form of QR code, which the user will scan it using the authenticator app.

1. The login process now requires a several steps:
2. The user enters username and password.
3. The authentication service validates the username and password.
4. The user enters one-time password generated by the authenticator app.

The authentication service verifies the one-time password using the generated secret key and send JWT token to the user.

Let's dive deep into the implementation.

One-time password manager

We will use this library to generate the secret key and verify the one-time password.

TotpManager component is used as a wrapper for a the TOTP library. It has the following operations.

The first, generates the secret key, the 2nd, generates the Qr code image URI for the secret key, and lastly, verifyCode verifies if the provided code is correct or incorrect code.

The implementation of these methods is a direct use of the TOPT library, you can check its documentation from here.

The registration flow

Usually, the user can enable the two-factor authentication after registration from the user profile, but in our case we will allow the user to enable the two-factor authentication during the registration process.

We changed the User model to hold two new properties as follow

the first one is a flag indicates if two-factor authentication is enabled or not, and the 2nd, is a string to hold the secret key.

We also added the flag to the signup request.

And changed the signup response

Add the URI for the QR code image, and the flag, so that, the front can decide whether to display the QR code or not.

We did change the registerUser method in the UserService, to generate and store the secret key.

We also changed the createUser in the AuthEndpoint to return the QR code image URI in the response.

Finally, the changes in the front-end is pretty simple

If mfa (multi-factor or two-factor authentication) is enabled, redirect to QR code page, otherwise, redirect to login page.

The login flow

As we know the login process is divided into two steps, for that, we provided an additional endpoint to verify the one-time password, alongside username and password validation endpoint.

Let’s look into the implementation of each step.

The first step, validates the username and password but it doesn’t generate the JWT token if two-factor authentication is enabled.

The 2nd step, verifies the code (one-time password) and, if it is correct, it generates the JWT token.

Again, the front-end is doing a simple check if the two-factor authentication is enabled then redirect to the code verification, otherwise, redirect to the home page.

The verification page is direct call to the “verify” endpoint.

You can find the full source code from here.

Conclusion

Two-factor authentication increase the level of security by adding an extra layer of security, hence, increase the trust and make it harder for the attacker to access your data.

Two-factor authentication is based on three concepts:

1. Something you know (username and password).
2. Something you have (one-time password).
3. Something you are (this is a little more advanced and it includes fingerprint, facial recognition, or voice pattern).