Keycloak 2FA Email Authenticator: How to Set Up Email OTP Login

Can you enable email-based two-factor authentication in Keycloak? Yes, but a standard Keycloak installation does not provide a universal built-in email OTP challenge after every password login. To implement this behavior, you generally need a compatible custom authentication provider or your own Keycloak Authenticator SPI implementation.

To configure a Keycloak 2FA email authenticator, install a compatible provider, configure email delivery, create a copy of the browser authentication flow, add the email OTP execution after password authentication, and bind the tested flow to your realm or intended clients.

The most important step is verifying that users cannot complete the intended login without successfully passing the email challenge.

This guide explains how to implement email OTP in modern Keycloak deployments, configure authentication flows, test security controls, and troubleshoot common errors.

Does Keycloak Support Email OTP Authentication by Default?

Keycloak supports several authentication methods out of the box, including password authentication, time-based one-time passwords (TOTP), WebAuthn, and recovery codes.

It also includes email verification features.

However, email verification is not the same as email OTP authentication.

Keycloak Email Verification vs. Email OTP vs. TOTP

If your goal is to verify that a user owns an email address, Keycloak’s built-in Verify Email action may be sufficient.

If your goal is to require a fresh code delivered by email after password verification, you need an email OTP authenticator.

If your organization requires stronger phishing-resistant authentication, consider WebAuthn or passkeys instead.

For background on authentication methods, see our guide to how authenticator login works.

💡 Discover Helpful Guides: Email Authenticator: Complete Guide to Secure Email Authentication

How to Set Up a Keycloak 2FA Email Authenticator

The following workflow is intended for administrators managing a modern Keycloak installation.

Before starting: Test in a non-production realm or environment. Preserve a working administrative login and a rollback path.

Step 1: Check Your Keycloak Version

Identify the exact Keycloak version running in your environment.

Email OTP providers are often developed against specific Keycloak releases.

An extension that works with one version may fail with another because of changes to authentication SPIs, dependencies, or templates.

Before downloading a provider, review:

• Supported Keycloak versions
• Java runtime requirements
• Authentication SPI compatibility
• Required dependencies
• Release notes and known issues
• Project maintenance activity
• Licensing and security considerations

Do not assume that an older extension tutorial applies to a current Keycloak distribution.

Step 2: Choose an Email OTP Provider

One community implementation is:

mesutpiskin/keycloak-2fa-email-authenticator

The project documents email OTP authentication for Keycloak browser flows.

It supports several delivery backends, including:

• Keycloak SMTP
• SendGrid
• Amazon SES
• Mailgun

It also documents configurable OTP behavior such as code lifetime, resend cooldown, and maximum attempts.

Important: This is a third-party extension, not an official built-in Keycloak feature.

Review its source code, dependencies, supported versions, and deployment requirements before using it in production.

Step 3: Download a Compatible Provider JAR

Choose a release that matches your Keycloak installation.

The example project’s release naming includes the targeted Keycloak version.

Download the appropriate JAR from the project’s official release page or supported artifact repository.

Verify the artifact and its dependencies through your normal software supply-chain process.

Do not install an arbitrary JAR downloaded from an untrusted website.

Step 4: Install the Provider in Keycloak

For modern Keycloak distributions, custom provider JARs are installed in the providers directory.

A typical Linux-based installation uses:

/opt/keycloak/providers/

Copy the reviewed JAR to that directory.

For example:

cp <compatible-provider>.jar /opt/keycloak/providers/

Then rebuild the Keycloak server when required:

/opt/keycloak/bin/kc.sh build

For optimized deployments, start the server using the appropriate production configuration.

/opt/keycloak/bin/kc.sh start --optimized

These commands illustrate provider installation. They are not a complete production deployment configuration.

If the extension requires additional dependencies, include the supported dependency artifacts as instructed by the provider documentation.

Deploying With Docker

For containerized Keycloak deployments, include the provider in a reproducible image.

A simplified Dockerfile pattern is:

FROM quay.io/keycloak/keycloak:<tested-version> AS builder

COPY <compatible-provider>.jar /opt/keycloak/providers/

RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:<tested-version>

COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

