Keycloak 2fa Email Authenticator

Abstract

1. Introduction

A Keycloak Authentication Provider for two-factor authentication (2FA) via email OTP. Supports Keycloak SMTP, SendGrid, AWS SES, and Mailgun.

2. Objective

🔒 Keycloak Authentication Provider implementation to get a two factor authentication with a OTP/code/token send via Email (SMTP, SendGrid, AWS SES, Mailgun)

This project demonstrates how Java can be applied to a real-world Cybersecurity & Ethical Hacking problem.

3. Key Features / Modules

• Email OTP login for Keycloak browser flows
• Configurable code length, TTL, resend cooldown, and max attempts
• Optional masked email display on the OTP form for better UX after the code is sent
• Multiple email delivery backends: Keycloak SMTP, SendGrid, AWS SES, and Mailgun

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• JDK 11 or later
• Maven / Gradle
• IntelliJ IDEA, Eclipse or Android Studio
• Git (to clone the repository)

6. Installation & Setup

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

<dependency>
  <groupId>io.github.mesutpiskin</groupId>
  <artifactId>keycloak-2fa-email-authenticator</artifactId>
  <version>26.3.0-KC26.6.1</version>
</dependency>

implementation 'io.github.mesutpiskin:keycloak-2fa-email-authenticator:26.3.0-KC26.6.1'

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add logging and alert notifications (email / Telegram)
• Write a threat model document for the tool
• Package it with Docker for safe lab testing

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which threat or attack does this project defend against?
2. What detection or protection technique is used and what are its limits?
3. How are false positives and false negatives handled?
4. Which cryptographic algorithms or security standards are involved?
5. What legal and ethical rules apply when testing a tool like this?

9. Source Code & License

This project is developed by mesutpiskin and published on GitHub under the Apache License 2.0. Please follow the license terms and credit the original author when you use or modify this code.