Looking for guidance on a clean self-service MFA and recovery code design #54659

tokapatrik · 2026-11-04T21:40:06Z

tokapatrik
Nov 4, 2026

Hi everyone!

I’m currently designing a self-service MFA solution for a B2B application using Keycloak. I’ve spent quite some time exploring the built-in authentication flows, required actions, recovery codes, and existing community extensions, but I keep running into limitations with each approach.

Before going down the route of custom development, I’d really appreciate some guidance from the community on whether there’s a cleaner, more idiomatic way to approach this.

Keycloak version: We’re currently targeting Keycloak 26.8.x, but we’re flexible about the version and happy to upgrade if a newer release offers a better solution.

What I’m trying to achieve

The goal is to give users control over their own MFA configuration while keeping recovery secure and predictable.

Ideally, I’d like the following behavior:

Optional MFA: Users can enable or disable MFA themselves. Initially, we’d support TOTP authenticator apps, with WebAuthn potentially added later.
Multiple MFA devices: Users should be able to register multiple TOTP authenticator devices and manage them individually, including removing devices they no longer use. Eventually, the same approach should work with WebAuthn credentials.
Recovery codes as a fallback: When users enable MFA, they should also be able to generate recovery codes. These should serve as a backup when their authenticator becomes unavailable, rather than being treated as a normal, standalone MFA method.
Consistent credential lifecycle: If a user removes their last regular MFA method, their recovery codes should also be invalidated automatically. If they enable MFA again later, they should generate a fresh set. Removing one of several registered devices should not affect the remaining devices or recovery codes.
Preferred authentication method: When multiple MFA methods or devices are configured, users should ideally be able to choose which one is presented by default while keeping alternatives available through “Try another way”.
Native user-initiated actions: Ideally, credential operations should happen in the user’s authenticated Keycloak context, with appropriate user events, rather than being performed through a backend service account.

I’m flexible about the implementation and even the overall approach. These are the outcomes I’m aiming for, not necessarily strict implementation requirements.

What I’ve explored so far

Conditional 2FA with OTP and recovery codes

The built-in Condition - User Configured works well for optional MFA. However, if the user removes their last OTP credential while recovery codes remain configured, Keycloak can still require recovery codes at login.

This creates an awkward state where the user has effectively disabled their authenticator but is still required to consume recovery codes on subsequent logins.

Automatic recovery code enrollment

I found the Add Recovery Codes option in the Configure OTP required action, which is almost exactly the behavior I want during enrollment.

Unfortunately, there doesn’t seem to be an equivalent mechanism for automatically removing recovery codes when the last regular MFA credential is deleted.

Application Initiated Actions for credential removal

The delete_credential AIA is great because the user can remove credentials through Keycloak itself.

However, it only removes one credential at a time. Chaining two AIAs through frontend redirects (first removing recovery codes, then the last OTP credential) feels fragile and introduces intermediate states.

Using the Admin REST API would be another option, but I’d prefer not to lose the distinction between user-initiated actions and administrative operations in the audit trail.

Managing multiple MFA devices and preferences

I’d also like users to be able to register and remove individual MFA devices without affecting their other credentials.

I haven’t found a straightforward self-service approach for managing the preferred authentication method or device. The Admin API supports credential ordering, but this doesn’t seem to be exposed through the standard Account Console.

Community extensions

I’ve also looked into projects such as keycloak-mfa-plugins, particularly because we may want to support email-based OTP in the future.

I’m open to using an existing extension if it provides a more complete approach to MFA enrollment, method selection, credential management, and recovery.

What I’d appreciate guidance on

Is there a recommended Keycloak-native approach, authentication flow configuration, or existing community extension that would cover these requirements without having to implement significant custom credential-management logic?

In particular, I’m interested in:

Whether recovery codes can remain available as a fallback without independently enabling MFA when all regular MFA credentials have been removed.
Whether there’s an existing mechanism to automatically invalidate recovery codes when the last regular MFA credential is deleted.
How others handle registering, managing, and removing multiple TOTP devices through self-service flows.
Whether there is a supported way for users to manage their preferred MFA method or device themselves.
Whether there’s an established approach that keeps these operations within Keycloak’s native user-initiated flows and audit events.

I’d prefer to avoid maintaining custom Java extensions if possible, but I’m open to different approaches if there’s a well-established solution.

Related discussions

Recovery authentication codes – Recovery authentication codes #8518
Add recovery codes after setting any MFA credential – Add recovery codes after setting any mfa credential #42290
Additional authenticator: Condition - credentials configured – Additional authenticator "Condition - credentials configured" #21156
Credential ordering – Make it possible to set order of credential types #12102

Has anyone implemented a similar setup, or would you recommend approaching the overall MFA design differently?

Thanks in advance for any pointers or suggestions!

AZapata27 · 2026-11-06T13:10:09Z

AZapata27
Nov 6, 2026

Most of this is doable with built-ins. The exception is cleaning up recovery codes, which needs a small bit of code. I checked against 26.8.1.

Leftover codes still triggering 2FA. Condition - User Configured only looks at non-subflow executions that sit next to it, and when they're all alternatives it passes if any one of them is configured (source). In the default browser flow the recovery code form is a sibling of OTP Form, so the codes alone satisfy it. Nested sub-flows are skipped by that check, so move the codes one level down:

2FA                                  Conditional
  Condition - User Configured        Required
  OTP Form                           Alternative
  WebAuthn Authenticator             Alternative
  Recovery (sub-flow)                Alternative
    Recovery Authentication Code Form  Required

The condition now only counts OTP/WebAuthn, while alternative sub-flows are still walked when building the "Try another way" list (source). I read this from the code but haven't run this exact flow, so test it first.

Invalidating codes. Nothing built in: deleting a credential removes just that one. It matters more than it looks, because "Add Recovery Codes" on Configure OTP skips setup when codes already exist, so a user who re-enables MFA keeps the old set. The smallest fix I can see is an event listener on REMOVE_CREDENTIAL. Both the Account Console delete and the delete_credential AIA emit it. When no otp or webauthn credential is left, the listener removes recovery-authn-codes. The trigger stays a user event in your audit trail.

Multiple devices work natively. Each OTP credential is separate and has a label. The Account Console adds and removes them one by one, and the OTP login form shows a device picker when there's more than one.

Preferred method. The default alternative follows the order of the user's stored credentials (source). But the Account REST reorder endpoints are commented out (here), so today only the Admin API can change it. That's #12102.

0 replies

Navigation Menu

Repository navigation

Looking for guidance on a clean self-service MFA and recovery code design #54659

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Looking for guidance on a clean self-service MFA and recovery code design #54659

Uh oh!

tokapatrik Nov 4, 2026

Replies: 1 comment

Uh oh!

AZapata27 Nov 6, 2026

tokapatrik
Nov 4, 2026

AZapata27
Nov 6, 2026