It’s almost always a good idea to support two-factor authentication (2FA), especially for back-office systems. 2FA comes in many different forms, some of which include SMS, TOTP, or even hardware tokens.
Enabling them requires a similar flow:
- The user goes to their profile page (skip this if you want to force 2fa upon registration)
- Clicks “Enable two-factor authentication”
- Enters some data to enable the particular 2FA method (phone number, TOTP verification code, etc.)
- Next time they login, in addition to the username and password, the login form requests the 2nd factor (verification code) and sends that along with the credentials
I will focus on Google Authenticator, which uses a TOTP (Time-based one-time password) for generating a sequence of verification codes. The ideas is that the server and the client application share a secret key. Based on that key and on the current time, both come up with the same code. Of course, clocks are not perfectly synced, so there’s a window of a few codes that the server accepts as valid. Note that if you don’t trust Google’s app, you can implement your own client app using the same library below (though you can see the source code to make sure no shenanigans happen).
How to implement that with Java (on the server)? Using the GoogleAuth library. The flow is as follows:
- The user goes to their profile page
- Clicks “Enable two-factor authentication”
- The server generates a secret key, stores it as part of the user profile and returns a URL to a QR code
- The user scans the QR code with their Google Authenticator app thus creating a new profile in the app
- The user enters the verification code shown the app in a field that has appeared together with the QR code and clicks “confirm”
- The server marks the 2FA as enabled in the user profile
- Optionally, you can give the user some “scratch codes”, which they can write down in case they lose their app or secret.
- If the user doesn’t scan the code or doesn’t verify the process, the user profile will contain just a orphaned secret key, but won’t be marked as enabled
- There should be an option to later disable the 2FA from their user profile page
The most important bit from theoretical point of view here is the sharing of the secret key. The crypto is symmetric, so both sides (the authenticator app and the server) have the same key. It is shared via a QR code that the user scans. If an attacker has control on the user’s machine at that point, the secret can be leaked and thus the 2FA – abused by the attacker as well. But that’s not in the threat model – in other words, if the attacker has access to the user’s machine, the damage is already done anyway.
Note: you may see this process called either 2-step authentication or 2-factor. The “factors” are: “something you know”, “something you have” and “something you are”. You can view the TOTP as just another thing “you know”, but you can also view the phone with the securely stored secret key as something “you have”. I don’t insist on either terminology in this particular case.
Upon login, the flow is as follows:
- The user enters username and password and clicks “Login”
- Using an AJAX request the page asks the server whether this email has 2FA enabled
- If 2FA is not enabled, just submit the username & password form
- If 2FA is enabled, the login form is not submitted, but instead an additional field is shown to let the user input the verification code from the authenticator app
- After the user enters the code and presses login, the form can be submitted. Either using the same login button, or a new “verify” button, or the verification input + button could be an entirely new screen (hiding the username/password inputs).
- The server then checks again if the user has 2FA enabled and if yes, verifies the verification code. If it matches, login is successful. If not, login fails and the user is allowed to reenter the credentials and the verification code. Note here that you can have different responses depending on whether username/password are wrong or in case the code is wrong. You can also attempt to login prior to even showing the verification code input. That way is arguably better, because that way you don’t reveal to a potential attacker that the user uses 2FA.
While I’m speaking of username and password, that can apply to any other authentication method. After you get a success confirmation from an OAuth / OpenID Connect / SAML provider, or after you can a token from SecureLogin, you can request the second factor (code).
In code, the above processes look as follows (using Spring MVC; I’ve merged the controller and service layer for brevity. You can replace the @AuthenticatedPrincipal bit with your way of supplying the currently logged in user details to the controllers). Assuming the methods are in controller mapped to “/user/”:
@RequestMapping(value = "/init2fa", method = RequestMethod.POST)
@ResponseBody
public String initTwoFactorAuth(@AuthenticationPrincipal LoginAuthenticationToken token) {
User user = getLoggedInUser(token);
GoogleAuthenticatorKey googleAuthenticatorKey = googleAuthenticator.createCredentials();
user.setTwoFactorAuthKey(googleAuthenticatorKey.getKey());
dao.update(user);
return GoogleAuthenticatorQRGenerator.getOtpAuthURL(GOOGLE_AUTH_ISSUER, email, googleAuthenticatorKey);
}
@RequestMapping(value = "/confirm2fa", method = RequestMethod.POST)
@ResponseBody
public boolean confirmTwoFactorAuth(@AuthenticationPrincipal LoginAuthenticationToken token, @RequestParam("code") int code) {
User user = getLoggedInUser(token);
boolean result = googleAuthenticator.authorize(user.getTwoFactorAuthKey(), code);
user.setTwoFactorAuthEnabled(result);
dao.update(user);
return result;
}
@RequestMapping(value = "/disable2fa", method = RequestMethod.GET)
@ResponseBody
public void disableTwoFactorAuth(@AuthenticationPrincipal LoginAuthenticationToken token) {
User user = getLoggedInUser(token);
user.setTwoFactorAuthKey(null);
user.setTwoFactorAuthEnabled(false);
dao.update(user);
}
@RequestMapping(value = "/requires2fa", method = RequestMethod.POST)
@ResponseBody
public boolean login(@RequestParam("email") String email) {
// TODO consider verifying the password here in order not to reveal that a given user uses 2FA
return userService.getUserDetailsByEmail(email).isTwoFactorAuthEnabled();
}
The QR code generation uses a Google’s service, which technically gives Google the secret key as well. I doubt they store it in addition to generating the QR code, but if you don’t trust them, you can implement your own QR code generator, it should not be hard to generate a QR code yourself.
On the client side it’s simple AJAX requests to the above methods (sidenote: I kind of feel the term AJAX is no longer trendy, but I don’t know how to call them. Async? Background? Javascript?).
$("#two-fa-init").click(function() {
$.post("/user/init2fa", function(qrImage) {
$("#two-fa-verification").show();
$("#two-fa-qr").prepend($('<img>',{id:'qr',src:qrImage}));
$("#two-fa-init").hide();
});
});
$("#two-fa-confirm").click(function() {
var verificationCode = $("#verificationCode").val().replace(/ /g,'')
$.post("/user/confirm2fa?code=" + verificationCode, function() {
$("#two-fa-verification").hide();
$("#two-fa-qr").hide();
$.notify("Successfully enabled two-factor authentication", "success");
$("#two-fa-message").html("Successfully enabled");
});
});
$("#two-fa-disable").click(function() {
$.post("/user/disable2fa", function(qrImage) {
window.location.reload();
});
});
The login form code depends very much on the existing login form you are using, but the point is to call the /requires2fa with the email (and password) to check if 2FA is enabled and then show a verification code input.
Overall, the implementation if two-factor authentication is simple and I’d recommend it for most systems, where security is more important than simplicity of the user experience.
