How Do You Implement Multi-Factor Authentication (MFA) in Spring Security Without Getting Stuck in Redirect Loops, Broken Sessions, and “Invalid Code” Nightmares

package com.example.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(Customizer.withDefaults())
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/login", "/mfa/", "/css/", "/js/**").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(form -> form
                .loginPage("/login")
                .defaultSuccessUrl("/post-login", true) // decide where to go next
                .permitAll()
            )
            .logout(Customizer.withDefaults());

        return http.build();
    }

    @Bean
    public AuthenticationManager authenticationManager(AuthenticationConfiguration cfg) throws Exception {
        return cfg.getAuthenticationManager();
    }
}

package com.example.security.mfa;

import org.springframework.security.authentication.AbstractAuthenticationToken;
import org.springframework.security.core.GrantedAuthority;

import java.util.Collection;

public class MfaRequiredAuthenticationToken extends AbstractAuthenticationToken {

    private final String username;

    public MfaRequiredAuthenticationToken(String username, Collection<!--? extends GrantedAuthority--> authorities) {
        super(authorities);
        this.username = username;
        super.setAuthenticated(true); // password step succeeded
    }

    @Override
    public Object getCredentials() {
        return ""; // no credentials stored here
    }

    @Override
    public Object getPrincipal() {
        return username;
    }
}

package com.example.security.mfa;

import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;

import java.util.List;

@Component
public class PostPasswordAuthService {

    public void onPasswordSuccess(Authentication passwordAuth) {
        String username = passwordAuth.getName();

        // Imagine you checked user settings / risk rules here.
        boolean mfaRequired = true;

        if (mfaRequired) {
            // Replace the normal token with an MFA-required token.
            var partial = new MfaRequiredAuthenticationToken(username, List.of());
            SecurityContextHolder.getContext().setAuthentication(partial);
        } else {
            // Keep the fully authenticated password token.
            SecurityContextHolder.getContext().setAuthentication(passwordAuth);
        }
    }

    public boolean isMfaRequired(Authentication auth) {
        return auth instanceof MfaRequiredAuthenticationToken;
    }
}

package com.example.web;

import com.example.security.mfa.PostPasswordAuthService;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

import java.io.IOException;

@Controller
public class PostLoginController {

    private final PostPasswordAuthService postPasswordAuthService;

    public PostLoginController(PostPasswordAuthService postPasswordAuthService) {
        this.postPasswordAuthService = postPasswordAuthService;
    }

    @GetMapping("/post-login")
    public void postLogin(HttpServletResponse response) throws IOException {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();

        if (postPasswordAuthService.isMfaRequired(auth)) {
            response.sendRedirect("/mfa/challenge");
            return;
        }
        response.sendRedirect("/"); // normal home
    }
}

package com.example.security.totp;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.ByteBuffer;
import java.time.Instant;

public class TotpVerifier {

    private static final int TIME_STEP_SECONDS = 30;
    private static final int DIGITS = 6;

    public boolean verify(String base32Secret, String code, int allowedWindowSteps) {
        long now = Instant.now().getEpochSecond();
        long currentStep = now / TIME_STEP_SECONDS;

        for (int i = -allowedWindowSteps; i <= allowedWindowSteps; i++) {
            String candidate = generateTotp(base32Secret, currentStep + i);
            if (constantTimeEquals(candidate, code)) return true;
        }
        return false;
    }

    public String generateTotp(String base32Secret, long timeStep) {
        byte[] key = Base32.decode(base32Secret); // implement or use a small lib
        byte[] counter = ByteBuffer.allocate(8).putLong(timeStep).array();

        byte[] hmac = hmacSha1(key, counter);
        int offset = hmac[hmac.length - 1] & 0x0F;

        int binary =
            ((hmac[offset] & 0x7F) << 24) |
            ((hmac[offset + 1] & 0xFF) << 16) |
            ((hmac[offset + 2] & 0xFF) << 8) |
            (hmac[offset + 3] & 0xFF);

        int otp = binary % (int) Math.pow(10, DIGITS);
        return String.format("%0" + DIGITS + "d", otp);
    }

    private byte[] hmacSha1(byte[] key, byte[] data) {
        try {
            Mac mac = Mac.getInstance("HmacSHA1");
            mac.init(new SecretKeySpec(key, "HmacSHA1"));
            return mac.doFinal(data);
        } catch (Exception e) {
            throw new IllegalStateException("HMAC failure", e);
        }
    }

    private boolean constantTimeEquals(String a, String b) {
        if (a == null || b == null) return false;
        if (a.length() != b.length()) return false;
        int r = 0;
        for (int i = 0; i < a.length(); i++) r |= a.charAt(i) ^ b.charAt(i);
        return r == 0;
    }
}

package com.example.web;

import com.example.security.mfa.MfaRequiredAuthenticationToken;
import com.example.security.totp.TotpVerifier;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import java.io.IOException;
import java.util.List;

@Controller
@RequestMapping("/mfa")
public class MfaController {

    private final TotpVerifier totpVerifier;

    public MfaController(TotpVerifier totpVerifier) {
        this.totpVerifier = totpVerifier;
    }

    @GetMapping("/challenge")
    @ResponseBody
    public String challenge() {
        // In a real app, return a proper HTML/Thymeleaf page with CSRF token.
        return """
            
              <h2>Enter your 6-digit code</h2>
              <form method="post" action="/mfa/verify">
                <input name="code">
                <button type="submit">Verify</button>
              </form>
            
            """;
    }

    @PostMapping("/verify")
    public void verify(@RequestParam("code") String code,
                       HttpServletRequest request,
                       HttpServletResponse response) throws IOException {

        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (!(auth instanceof MfaRequiredAuthenticationToken)) {
            response.sendRedirect("/"); // already verified or not in MFA flow
            return;
        }

        String username = auth.getName();

        // Load user's stored secret from DB; hard-coded here for demo.
        String base32Secret = "JBSWY3DPEHPK3PXP"; // example only

        boolean ok = totpVerifier.verify(base32Secret, code, 1);
        if (!ok) {
            response.sendRedirect("/mfa/challenge?error=invalid_code");
            return;
        }

        // Upgrade to fully authenticated token (attach roles/authorities here)
        var full = new UsernamePasswordAuthenticationToken(username, "", List.of());
        SecurityContextHolder.getContext().setAuthentication(full);

        response.sendRedirect("/");
    }
}

Read more at : How Do You Implement Multi-Factor Authentication (MFA) in Spring Security Without Getting Stuck in Redirect Loops, Broken Sessions, and “Invalid Code” Nightmares