Keycloak MFA, WebAuthn and passkeys

The main design choice for MFA in Keycloak is whether the second factor applies to every login in a realm or only to the logins that meet a condition. Keycloak runs sign-in as an authentication flow made of executions, and each execution can be set to required, alternative, conditional or disabled. A second-factor step such as OTP or WebAuthn can sit in the browser flow as a conditional sub-flow, so Keycloak evaluates the condition at sign-in and asks for the second factor only when the condition is true. The conditions are the part that decides who gets challenged, so they belong in the design before any flow is built.

A single realm-wide requirement is the simplest option to explain and to audit. One flow, one set of required executions, and every user and client follows the same path. The cost appears during rollout. If the organization needs to phase MFA in by application, team or user population, a realm-wide step forces a choice between a hard cutover and a temporary exception outside the flow, which is harder to track. Conditional steps let you start with a narrow scope, such as one administrative client or one role, and widen it later. The trade-off is that each condition adds a branch, and every branch needs its own test cases and documentation. A flow that looks small on a diagram can produce many more sign-in paths than the team expects.

Before you design the flow, list the condition types available in the Keycloak release you plan to run and write down how each one is evaluated. The server administration guide describes the authenticator conditions that Keycloak provides. Check the exact list against your release, since conditions are added and changed between versions, and confirm the behavior of each condition for brokered and federated users. A user who signs in through an external identity provider or from LDAP or Active Directory may not carry the same role, group or attribute data as a local user, and a condition that depends on that data can evaluate differently for these users. Brokered sign-ins also pass through a first broker login flow, so confirm which flow applies and whether MFA should be enforced there, in the upstream provider, or both.

Write the decision as a table before building anything. For each application, role, group or sign-in context, record whether the second factor is required, which condition selects it, which flow it lives in, and who owns the exception. Then test each row with a local user, a federated user and a brokered user, and with a client that uses the authorization code flow and one that does not. Illustrative example: a team might require WebAuthn for members of an administrators group on the admin client, and OTP as a fallback for everyone else, and find during testing that one group mapping does not reach brokered users. That gap is easier to find in a table than in production logs.

Keep the number of flows small and name them for their purpose so auditors and on-call engineers can read them. Export each flow definition into version control so changes are reviewed like code, and record which conditions depend on directory data that another team controls. The effort for this section grows with the number of conditions, the number of identity sources, and the number of clients that need different treatment. Ask any partner to show the condition matrix, the test cases for each branch, and the change process for adding a new client to the policy before you agree on scope.

The safest MFA rollout in Keycloak moves users through stages that each add pressure without removing access. Start with a pilot group, move to a prompted enrollment window where users are asked to register a second factor but can still sign in with a password alone, and enforce the requirement only group by group once support volume is understood. In Keycloak this maps to the Required actions and conditional authentication settings on the browser flow, so you can change who is challenged without rewriting the flow itself. Decide the stages, the group that enters each one, and the exit criteria for each stage before anyone is enrolled. The pilot group should be small, mixed and willing. Include administrators and people who will test the helpdesk procedure, not only technical staff. Use it to confirm the enrollment screens for OTP, WebAuthn security keys and passkeys in the browsers and devices your users actually run, and to check how the conditional UI for passkeys behaves on each. Record every confusing prompt. Pilot findings usually concern wording and device handling, not the protocol, so review them with the people who write user communication as well as the identity team. During the prompted enrollment window, users should see a clear message and a reminder, but not a hard block. This is the point to distribute recovery codes. Recovery codes are only useful if the user has them before losing a device, so require each user to generate and store them at enrollment, and tell them explicitly that a code is single use and must be kept somewhere other than the device it recovers. Confirm with your own policy whether codes are generated during the required action or on demand from the account console, and whether users can regenerate them. Do not enforce MFA for a group until its recovery code rate is at a level your helpdesk can handle. Before switching on enforcement for a group, write the helpdesk procedure for lost or replaced devices. The procedure should verify identity through a channel the attacker cannot easily control, such as a manager confirmation or a callback to a number already on file, and then have an administrator remove the lost credential or issue a new required action. It should never simply disable the OTP requirement for an account, because that creates a silent bypass that outlives the incident. Keep enrolling a new device and recovering an account as separate tickets with separate checks: enrollment adds a credential to a session the user already controls, while recovery reestablishes trust after a credential is lost. Expect support spikes at the start of the enrollment window, after each enforcement date, and after device refresh cycles. Keep the previous flow available until enforcement has run stably for a defined period that you set, and document how to revert a group to the prior browser flow binding. Rollback should change one group's binding, not restart the whole realm. Communicate each phase in advance through the channels users already trust, state what they will see and what to do if they cannot sign in, and link to the helpdesk contact. Confirm your support hours, staffing and escalation path with the people who will run them, since these are the costs that rise sharply if enforcement is switched on too broadly.

Test the MFA design before any user is asked to enroll, and treat the failure paths as first-class test cases. The goal is a written matrix that shows every authentication method works in every browser and device class your users actually use, and that a user who cannot finish MFA is routed to the documented recovery path rather than left at a dead end. Build the matrix in a non-production realm that mirrors the production authentication flow, client settings and required actions, so results carry over to the live configuration. On one axis, list each method you intend to offer: OTP through an authenticator app, a WebAuthn security key, a passkey, and a recovery code. On the other axis, list the browser and device combinations your user base uses, including the platform passkey providers on mobile devices and the conditional and modal passkey UI in each browser. Add rows for each conditional branch in the browser flow, such as the rule that prompts for a second factor only for certain clients, roles, groups or networks. Then add rows for brokered and federated users, because an identity provider that already performed MFA upstream may or may not be expected to satisfy the Keycloak condition. Confirm with your identity team which of these outcomes is intended before you write expected results. Next, test the edge cases that generate support tickets. Use an expired OTP code, a code entered twice, a security key removed mid-flow, and a passkey enrolled on one device but used on another. For each, record the exact message the user sees and whether the session can retry. Simulate lost-device recovery by removing the user's second factor through the admin console, then confirm the user can enroll a replacement through the recovery path you documented, and that recovery codes are single-use. Verify that an administrator removal of a credential takes effect at the next login, not only in a new session created later, and check the audit events that record the change. The fail-safe checks matter most. Make the MFA step fail deliberately for a test user who has no usable factor and confirm the flow lands on the documented recovery page with a clear next step. Then disable the required-MFA condition, or roll the authentication flow back to the previous binding, and confirm no account is stranded: users with only a passkey should still sign in, and nobody should be locked out because a required action was left pending. Record the rollback steps and time them, since they are the procedure you will use under pressure. Repeat the full matrix after every Keycloak upgrade and before each enforcement phase, not only at initial launch. Upgrade notes and minor-release changes can alter authentication behavior, and a rollout that passed in one release may need retesting in the next. Keep the results in a versioned sheet, record the Keycloak version and realm export used, and ask your implementation partner or internal team to confirm the expected outcome for each row before the test cycle starts.