Multi-Factor Authentication Integration

Introduction

Welcome to the third lesson of the "Multi-Factor Authentication (MFA) in Spring Boot" course! In this lesson, we will focus on integrating MFA into a Spring Boot application. Building on the foundational concepts from the previous lesson, we will explore the practical steps necessary to enhance the security of your application by implementing MFA. Let's dive in and see how we can secure our application with MFA! 🚀

Secure MFA Integration Patterns

Now that you're familiar with the core MFA functions like generateSecret, verifyToken, verifyCode, and generateBackupCodes, let's focus on integrating these functions securely into your Spring Boot application. Proper integration is crucial - even with well-implemented MFA functions, vulnerabilities can arise from insecure application design. We'll examine how to store MFA data securely, protect sensitive endpoints, and create a robust authentication flow. Security Reminder: Always encrypt MFA secrets at rest to prevent attackers from accessing them if your database is compromised. Always hash backup codes before storing them, just like passwords, so they cannot be used if leaked. Implement rate-limiting on all sensitive endpoints (such as /verify, /login, and /login/verify) to protect against brute-force attacks.

The Vulnerable Code

Let's examine a scenario where MFA is not properly integrated, leading to potential security vulnerabilities: Java // Example of a vulnerable MFA setup @PostMapping("/verify") public ResponseEntity<?> verify(@RequestBody Map<String, String> request) {String username = request.get("username"); String token = request.get("token"); User user = userRepository.findByUsername(username).orElse(null); boolean isValid = MFABasics.verifyToken(token, user.getMfaSecret()); if (isValid) {user.setMfaEnabled(true); userRepository.save(user); return ResponseEntity.ok(Map.of("success", true));} else {return ResponseEntity.ok(Map.of("success", false, "error", "Invalid token"));}} This code contains several critical vulnerabilities: No authentication checks - anyone can access this endpoint No validation that the user exists before accessing properties (potential NullPointerException) No protection against brute force attacks The endpoint updates user settings without proper authorization

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Security Utility Methods Implementation

Before we implement the MFA routes, let's create the necessary utility methods for encryption, hashing, and token management. These methods are essential for secure MFA integration:

Java

@Component
public class MFASecurityUtils {
    
    @Value("${mfa.encryption.key}") // Store in application.properties, never in code
    private String encryptionKey;
    
    @Value("${jwt.secret}") // Your JWT secret
    private String jwtSecret;
    
    private final BCryptPasswordEncoder passwordEncoder = new BCryptPasswordEncoder();
    private final ObjectMapper objectMapper = new ObjectMapper();
    
    // Encrypt MFA secret before storing
    public String encryptSecret(String secret) {
        try {
            SecretKeySpec keySpec = new SecretKeySpec(encryptionKey.getBytes(), "AES");
            Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
            cipher.init(Cipher.ENCRYPT_MODE, keySpec);
            byte[] encrypted = cipher.doFinal(secret.getBytes());
            return Base64.getEncoder().encodeToString(encrypted);
        } catch (Exception e) {
            throw new RuntimeException("Encryption failed", e);
        }
    }
    
    // Decrypt MFA secret when needed
    public String decryptSecret(String encryptedSecret) {
        try {
            SecretKeySpec keySpec = new SecretKeySpec(encryptionKey.getBytes(), "AES");
            Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
            cipher.init(Cipher.DECRYPT_MODE, keySpec);
            byte[] decrypted = cipher.doFinal(Base64.getDecoder().decode(encryptedSecret));
            return new String(decrypted);
        } catch (Exception e) {
            throw new RuntimeException("Decryption failed", e);
        }
    }
    
    // Hash backup codes before storing
    public String hashBackupCodes(List<String> backupCodes) {
        try {
            List<String> hashed = backupCodes.stream()
                .map(passwordEncoder::encode)
                .collect(Collectors.toList());
            return objectMapper.writeValueAsString(hashed);
        } catch (Exception e) {
            throw new RuntimeException("Failed to hash backup codes", e);
        }
    }
    