Replace the placeholders with a verified Keycloak image version and matching provider artifact.

Configure the runtime database, hostname, TLS, and other production settings separately.

The exact Docker build process may require adjustments for your environment and extension dependencies.

Step 5: Verify Provider Discovery

Start Keycloak and inspect the startup logs.

Confirm that the provider loads successfully.

Open the Keycloak Admin Console and navigate to:

Authentication → Flows

When you create or edit a flow, check whether the new email authenticator is available as an execution.

If the provider does not appear, verify:

• The JAR is in the correct directory.
• The provider version matches Keycloak.
• The build completed successfully.
• Required dependencies are available.
• The server was restarted using the updated build.
• Startup logs do not contain provider-loading errors.

Do not continue to production flow changes until the provider is discovered correctly.

💡 Discover Helpful Guides: Email 2FA: Protect Your Inbox and Understand Email Codes

Configure Delivery Before Changing Login Flows

Test the sender and transport

Configure the delivery backend required by the extension. If it uses Keycloak’s email service, validate the realm’s SMTP settings first. If it uses another supported backend, review that integration separately. Use an appropriate sender identity, encrypted transport where supported, and credentials managed through your deployment’s secret-handling process.

Test delivery to the mailbox providers your users actually use. An SMTP connection test is useful but does not prove that every message reaches the inbox promptly. Spam filtering, sender reputation, and mailbox rules can still affect the experience. A Keycloak 2fa email authenticator depends on the complete path from challenge creation to a readable message.

Verify the destination policy

Decide whether the flow requires a previously verified email address and how address changes are approved. Do not let a user who knows only a password redirect the second-factor challenge to an arbitrary new inbox without an appropriate verification process. Missing, duplicate, or stale addresses need an explicit handling rule.

During testing, inspect a message on a real phone. The subject should identify the service, and the body should explain which sign-in the code belongs to without exposing unnecessary personal information. Keep templates concise enough that the code is easy to locate.

For every Keycloak 2fa email authenticator deployment, document who owns email delivery incidents. Identity administrators and mail administrators may be different teams; a shared troubleshooting path avoids leaving users stranded between them when the server reports success but the inbox remains empty.

Build a Browser Flow That Enforces the Challenge

Start with a testable copy

Copy the appropriate browser flow in a test realm and name it clearly. Preserve a known-working administrative route. Add the selected email authenticator execution according to the extension’s documentation, after the stage that establishes the user and satisfies your first-factor requirement. Do not edit production authentication simply to discover what an execution does.

Check execution requirements and branches

Keycloak’s Server Developer Guide explains execution requirements and authentication-provider behavior. Required, alternative, and conditional structures affect whether a step runs or can be bypassed. A Keycloak 2fa email authenticator placed in the wrong branch may display during one test while remaining optional in another path.

Review password login, existing SSO sessions, identity brokering, and any client-specific flow overrides relevant to your deployment. Requiring an email challenge at every page load is a different policy from requiring it during a fresh authentication. Define that distinction before deciding a skipped prompt is a defect.

Bind and verify the intended flow

Apply the copied flow to the test realm or intended client scope using the supported binding controls. Start a clean session and confirm the full sequence. A configuration that exists in the console but is not bound to the relevant entry point does not protect that login.

Capture the expected sequence as an acceptance test: first-factor success, email challenge, correct-code acceptance, then application access. The Keycloak 2fa email authenticator must also reject missing or invalid codes before success. Testing only the happy path cannot establish that the challenge is mandatory.

📘 Find the Right Guide: Email Authentication Failed Fixes for Login and Sending

Set Code Lifetime, Retry, and Resend Controls

Expiry and one-time acceptance

Require unpredictable codes, a bounded lifetime, and validation tied to the correct user and authentication transaction. Successful use should consume the challenge according to the implementation’s documented semantics. Verify that an expired code and a previously used code cannot finish a new login. These are acceptance criteria to test, not capabilities to assume from a plugin name.

For a Keycloak 2fa email authenticator, choose expiry with measured delivery latency in mind. An extremely short window can punish legitimate users when mail queues slow down. An unnecessarily long window increases exposure. Document the chosen balance and review it against real delivery measurements.

