Keycloak MFA: Add TOTP Two-Factor Authentication (2026)

Keycloak’s Multi-Factor Authentication (MFA) is more than just an extra login step; it’s a layered security strategy where the second factor proves possession of a device, not just knowledge of a password.

Let’s see TOTP (Time-based One-Time Password) in action. Imagine a user, Alice, logging into a protected application.

sequenceDiagram
    participant Alice
    participant Keycloak
    participant Application

    Alice->>Keycloak: Username and Password
    Keycloak-->>Alice: Request Second Factor (TOTP)
    Alice->>Alice: Opens Authenticator App (e.g., Google Authenticator)
    Alice->>Keycloak: TOTP Code from App
    Keycloak-->>Application: Validates TOTP, Grants Access Token
    Application-->>Alice: Access Granted

Here’s what’s happening under the hood when Alice initiates the TOTP setup.

First, Alice navigates to her profile in Keycloak and selects "Authenticator". She clicks "Add TOTP". Keycloak then generates a unique secret key for her account. This secret is encoded into a QR code, which Alice’s authenticator app will scan.

The QR code contains a URI that looks something like this:

otpauth://totp/Keycloak:alice?secret=JBSWY3DPEHPK3PXP&issuer=Keycloak

• otpauth://totp/: This is the standard URI scheme for TOTP.
• Keycloak:alice: This is the label displayed in the authenticator app, typically Issuer:AccountName.
• secret=JBSWY3DPEHPK3PXP: This is the crucial part – the shared secret key. This same secret will be provisioned on both Keycloak’s server and Alice’s authenticator app.
• issuer=Keycloak: This tells the authenticator app which service this code is for, helping to disambiguate if Alice uses the app for multiple services.

Once Alice scans the QR code, her authenticator app generates a 6-digit code that changes every 30 seconds. This code is derived from the shared secret and the current Unix time, divided into 30-second intervals.

When Alice enters this code during login, Keycloak retrieves her stored secret key. It then performs the same calculation using the current time to generate an expected code. If Alice’s provided code matches Keycloak’s calculated code (within a small time window to account for clock drift), authentication proceeds.

The magic of TOTP lies in its stateless nature for the server. Keycloak doesn’t need to store the current code for each user; it only needs the secret key. The time-based algorithm ensures that the code is inherently temporary and tied to a specific device (or at least, a specific provisioning event).

The default configuration for TOTP in Keycloak is generally robust. However, understanding these parameters can help tune it. In the Keycloak Admin Console, under Authentication -> Flows -> browser -> (three dots) -> Configure, you can find settings related to TOTP.

• Period: This is the time window (in seconds) for which a TOTP code is valid. The default is 30. If you see frequent "invalid code" errors that aren’t due to user error, and you’ve confirmed clock sync isn’t the issue, you could slightly increase this, but it weakens security.
• Digits: The number of digits in the TOTP code. The default is 6. Changing this is highly discouraged as it breaks compatibility with standard authenticator apps.
• Look Ahead Window: This allows Keycloak to accept codes from the next time window. The default is usually 0 or 1. A 1 means it will accept the current code and the code from the immediately following 30-second interval. This helps users who might be a second or two slow entering the code.

The actual shared secret is stored encrypted within Keycloak’s user credentials. When a user is prompted for a TOTP code, Keycloak fetches this encrypted secret, decrypts it using its master key, and then uses it in the TOTP validation algorithm.

A common point of confusion is what happens if a user loses their device. Keycloak doesn’t inherently have a "recovery code" mechanism for TOTP by default. If a user loses their device and their secret key, they lose access via TOTP. Administrators would typically need to manually reset the user’s MFA status, forcing them to re-enroll their TOTP authenticator. This is a critical process to have documented.

The next step after mastering TOTP is often exploring other MFA methods like WebAuthn (FIDO2) or even SMS-based OTPs, each with its own set of trade-offs and implementation details.