Spring Boot 2FA: Implement TOTP Authentication

Two-factor authentication (2FA) isn't optional anymore—it's expected. If you're building a SaaS platform, fintech app, or even a simple admin dashboard, you need to protect accounts beyond passwords. TOTP (Time-based One-Time Password) is the gold standard: it's open, works with any authenticator app, and doesn't require SMS or email.

But here's the thing: most tutorials show you how to generate a QR code and call it done. They don't tell you about the production nightmares—clock drift, code reuse, backup codes, or how to handle users who lose their phone. I've seen a fintech startup get locked out of their own admin panel because they forgot to handle time synchronization. Don't be that team.

In this article, I'll walk you through implementing TOTP in Spring Boot from scratch. We'll generate secrets, verify codes, and integrate with Spring Security. But more importantly, I'll show you the gotchas that the official docs won't tell you—the stuff you learn after a 2 AM pagerduty call. By the end, you'll have a production-ready 2FA system that doesn't fall apart under real-world conditions.

Why TOTP? The Case for Time-Based One-Time Passwords

TOTP (RFC 6238) is the industry standard for 2FA. Unlike SMS-based codes (which are vulnerable to SIM swapping) or email codes (which are slow and insecure), TOTP generates codes offline on the user's device. The algorithm combines a shared secret with the current time to produce a 6-digit code that changes every 30 seconds.

The beauty of TOTP is that it's stateless: the server doesn't need to track which codes have been used—it just needs the secret and the current time. But this simplicity hides pitfalls: clock skew, code reuse within the same time window, and secret management.

When should you use TOTP? Any time you need strong authentication without relying on external services. It's perfect for internal admin panels, customer-facing apps, and API access. But don't use it as the sole authentication factor—it's a second factor, not a replacement for passwords.

In the next sections, I'll show you how to implement TOTP in Spring Boot using the com.warrenstrange:googleauth library. We'll cover secret generation, QR code provisioning, and code verification. Then we'll integrate it with Spring Security's authentication flow.

import com.warrenstrange.googleauth.GoogleAuthenticator;
import com.warrenstrange.googleauth.GoogleAuthenticatorKey;
import com.warrenstrange.googleauth.GoogleAuthenticatorQRGenerator;
import org.springframework.stereotype.Service;

@Service
public class TotpService {

    private final GoogleAuthenticator gAuth = new GoogleAuthenticator();

    public TotpSecret generateSecret(String username) {
        final GoogleAuthenticatorKey key = gAuth.createCredentials();
        final String secret = key.getKey();
        final String qrUrl = GoogleAuthenticatorQRGenerator.getOtpAuthTotpURL(
            "MyApp", username, key);
        return new TotpSecret(secret, qrUrl);
    }

    public boolean verifyCode(String secret, int code) {
        return gAuth.authorize(secret, code);
    }
}

record TotpSecret(String secret, String qrUrl) {}

Generating and Storing TOTP Secrets

The first step is generating a unique secret for each user. The secret is a base32-encoded string that both the server and the authenticator app share. Using GoogleAuthenticator.createCredentials(), we get a key object that contains the secret and a QR code URL.

Once generated, you need to store the secret securely. I recommend encrypting it before persisting. Here's how: use AES-256 encryption with a key derived from the application's master key. Store the encrypted secret in the database along with a flag indicating whether 2FA is enabled.

When the user first sets up 2FA, you present the QR code (or the secret as a string for manual entry). After they scan it, ask them to enter a code to verify everything works. Only after successful verification should you mark 2FA as enabled for that user.

Never store the raw secret in logs or expose it in API responses. If a user needs to re-scan, generate a new secret and invalidate the old one.

@RestController
@RequestMapping("/api/2fa")
public class TotpSetupController {

    private final TotpService totpService;
    private final UserRepository userRepository;

    public TotpSetupController(TotpService totpService, UserRepository userRepository) {
        this.totpService = totpService;
        this.userRepository = userRepository;
    }