    // Parse stored backup codes
    public Set<String> parseBackupCodes(String backupCodesJson) {
        try {
            if (backupCodesJson == null || backupCodesJson.isEmpty()) {
                return new HashSet<>();
            }
            List<String> codes = objectMapper.readValue(backupCodesJson, 
                new TypeReference<List<String>>() {});
            return new HashSet<>(codes);
        } catch (Exception e) {
            throw new RuntimeException("Failed to parse backup codes", e);
        }
    }
    
    // Serialize backup codes to JSON
    public String serializeBackupCodes(Set<String> backupCodes) {
        try {
            return objectMapper.writeValueAsString(backupCodes);
        } catch (Exception e) {
            throw new RuntimeException("Failed to serialize backup codes", e);
        }
    }
    
    // Generate temporary token for two-step MFA login (expires in 5 minutes)
    public String generateTempToken(Integer userId) {
        return Jwts.builder()
            .setSubject(userId.toString())
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 300000)) // 5 minutes
            .signWith(SignatureAlgorithm.HS256, jwtSecret)
            .compact();
    }
    
    // Verify temporary token and return user ID
    public Integer verifyTempToken(String token) {
        try {
            Claims claims = Jwts.parser()
                .setSigningKey(jwtSecret)
                .parseClaimsJws(token)
                .getBody();
            return Integer.parseInt(claims.getSubject());
        } catch (Exception e) {
            return null; // Invalid or expired token
        }
    }
    
    // Generate session token after successful authentication
    public String generateSessionToken(User user) {
        return Jwts.builder()
            .setSubject(user.getUsername())
            .claim("userId", user.getId())
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 86400000)) // 24 hours
            .signWith(SignatureAlgorithm.HS256, jwtSecret)
            .compact();
    }
    
    // Extract username from authorization header
    public String getUsernameFromToken(String authHeader) {
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            return null;
        }
        try {
            String token = authHeader.substring(7);
            Claims claims = Jwts.parser()
                .setSigningKey(jwtSecret)
                .parseClaimsJws(token)
                .getBody();
            return claims.getSubject();
        } catch (Exception e) {
            return null;
        }
    }
    
    // Verify password (assuming passwords are hashed with BCrypt)
    public boolean verifyPassword(String rawPassword, String encodedPassword) {
        return passwordEncoder.matches(rawPassword, encodedPassword);
    }
}

Required Dependencies:

Add these to your pom.xml:

XML

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt</artifactId>
    <version>0.9.1</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Configuration:

Add to your application.properties:

INI

# Use a strong, randomly generated key (at least 32 characters)
mfa.encryption.key=your-32-character-encryption-key-here
jwt.secret=your-jwt-secret-key-here

Security Notes:

Never hardcode encryption keys or secrets in your code
Use environment variables or a secrets management system in production
The encryption example uses AES with ECB mode for simplicity; consider using GCM mode for better security
Regularly rotate your encryption keys and secrets
Consider using Spring Security Crypto for more advanced encryption needs

Now that we have these utility methods, let's see how to use them in our MFA integration.

Implementing MFA Setup

Let's create a secure route for setting up MFA, using the utility methods we just created. First, inject the MFASecurityUtils component into your controller:

Java

@RestController
@RequestMapping("/api/mfa")
public class MFAController {
    
    @Autowired
    private MFASecurityUtils securityUtils;
    
    @Autowired
    private UserRepository userRepository;
    
