Bot attacks on login endpoints are a constant headache. Credential stuffing and brute force attempts waste resources and risk account compromise. Traditional rate limiting is too blunt — it often punishes legitimate users sharing an IP. That's why a Proof of Work (PoW) challenge, specifically using the memory-hard Argon2id algorithm, offers a smarter defense. Below, we break down how it works, why Argon2id beats SHA-256, and how you can configure it for your Keycloak deployment.
Why use Proof of Work for Keycloak authentication?
Proof of Work forces the client to perform a computational task before accessing the login form. For real users, this adds a barely noticeable delay (like 100–200ms). For bots, it makes each attack attempt expensive — both in time and computing resources. Unlike rate limiting, which penalizes all traffic from a given IP, PoW targets each connection individually. A bot running thousands of attempts suddenly faces a massive overhead, dramatically reducing the attacker's return on investment. The challenge is lightweight for humans because browsers can compute it in the background, but scaling up for automated scripts becomes prohibitively costly. This approach effectively stops credential stuffing and brute force attacks without affecting legitimate user experience.
Why choose Argon2id over SHA-256 for PoW?
SHA-256 PoW, popularized by Bitcoin, is easy to parallelize. Attackers with GPUs can compute billions of hashes per second, making cheap cloud clusters capable of solving thousands of challenges quickly. Argon2id, on the other hand, is memory-hard: each computation requires a fixed amount of RAM (e.g., 16 MB). GPUs have limited memory bandwidth, so they cannot accelerate Argon2id significantly. A $200 CPU can perform ~0.2 challenges per second with Argon2id, while a $10k GPU barely matches that. In contrast, SHA-256 would give the GPU a 25x advantage. By using Argon2id, we neutralize the attacker's hardware advantage, making brute force economically unfeasible. The cost-per-attempt skyrockets, but legitimate users still enjoy fast login.
How does the Keycloak PoW extension actually work?
The system combines three layers: a honeypot field, solve-time validation, and a dual-hash verification. First, a hidden input in the login form traps simple bots — if filled, the server silently rejects without any hash computation, saving CPU. Second, every challenge is timestamped. If a submission arrives in under 100ms (configurable), it indicates pre-computation, so the request is rejected. Third, the browser solves a SHA-256 puzzle for quick UI response, but the server verifies using Argon2id — the real security gate. This means you cannot bypass the server cost. Additionally, difficulty ramps per IP address: base difficulty for the first few attempts, then exponentially harder after many failures. An attacker trying 50 times in a minute faces dramatically higher costs per attempt.
What is difficulty ramping and how does it help?
Difficulty ramping dynamically increases the PoW challenge hardness based on the number of recent failed attempts from an IP. For example, the first login from a new IP requires a low difficulty (e.g., 1 iteration of Argon2id, taking ~100ms). After 50 attempts in a minute, the difficulty jumps to 2 iterations, doubling the work. At 100 attempts, it might go to 4 iterations, making each attempt four times slower. This creates a steep cost curve: a bot might succeed a few times, but the overhead grows linearly (or worse) with persistence. Legitimate users who occasionally mistype passwords still experience only a slight delay because their failure count resets after a successful login or timeout. This approach thwarts automated attacks while keeping user friction minimal.
What configuration options are available?
The extension offers several parameters to fine-tune security and performance. A sample configuration looks like:
hash_algorithm = argon2
argon2_base_difficulty = 1
argon2_memory_kb = 16384 # 16 MB
argon2_iterations = 1
argon2_max_difficulty = 4- hash_algorithm: Choose between SHA-256 (fast) or Argon2id (memory-hard, default).
- argon2_base_difficulty: Starting difficulty (iterations count).
- argon2_memory_kb: RAM per challenge in kilobytes — higher values increase GPU resistance.
- argon2_iterations: Number of Argon2id iterations — more iterations equal harder work.
- argon2_max_difficulty: Ceiling to prevent excessive server load.
Additionally, you can set min_solve_time (e.g., 100ms) and difficulty_ramp_thresholds to control when difficulty increases.
What are the main benefits of this approach?
The primary benefit is protection against credential stuffing and brute force attacks without relying solely on IP-based rate limiting. Legitimate users experience a near-invisible delay, while attackers face escalating costs. The memory-hard algorithm (Argon2id) ensures GPU clusters are ineffective, so even sophisticated adversaries cannot scale cheaply. The multi-layer design (honeypot, timing checks, dual hash) prevents bypass attempts and reduces server load from dumb scrapers. Configurable difficulty ramping adapts to threat levels automatically. Overall, this solution provides robust security for Keycloak authentication with minimal impact on user experience, making it ideal for high-traffic applications that need to fend off automated attacks.