Guidance on Enabling Email OTP MFA for Existing Users and Enforcing OTP for Sensitive Actions

Extending the server
1

Hello Keycloak community,

I have implemented an Email OTP Authenticator and integrated it into the Browser Authentication Flow with a Conditional User Attribute check. This ensures that Email OTP is only prompted if the mfa_enabled user attribute is set.

For new users, I have a custom Event Listener SPI that automatically sets mfa_enabled=true during the REGISTER event, requiring all new users to log in with Email OTP. This part works seamlessly.

Issue: Enabling Email OTP MFA for Existing Users

I need to provide a seamless way for existing users to enable Email OTP MFA from my client application. The flow is as follows:

  1. If mfa_enabled is not present in the JWT, the client app prompts the user to enable Email OTP MFA.
  2. Until now, users were not required to provide a real email address. We want to allow users to update their email to one they have access to.
  3. After updating their email, they receive an OTP to the new email address for verification.
  4. Only after successful OTP verification should mfa_enabled be set to true, enforcing Email OTP for subsequent logins.

Initial Approach & Challenge

I initially considered implementing two new Required Actions:

  • Email Update (to allow users to update their email).
  • Email OTP Verification (to verify the updated email).

I also planned to support Application Initiated Actions for these steps. However, since these are two separate Required Actions, the client app would have to manually orchestrate the flow—first triggering the email update, then triggering OTP verification. This is not ideal.

I would prefer Keycloak to orchestrate this entire process instead of relying on the client app.

Additional Requirement: Enforcing Email OTP for Sensitive Actions

Once Email OTP MFA is enabled, I also want to enforce OTP verification for sensitive account actions, including:

  • Username updates
  • Password changes
  • Account deletion

However, I do not want to force a full re-login before these actions—only an Email OTP prompt for additional security.

Questions:

  1. What is the best way to structure this Email Update + Email OTP flow within Keycloak without requiring client-side orchestration?
  2. Is there a way to combine both actions into a single Required Action?
  3. How can I enforce Email OTP verification for sensitive actions without requiring a full re-login?

I appreciate any suggestions or best practices from the community.

Thanks!

2

Hello @kmharish, here are the guidances I would give :

  1. Leverage Keycloak natives mecanisms:
    • Activate “Verify email” in realm settings > login tab, so that the built-in email verification mecanism will trigger after initial login or after address changes
    • Ensure the “email” attribute is mandatory in the “user profile” atb of the realm settings
    • Force an “update profile” required action for all existing users and mark their email as “not verified”. So that every existing users will have to verify their email, even if they already provided one.
    • The built-in “verify email” mecanism does not send an OTP by mail, but send an email with a verification link inside. It serves the same purpose, but if you really want an OTP in the mail, maybe you could override this mecanism (the “verify email” required action) or get inspiration from it.
  2. It should be possible, but it shouldn’t be necessary with the process described above
  3. I think this can be answered by leveraging the Step-up Authentication mecanism. Introduction and demonstration here : KEYCLOAK Step-Up Authentication explained

Hope that will help.