Attempts and request volume

Apply limits to incorrect submissions and challenge generation. Consider account-level abuse as well as network-level traffic; a single IP rule may behave poorly behind shared networks or distributed attacks. Coordinate extension-specific limits with the identity service’s other protections and verify how failure events are recorded.

Resend behavior and shared state

Specify whether resending replaces the previous code or resends the same active challenge. Make the UI and message wording match that behavior. Test two browser tabs, delayed messages, and repeated clicks. Avoid a system where users cannot tell which message remains valid.

In a cluster, state must remain consistent across nodes and concurrent submissions. A Keycloak 2fa email authenticator that stores critical challenge state only in a local process may behave differently after load balancing or restart. Review storage, expiry, and consumption together, then test those conditions directly before treating the limits as reliable.

Test Failure Paths Before Production

Build a test matrix that proves both enforcement and usability. The most valuable cases are often the ones a demonstration skips: a changed email address, an interrupted session, or a second request arriving after the first message. Use disposable test accounts and keep real user codes out of test reports.

Run the matrix against the actual packaged Keycloak 2fa email authenticator artifact, not only a developer’s local build. Repeat relevant cases through each application entry point that can authenticate users. Include existing sessions and brokered sign-ins where your policy expects the challenge to apply.

Separate a delivery success from an authentication success in the evidence. A mail provider accepting a message does not mean the user received it, and receiving it does not mean the code was accepted. Correlation identifiers and timestamps can connect these stages without logging the code itself.

Define release-blocking failures before the test starts. An optional challenge, unlimited guesses, or inconsistent cluster behavior should not be dismissed as a cosmetic issue. This turns the Keycloak 2fa email authenticator review into a decision supported by observable results rather than a screenshot of one successful login.

💡 Discover Helpful Guides: Passwordless Email Authentication With Magic Links and Codes

Operate the Flow Without Exposing Secrets

Measure the stages separately

Track challenge creation, delivery-provider acceptance, verification success, expiry, and recovery use. Aggregate timings can show whether users struggle with slow mail or confusing screens. Avoid placing OTP values, credentials, or unnecessary email addresses in logs, dashboards, or support tickets. Review retention and access controls for the diagnostic data you do keep.

A Keycloak 2fa email authenticator needs a clear incident definition. If delivery latency rises, distinguish a provider outage from a template problem or a realm configuration change. Keep a non-secret correlation identifier so support can follow one attempt without requesting the user’s active code.

Provide actionable user messages

After identifying the user in the appropriate stage, a masked destination can help someone recognize the expected inbox without showing the full address. Explain when to retry, how resend behaves, and how to seek help. Avoid revealing account existence through unauthenticated responses where that information should remain private.

Review messages with real users or support staff. “Invalid code” can mean mistyping, expiry, or using an earlier resend; the next action should be clear without exposing security-sensitive internals. Do not tell users to keep clicking until something arrives.

Operational ownership is part of the Keycloak 2fa email authenticator design. Assign responsibilities for server upgrades, extension maintenance, SMTP credentials, template changes, and user recovery. A feature with no clear owner tends to become difficult to change precisely when access failures make changes urgent.

Plan Recovery and Native OTP Alternatives

Avoid an automatic fail-open path

Decide how users recover when they cannot access the mailbox. The recovery process should verify identity through an approved route, not simply remove the second step after a delivery error. A mail outage is an availability problem; it does not prove the person at the browser is the account owner.

A Keycloak 2fa email authenticator fallback should preserve the policy’s intended assurance. Document who can reset enrollment, what evidence is required, and how the action is audited. Test the process before a production outage. Privileged accounts may need different recovery rules from ordinary users.

Consider a compatible authenticator app

Keycloak’s native OTP enrollment can be an alternative when dependence on email delivery is the main concern. Administrators must choose a supported OTP policy and confirm that the user’s app supports its algorithm, digits, and timing parameters. Native code generation removes the need to receive a new email for each challenge, but recovery still needs planning.

For a compatible TOTP policy, is an option to evaluate during enrollment. Test it against your realm’s actual configuration rather than assuming every OTP setting works with every app. It does not implement the email extension or replace server-side flow configuration.