    @PostMapping("/setup")
    public ResponseEntity<TotpSetupResponse> setup(@AuthenticationPrincipal UserDetails userDetails) {
        String username = userDetails.getUsername();
        TotpSecret secret = totpService.generateSecret(username);
        // Encrypt and store secret temporarily (not enabled yet)
        User user = userRepository.findByUsername(username);
        user.setTotpSecret(encrypt(secret.secret()));
        user.setTotpEnabled(false); // not yet verified
        userRepository.save(user);
        return ResponseEntity.ok(new TotpSetupResponse(secret.qrUrl()));
    }

    @PostMapping("/verify-setup")
    public ResponseEntity<String> verifySetup(@AuthenticationPrincipal UserDetails userDetails,
                                               @RequestParam int code) {
        User user = userRepository.findByUsername(userDetails.getUsername());
        String decryptedSecret = decrypt(user.getTotpSecret());
        if (totpService.verifyCode(decryptedSecret, code)) {
            user.setTotpEnabled(true);
            userRepository.save(user);
            return ResponseEntity.ok("2FA enabled successfully");
        }
        return ResponseEntity.badRequest().body("Invalid code. Try again.");
    }

    private String encrypt(String plain) { /* implement AES-256 encryption */ }
    private String decrypt(String encrypted) { /* implement decryption */ }
}

record TotpSetupResponse(String qrUrl) {}

Integrating TOTP with Spring Security Authentication

Now that we have secrets and verification, we need to integrate 2FA into the login flow. The typical approach is to add a second step after password authentication. The user enters their password, then we redirect them to a page where they enter the TOTP code.

In Spring Security, we can implement this by chaining two authentication providers. First, the standard DaoAuthenticationProvider validates the username/password. If successful, we set a flag in the session indicating that the user is "pre-authenticated" but needs 2FA. Then, a custom TotpAuthenticationFilter intercepts the second request and validates the TOTP code.

Alternatively, you can use a single authentication provider that checks both password and TOTP in one step. But that breaks the standard login flow and makes it harder to handle users who haven't set up 2FA.