    // Route to set up MFA (requires authentication)
    // Add rate-limiting in production
    @PostMapping("/setup")
    public ResponseEntity<?> setup(
            @RequestHeader(value = "Authorization", required = false) String authHeader,
            @RequestBody Map<String, String> request) {
        
        // Extract and verify user from token
        String username = securityUtils.getUsernameFromToken(authHeader);
        if (username == null) {
            return error(HttpStatus.UNAUTHORIZED, "Unauthorized");
        }
        
        User user = userRepository.findByUsername(username).orElse(null);
        if (user == null) {
            return error(HttpStatus.NOT_FOUND, "User not found");
        }
        
        try {
            // Generate MFA secret using our utility
            Map<String, String> secretData = MFABasics.generateSecret(user.getUsername());
            String secret = secretData.get("secret");
            String otpauth = secretData.get("otpauth");
            
            // Encrypt the secret before storing
            String encryptedSecret = securityUtils.encryptSecret(secret);
            
            // Generate backup codes and hash them before storing
            List<String> backupCodes = MFABasics.generateBackupCodes(10);
            String hashedCodes = securityUtils.hashBackupCodes(backupCodes);
            
            // Set both mfaSecret and backupCodes before saving
            user.setMfaSecret(encryptedSecret);
            user.setMfaEnabled(false); // Will be enabled after verification
            user.setBackupCodes(hashedCodes);
            userRepository.save(user);
            
            // Generate QR code
            String qrCodeUrl = MFABasics.generateQRCodeDataURL(otpauth);
            
            Map<String, Object> response = new HashMap<>();
            response.put("success", true);
            response.put("qrCodeUrl", qrCodeUrl);
            response.put("backupCodes", backupCodes); // Return plain codes to user only at creation
            response.put("message", "Scan the QR code with your authenticator app, then verify with a token");
            
            return ResponseEntity.ok(response);
        } catch (Exception e) {
            return error(HttpStatus.INTERNAL_SERVER_ERROR, "Failed to set up MFA");
        }
    }
    
    // Helper method for error responses
    private ResponseEntity<?> error(HttpStatus status, String message) {
        return ResponseEntity.status(status).body(Map.of("success", false, "error", message));
    }
}

This secure implementation includes:

Authentication checks to ensure only logged-in users can access it
Error handling for failed operations
Proper user verification
Temporary storage of the secret until verified
Encryption of secrets and hashing of backup codes using our utility methods
(In production) Add rate-limiting

Verifying MFA Tokens Securely

Next, we'll create a secure route to verify the MFA token provided by the user:

Java

// Add rate-limiting in production
@PostMapping("/verify")
public ResponseEntity<?> verify(
        @RequestHeader(value = "Authorization", required = false) String authHeader,
        @RequestBody Map<String, String> request) {
    
    String token = request.get("token");
    if (token == null || token.isEmpty()) {
        return error(HttpStatus.BAD_REQUEST, "Token is required");
    }
    
    // Extract and verify user from token
    String username = securityUtils.getUsernameFromToken(authHeader);
    if (username == null) {
        return error(HttpStatus.UNAUTHORIZED, "Unauthorized");
    }
    
    User user = userRepository.findByUsername(username).orElse(null);
    if (user == null || user.getMfaSecret() == null) {
        return error(HttpStatus.BAD_REQUEST, "MFA not set up");
    }
    
    try {
        // Decrypt the secret before verification
        String decryptedSecret = securityUtils.decryptSecret(user.getMfaSecret());
        
        // Verify the token
        boolean isValid = MFABasics.verifyToken(token, decryptedSecret);
        
        if (isValid) {
            // Only now do we enable MFA for the user
            user.setMfaEnabled(true);
            userRepository.save(user);
            
            // Generate a new session token or refresh existing session
            String sessionToken = securityUtils.generateSessionToken(user);
            
            return ResponseEntity.ok(Map.of(
                "success", true,
                "message", "MFA enabled successfully",
                "sessionToken", sessionToken
            ));
        } else {
            return error(HttpStatus.UNAUTHORIZED, "Invalid token");
        }
    } catch (Exception e) {
        return error(HttpStatus.INTERNAL_SERVER_ERROR, "Failed to verify token");
    }
}

This implementation includes:

Input validation for the token
Authentication checks
Verification that MFA is set up
Proper error handling
Session regeneration after successful verification
Decryption of secrets before use using our utility methods
(In production) Add rate-limiting

Implementing Login with MFA