Keep the distinction explicit in user instructions: Keycloak 2fa email authenticator delivers a challenge through the inbox, while an enrolled app generates a code from its own credential. Choosing one changes the dependency model and support process, not merely the look of the login page.

💡 Discover Helpful Guides

Google Email Two Factor Authentication Setup for Gmail

Roll Out With a Reversible Change Plan

Pilot with a representative group before expanding enrollment. Include users with different mailbox providers, devices, and accessibility needs. Record completion time, resend frequency, and support questions. A flow that works well for the engineering team may still confuse users who read email on a separate device or rarely change account settings.

Before releasing a Keycloak 2fa email authenticator, preserve the prior configuration and server artifact, document the intended bindings, and define rollback triggers. Test a rollback in the non-production environment. The plan should explain how existing sessions, enrolled users, and pending challenges are handled rather than assuming a container restart resolves every state change.

Communicate the change in advance through a trusted channel. Explain when users will see the challenge, which sender to expect, and how to contact support without disclosing a code. Do not train users to approve unexpected security requests simply because an email mentions your organization.

After rollout, compare observed failure rates with the pilot and review any policy exceptions. A growing exception list may indicate a design problem rather than a need for more bypasses. Keep the provider under the same upgrade and vulnerability-review discipline as the identity service itself.

The ongoing cost of a Keycloak 2fa email authenticator includes maintenance, delivery, and recovery. Make that ownership visible in the release record. It helps future administrators understand why the extension was selected and what must be retested when either Keycloak or the mail infrastructure changes.

💡 Discover Helpful Guides: How to Add Email to Authenticator App With QR or Manual Setup

Frequently Asked Questions

Is email OTP the same as Verify Email?

No. Verify Email confirms ownership through Keycloak’s verification process. An email OTP login extension adds a challenge to an authentication flow. They can both involve the same mailbox while serving different purposes, so enabling one should not be treated as configuring the other.

Is every community email authenticator compatible with my version?

No. Review the extension’s supported versions and test the exact artifact with your server image. Authentication SPI and template dependencies can change. A Keycloak 2fa email authenticator that worked in another deployment is evidence to investigate, not a compatibility guarantee for yours.

Can users keep signing in when SMTP fails?

Only through the recovery or alternative methods your policy explicitly permits. Do not silently accept a failed email challenge. Define and test the outage behavior before production, including the user-facing message, support escalation, and any stronger pre-enrolled method available to the affected user.

Are short-lived email codes phishing-resistant?

No. A user can still give a valid code to a fraudulent site. Expiry and attempt limits address specific risks but do not bind the user’s action to the genuine service in the way a phishing-resistant method is intended to do.

Can a mobile authenticator replace email delivery?

Yes, when you deliberately configure a compatible native OTP method and enroll users in it. That is a change of authentication method, not a setting inside every email extension. Confirm app compatibility, recovery procedures, and the flow requirements before making the new method available.

📖 Explore Articles: How to Add Email to Authenticator App With QR or Manual Setup

Final Thoughts

A Keycloak 2fa email authenticator is a small extension with a large operational footprint. It touches the login flow, mailbox security, message delivery, challenge state, and account recovery. Start by deciding whether email meets the requirement, then choose and review an implementation that matches your server version.

The most useful deployment evidence is a repeatable test sequence. Prove that the challenge runs where required, rejects incorrect and stale codes, behaves predictably after resends, and remains consistent across your real deployment topology. Verify the error path as carefully as the successful login. Preserve secrets while collecting enough diagnostic information to support users.

Keep ownership and rollback concrete. Someone must maintain the provider, someone must investigate delivery failures, and someone must control recovery exceptions. Those responsibilities should be agreed before the feature becomes a dependency for every user. Review them again when upgrading the identity service or changing mail providers.

If reliable email delivery is the main obstacle, evaluate native OTP or another supported method instead of weakening enforcement. The best Keycloak 2fa email authenticator implementation is one whose limits are understood and whose recovery path is tested. A successful demo is the beginning of that work; a documented, observable, reversible deployment is the result to aim for.