Learn Keycloak - Multi-Factor Authentication (MFA)

#Introduction

In episode 22 you recorded and audited activity. Episode 23 closes the biggest gap in login security: Multi-Factor Authentication (MFA). Passwords alone are no longer enough — combining factors makes phishing attacks or password theft lose much of their value. You'll look at OTP (TOTP/HOTP), WebAuthn and passkeys, SMS, conditional OTP, down to recovery codes and their security policies.

#MFA Basics

Authentication factors are divided into three categories:

MFA means combining at least two different categories. A password plus a security question doesn't count as MFA because both are "knowledge". The combination of password and OTP is the most common pattern and the easiest to implement in Keycloak.

#OTP (One-Time Password)

#TOTP vs HOTP

TOTP is the standard for mobile authenticator apps; HOTP is more common in older hardware tokens.

#Configuring OTP in Keycloak

OTP policy is set in Realm Settings → Authentication → OTP Policy: choose the type (TOTP or HOTP), number of digits, period, and algorithm (SHA1, SHA256, SHA512). The more modern the algorithm, the better. The same policy can be set via the admin CLI:

kcadm.sh update realms/myrealm -r myrealm \
  -s otpPolicyType=totp \
  -s otpPolicyAlgorithm=HmacSHA256 \
  -s otpPolicyDigits=6 \
  -s otpPolicyPeriod=30

Users enable OTP through the Configure OTP required action — they scan a QR code with Google Authenticator or FreeOTP. After that, every login goes through an OTP step.

#WebAuthn / FIDO2

#Hardware Security Keys

YubiKey and similar devices use the WebAuthn/FIDO2 protocol. Authentication is done by pressing a button on the device — something you "have" physically.

#Platform Authenticators

Windows Hello, Touch ID, and device biometric sensors are examples of platform built-in authenticators. Without additional hardware, users can still use passkeys.

#Passwordless Authentication

WebAuthn also opens the passwordless path: users sign in with a passkey only, without any password. This is a strong option as long as its recovery is well planned.

#Configuration in Keycloak

Keycloak provides Webauthn Policy and Webauthn Passwordless Policy in Realm Settings → Authentication: set the relying party, attestation, and user verification. Device registration is done through the WebAuthn Register required action.

#SMS Authentication

#SMS OTP

One-time codes sent via SMS. Practical because almost everyone has a phone.

#SMS Gateway Integration

Core Keycloak does not include a built-in SMS gateway. For SMS OTP, you need a custom authenticator (SPI) that calls an SMS service such as Twilio or a local aggregator. Revisit the custom provider mechanism from episode 21.

#Security Considerations

SMS can be intercepted through SIM swapping or carrier network gaps. Treat SMS as a second layer, not the only factor, and consider this risk when choosing a policy.

#Required Actions & Conditional OTP

A required action is a step users must complete, such as Configure OTP. The MFA policy can be made mandatory for all users or only under certain conditions.

Conditional OTP allows OTP to be requested only when conditions are met — for example access from an unknown IP — so users who normally log in from the same place aren't bothered every time. In Keycloak, this rule is arranged by adding a condition to the authentication flow. To inspect the flow steps, use kcadm.sh get authentication/flows/browser/executions -r myrealm.

#Recovery Codes

MFA strengthens security, but adds one problem: what happens if the device is lost? Since core Keycloak doesn't yet provide built-in recovery codes, you usually use a community extension or a manual recovery flow:

• Backup codes — one-time codes printed at setup; store them somewhere safe, not on the same phone.
• Recovery flow — if the device is lost, an admin resets the user's MFA via the admin console (recorded as an admin event, see episode 22).
• Code management — reissue new codes and revoke old ones after use or exposure.

Decide on a recovery strategy before production — waiting for a locked-out user on day 1 is a bad way to learn.

#The Complete MFA Flow

When all layers are in place, the MFA login flow in Keycloak runs like this:

1. The user enters username and password (the "knowledge" factor).
2. If conditional OTP is active, the flow checks the conditions — for example a new IP or an unrecognized device.
3. When the condition is met, the user is asked for a TOTP code from the authenticator app or a passkey from the device (the "possession" factor).
4. On success, the LOGIN event is recorded with the auth method details — audit evidence for episode 22.

If any factor fails, the LOGIN_ERROR event is stored and the brute force detection counter (episode 24) increments.

#Security Policies

Several recommended policies for MFA:

• Require MFA for sensitive roles or all users via a required action.
• Apply conditional OTP to balance security and convenience.
• Use modern OTP algorithms (SHA256/SHA512) and a reasonable period.
• Combine with the password policy from episode 20 and monitor via the events from episode 22.

#Closing

In episode 23, you understood MFA in Keycloak: the factor concept (knowledge, possession, biometrics), TOTP and HOTP OTP, WebAuthn with hardware keys and platform authenticators, SMS OTP with its risks, required actions and conditional OTP, recovery codes, and the security policies around them.

Key takeaways:

• MFA means at least two factors from different categories — a password plus a security question isn't MFA.
• TOTP via Google Authenticator or FreeOTP is the easiest built-in option.
• WebAuthn opens the passkey and passwordless path with physical security.
• Plan recovery codes before production — a lost device is the worst time to improvise.

In the next episode (episode 24), you'll complete the defense from another side: Brute Force Protection & Security — lockout, CAPTCHA, security headers, and session and token security.