**Overview**
A system where users can log in using their **email Id /Username + Email OTP** instead of username/password, by Keycloak.
**Make Email OTP Java SPI **
# Run this to find the Keycloak container:
docker ps | grep -i keycloak
Result will look like
2550aa1a95b7 quay.io/keycloak/keycloak:26.1.0 "/opt/keycloak/bin/k…" 7 days ago Up 7 days 8443/tcp, 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp, 9000/tcp keycloak_app
fcca38958118 postgres:16 "docker-entrypoint.s…" 7 days ago Up 7 days (healthy) 5432/tcp
Run this in the droplet console to find the exact JAR download URL:
curl -s https://api.github.com/repos/for-keycloak/email-otp-authenticator/releases/latest | grep browser_download_url
We need email-otp-authenticator JAR if it is not available
**1. Download the email-otp-authenticator JAR**
curl -L -o email-otp-authenticator.jar https://github.com/for-keycloak/email-otp-authenticator/releases/download/v1.3.5/email-otp-authenticator-v1.3.5-kc-26.2.5.jar
**2. Copy into the running container**
docker cp email-otp-authenticator.jar keycloak_app:/opt/keycloak/providers/
**3. Run build inside the container (registers the provider)**
# Verify it's there
docker exec keycloak_app ls /opt/keycloak/providers/
docker exec keycloak_app /opt/keycloak/bin/kc.sh build
**4. Restart the container**
docker restart keycloak_app
# Now let's set up the Email OTP flow. Go to Keycloak Admin Console at [[https://64.227.190.56/|https://64.227.190.56/]]:
**1. First configure SMTP (if not already done)**
Realm Settings → Email
Host: smtp.gmail.com,
Port: 587
From: from email id
Username: your username,
Password: your app
password Enable StartTLS → Save → Test connection
**2. Create Email OTP Authentication Flow**
Go to Authentication → Flows → Create flow Name: Browser Email OTP
→ Save Add step → Username Password Form → Required Add step →
Email OTP → Required
**3. Bind the flow**
Client → account → Advance Override realm authentication flow bindings. →Browser Flow → Browser email otp
**Customize email content**
python3 -c "import zipfile; [print(f) for f in zipfile.ZipFile('email-otp-authenticator.jar').namelist()]"
# check current email template
python3 -c "
import zipfile
with zipfile.ZipFile('email-otp-authenticator.jar') as z:
print(z.read('theme-resources/messages/messages_en.properties').decode())
"
# To customize the email text, create a custom Keycloak theme. Run these commands on the droplet:
Step 1: Create theme directory \structure
docker exec keycloak_app mkdir -p /opt/keycloak/themes/cotrav/email/messages
Step 2: Create theme.\properties
docker exec keycloak_app sh -c 'cat> /opt/keycloak/themes/cotrav/email/theme.properties <<\EOF
parent=\base
EOF'
Step 3: Create custom messages (edit the text as you like)
docker exec keycloak_app sh -c 'cat> /opt/keycloak/themes/cotrav/email/messages/messages_en.properties <<\EOF
emailOtpSubject=Your Cotrav OTP \Code
emailOtpYourAccessCode=Your one-time login code is:
emailOtpExpiration=This code will expire in {0} minutes. Do not share it with anyone.
EOF'
Step 4: Set realm to use this \theme
TOKEN=$(curl -s -X POST http://64.227.190.56:8080/realms/master/protocol/openid-connect/token
-d "client_id=admin-cli&grant_type=password&username=superadmin_username&password=superadminpassword"
| grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
curl -s -X PUT http://64.227.190.56:8080/admin/realms/master \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"emailTheme":"cotrav"}'
Then test by logging in again — you should see your custom text in the OTP email.
# Invalid otp issue\\
The OTP field name sent by our server might not match what the extension expects. Let me check:
python3 -c "\
import zipfile\
with zipfile.ZipFile('email-otp-authenticator.jar') as z:\
print(z.read('theme-resources/templates/login-email-otp.ftl').decode())\
"
**# Browser email otp Flow order should be** \\
Username Form → Required (first)\\
Email OTP Form → Required (second)
**# Dont do this**
- No required user action available in user details\\
- Set Email & password