Local Build & Deployment

Build the authenticator from source using Maven and deploy the JAR to your Keycloak installation.

Prerequisites

• Java 21+ — Download from Adoptium
• Maven 3.9+ — Download from Apache

Step 1 — Clone the Repository

git clone https://github.com/mesutpiskin/keycloak-2fa-email-authenticator.git
cd keycloak-2fa-email-authenticator

Step 2 — Verify Prerequisites

java -version  # Should show Java 21+
mvn -version   # Should show Maven 3.9+

Step 3 — Build the Project

mvn clean package

This produces target/keycloak-2fa-email-authenticator-26.4.0.jar.

:::note Skip tests If tests fail due to Java version compatibility (e.g. Java 25+):

mvn clean package -DskipTests

:::

Step 4 — Deploy to Keycloak

Standard Installation

cp target/keycloak-2fa-email-authenticator-*.jar <KEYCLOAK_HOME>/providers/

Dockerized Keycloak

cp target/keycloak-2fa-email-authenticator-*.jar /opt/keycloak/providers/

Step 5 — Rebuild Keycloak

After copying the JAR, register the provider:

Linux / macOS

<KEYCLOAK_HOME>/bin/kc.sh build

Windows

<KEYCLOAK_HOME>\bin\kc.bat build

Running Tests

mvn test

note

Tests may fail on Java 25+ due to Mockito/ByteBuddy compatibility. Use Java 21 for development.

What's Next?

• Authentication Flow Setup — wire up the 2FA flow
• Email Provider Configuration — choose SMTP, SendGrid, AWS SES, or Mailgun