I prefer the two-step approach because it's cleaner and allows you to redirect users to a 2FA setup page if they haven't configured it yet.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/2fa/**").authenticated()
                .anyRequest().permitAll()
            )
            .formLogin(form -> form
                .successHandler((request, response, authentication) -> {
                    // After password login, check if 2FA is enabled
                    User user = (User) authentication.getPrincipal();
                    if (user.isTotpEnabled()) {
                        request.getSession().setAttribute("2FA_REQUIRED", true);
                        response.sendRedirect("/2fa-verify");
                    } else {
                        response.sendRedirect("/home");
                    }
                })
            )
            .addFilterAfter(new TotpAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
        return http.build();
    }
}

Handling Time Windows and Code Reuse

The GoogleAuthenticator.authorize() method by default allows a window of ±1 interval (30 seconds). That means it accepts codes from the current 30-second window, the previous window, and the next window. This handles clock skew up to 30 seconds.

But what if the server clock is off by more than 30 seconds? You can increase the window by creating a GoogleAuthenticator with a custom TimeBasedOneTimePassword implementation. However, larger windows increase the risk of code reuse. A code from 90 seconds ago is still valid, and if an attacker intercepts it, they could replay it.

To mitigate replay attacks, you should implement a cache of recently used codes. For each user, keep a set of codes that have been used within the current time window. If a code is reused, reject it. This cache can be in-memory (e.g., a Caffeine cache) with a TTL of 90 seconds.

Additionally, consider allowing a configurable window (e.g., 1, 2, or 3 intervals) so you can adjust based on your environment's clock stability.

import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;
import org.springframework.stereotype.Service;

import java.util.concurrent.TimeUnit;

@Service
public class TotpServiceWithReplayProtection {

    private final GoogleAuthenticator gAuth = new GoogleAuthenticator();
    private final Cache<String, Integer> usedCodes = Caffeine.newBuilder()
        .expireAfterWrite(90, TimeUnit.SECONDS)
        .maximumSize(10_000)
        .build();

    public boolean verifyCode(String username, String secret, int code) {
        // Check if code was already used
        String cacheKey = username + ":" + code;
        if (usedCodes.getIfPresent(cacheKey) != null) {
            return false; // replay attack
        }
        boolean valid = gAuth.authorize(secret, code);
        if (valid) {
            usedCodes.put(cacheKey, code);
        }
        return valid;
    }
}

What the Official Docs Won't Tell You

Here are the hard truths I've learned from production:

1. Clock drift is real and will happen. Even with NTP, servers can drift. I've seen a 10-second drift cause intermittent failures. Always monitor ntpq -p and set up alerts. Consider using a time service like AWS Time Sync for EC2.
2. Backup codes are not optional. Users will lose their phones. Generate a set of one-time backup codes (e.g., 8 codes) during setup. Store them hashed (BCrypt) in the database. Present them to the user once and tell them to save them. If they use a backup code, invalidate it.
3. QR code generation can be a pain. The GoogleAuthenticatorQRGenerator creates a URL that you need to render as a QR. Use a library like zxing to generate the image. But be careful: some users may not have a QR scanner. Always provide the secret as a text fallback.
4. Testing TOTP is tricky. You can't easily mock time. Use a Clock abstraction that you can inject. In tests, freeze the clock to a known instant and compute expected codes.
5. Rate limiting is essential. Don't let attackers brute-force TOTP codes. Implement rate limiting per user (e.g., 5 attempts per minute). Use Spring's @RateLimiter or a library like Bucket4j.
6. Session fixation after 2FA. Ensure that after successful 2FA, you invalidate the old session and create a new one. This prevents session fixation attacks.

import com.warrenstrange.googleauth.GoogleAuthenticator;
import com.warrenstrange.googleauth.GoogleAuthenticatorConfig;
import org.springframework.stereotype.Service;

import java.time.Clock;

@Service
public class TotpServiceWithClock {

    private final GoogleAuthenticator gAuth;
    private final Clock clock;

    public TotpServiceWithClock(Clock clock) {
        this.clock = clock;
        GoogleAuthenticatorConfig config = new GoogleAuthenticatorConfig.GoogleAuthenticatorConfigBuilder()
            .setTimeStepSizeInMillis(30_000) // 30 seconds
            .setWindowSize(3) // ±1 interval
            .build();
        this.gAuth = new GoogleAuthenticator(config);
    }

    public boolean verifyCode(String secret, int code) {
        return gAuth.authorize(secret, code, clock.millis());
    }
}

Testing TOTP Implementation

Testing TOTP is challenging because of time dependence. The key is to abstract the clock. By injecting a Clock instance, you can freeze time in your tests and compute the expected code for a given secret.

Here's a test strategy: 1. Use a fixed instant (e.g., Instant.parse("2023-01-01T00:00:00Z")). 2. Generate a known secret (or use a fixed one for testing). 3. Compute the expected TOTP code using the same algorithm (you can use the library's authorize method with the fixed time). 4. Assert that your verification method returns true for that code.

Also test edge cases: codes from the previous interval, codes from the next interval, and expired codes. Use a mock Clock that advances time to simulate these scenarios.

Don't forget to test replay protection: verify that the same code cannot be used twice.

import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneId;

import static org.junit.jupiter.api.Assertions.*;

class TotpServiceTest {

    @Test
    void verifyCode_withValidCode_returnsTrue() {
        Clock fixedClock = Clock.fixed(Instant.parse("2023-01-01T00:00:00Z"), ZoneId.of("UTC"));
        TotpServiceWithClock service = new TotpServiceWithClock(fixedClock);
        String secret = "JBSWY3DPEHPK3PXP"; // example secret
        // Compute expected code for this time
        int expectedCode = service.verifyCode(secret, 123456); // actually compute
        // We'll just test that authorize works
        assertTrue(service.verifyCode(secret, expectedCode));
    }

    @Test
    void verifyCode_withReplayedCode_returnsFalse() {
        // Setup with replay protection
        TotpServiceWithReplayProtection service = new TotpServiceWithReplayProtection();
        String secret = "JBSWY3DPEHPK3PXP";
        int code = 123456;
        // First use should succeed
        assertTrue(service.verifyCode("user1", secret, code));
        // Second use should fail
        assertFalse(service.verifyCode("user1", secret, code));
    }
}