When MFA is enabled, the login process becomes a two-step procedure. In this flow, a temporary token (often called a tempToken) is issued after the user successfully enters their username and password, but before they complete MFA verification.

A tempToken is a short-lived, signed token (such as a JWT) that securely encodes the user's identity and the fact that they have passed the first authentication step. It is used to track the login session between the password and MFA steps, ensuring that only the correct user can proceed to MFA verification. In our implementation, the tempToken expires in 5 minutes.

Java

// Add rate-limiting in production
@PostMapping("/login")
public ResponseEntity<?> login(@RequestBody Map<String, String> request) {
    String username = request.get("username");
    String password = request.get("password");
    
    User user = userRepository.findByUsername(username).orElse(null);
    
    // Verify username and password
    if (user == null || !securityUtils.verifyPassword(password, user.getPassword())) {
        return error(HttpStatus.UNAUTHORIZED, "Invalid credentials");
    }
    
    // Check if MFA is enabled
    if (user.isMfaEnabled()) {
        // Generate a temporary login token that will be used to complete login
        String tempToken = securityUtils.generateTempToken(user.getId());
        
        return ResponseEntity.ok(Map.of(
            "success", true,
            "requireMFA", true,
            "tempToken", tempToken,
            "message", "Please enter your MFA code to complete login"
        ));
    } else {
        // Regular login without MFA
        String sessionToken = securityUtils.generateSessionToken(user);
        return ResponseEntity.ok(Map.of(
            "success", true,
            "sessionToken", sessionToken
        ));
    }
}

// Second step for MFA verification
// Add rate-limiting in production
@PostMapping("/login/verify")
public ResponseEntity<?> verifyLogin(@RequestBody Map<String, String> request) {
    String tempToken = request.get("tempToken");
    String mfaCode = request.get("mfaCode");
    
    // Verify the temporary token
    Integer userId = securityUtils.verifyTempToken(tempToken);
    if (userId == null) {
        return error(HttpStatus.UNAUTHORIZED, "Invalid session");
    }
    
    User user = userRepository.findById(userId).orElse(null);
    if (user == null || user.getMfaSecret() == null) {
        return error(HttpStatus.BAD_REQUEST, "User not found");
    }
    
    try {
        // Decrypt the secret before verification
        String decryptedSecret = securityUtils.decryptSecret(user.getMfaSecret());
        
        // Convert stored hashed backup codes to Set
        Set<String> hashedBackupCodes = securityUtils.parseBackupCodes(user.getBackupCodes());
        
        // Verify using both token and backup codes (compare mfaCode to hashed codes)
        boolean isValid = MFABasics.verifyCode(mfaCode, decryptedSecret, hashedBackupCodes);
        
        if (isValid) {
            // If a backup code was used, update the stored codes
            if (user.getBackupCodes() != null) {
                user.setBackupCodes(securityUtils.serializeBackupCodes(hashedBackupCodes));
                userRepository.save(user);
            }
            
            // Complete login
            String sessionToken = securityUtils.generateSessionToken(user);
            return ResponseEntity.ok(Map.of(
                "success", true,
                "sessionToken", sessionToken
            ));
        } else {
            return error(HttpStatus.UNAUTHORIZED, "Invalid MFA code");
        }
    } catch (Exception e) {
        return error(HttpStatus.INTERNAL_SERVER_ERROR, "Verification failed");
    }
}

This two-step process ensures:

Users with MFA enabled must provide a valid MFA code
Temporary tokens control the flow between login steps
Both TOTP and backup codes are supported
Used backup codes are invalidated
Secrets are decrypted before use, and backup codes are always hashed using our utility methods
(In production) Add rate-limiting

Introduction

Secure MFA Integration Patterns

The Vulnerable Code

Join the 1M+ learners on CodeSignal

Secure User Model Modifications

Security Utility Methods Implementation

Implementing MFA Setup

Verifying MFA Tokens Securely

Implementing Login with MFA

Conclusion and Next Steps