DEV Community: Mr. Buch

Keycloak Knows. Why Doesn't The Rest Of Your Stack?

Mr. Buch — Thu, 14 May 2026 20:49:21 +0000

Here's a situation I've been in more times than I'd like to admit.

You set up Keycloak. It works great. Users register, log in, reset passwords — all handled. You move on to building the actual product. Then three weeks later, someone asks why the CRM doesn't have half the users in it. Or why the billing system is charging people who deleted their accounts six months ago. Or why the welcome email never went out.

Because Keycloak knew. Nobody else did.

So you go looking for the clean solution. Maybe you poll the admin API every few minutes? Sure, if you enjoy stale data and hammering your auth server for no reason. Maybe you query Keycloak's database directly? Works great until the next upgrade shuffles the schema and you spend a weekend figuring out why everything broke. Maybe you just... duplicate the registration logic in your backend and keep both in sync manually? I've seen this in production. It's exactly as bad as it sounds.

None of these are good options. They're just different ways to be annoyed later.

What I actually wanted was simple: when something happens in Keycloak, POST it to my backend. That's it. I don't want to poll. I don't want to touch the database. I just want an event, a payload, and an endpoint to send it to.

So I built it.

Keycloak Webhook is a small Keycloak extension — drop the JAR in, add two fields to your client config, and you start getting HTTP POSTs every time a user does something. Registration, login, logout, password reset, email change, account deletion. Your backend just handles the request and moves on.

How it actually works

The extension registers itself as a Keycloak event listener. When a user event fires, it looks up the webhook config on that client, then hands off the HTTP POST to a background thread. Keycloak doesn't wait. The user doesn't wait. If your endpoint is slow, fine. If it's down, it retries three times with a short backoff (1s, 2s, 3s) and logs what happened. Then life goes on.

The payload you get looks like this:

{
  "type": "REGISTER",
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_name": "john.doe",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "email_verified": false,
  "created_timestamp": 1747353600000,
  "user_ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
  "delete_by_admin": false,
  "user_roles": [
    "default-roles-myrealm",
    "offline_access"
  ],
  "organizations": [
    {
      "id": "org-uuid-1234",
      "name": "Acme Corp",
      "alias": "acme-corp"
    }
  ],
  "attributes": {
    "phone_number": ["+1-555-0100"],
    "company": ["Acme Corp"],
    "job_title": ["Engineer"]
  },
  "realm": {
    "id": "a3f8c2d1-1234-5678-abcd-000000000001",
    "name": "myrealm",
    "display_name": "My Application Realm"
  }
}

Supported events: REGISTER, REGISTER_ERROR, LOGIN, LOGOUT, RESET_PASSWORD, VERIFY_EMAIL, UPDATE_EMAIL, DELETE_ACCOUNT.

REGISTER_ERROR is the weird one — registration failed, so there's no user in Keycloak yet, but we still send what we have (email, name from the form, error details). Useful for tracking failed signups or debugging onboarding drop-off.

Setting it up

Build the JAR:

git clone <repo-url>
cd keycloak-webhook
mvn clean package

Mount it into Keycloak:

docker run -p 8080:8080 \
  -v ./target/keycloak-webhook.jar:/opt/keycloak/providers/keycloak-webhook.jar \
  quay.io/keycloak/keycloak:26.6 start-dev

It's a Keycloak SPI — auto-registers on startup, no theme files, no extra config.

Now the step everyone skips: go to Admin console → your realm → Realm Settings → Events, and add brew-event-webhook to the Event Listeners field. Save. Do this for every realm you care about.

The JAR alone does nothing until you activate it here. I know because I've forgotten this myself.

Then configure the webhook endpoint on whichever client you want. There's no Attributes tab in the UI for this — you'll need the Keycloak Admin API. You can get the client UUID from Admin console → Clients → your client → the URL in your browser.

For the token, don't use your admin user credentials. Instead, create a dedicated client for this:

Admin console → Clients → Create client
Enable Service account roles (under Capability config)
Go to that client → Service accounts roles tab → Assign role → filter by realm-management → add manage-clients

Then get a token from that client:

curl -X POST \
  "https://your-keycloak/realms/{realm}/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id={your-service-client-id}" \
  -d "client_secret={your-service-client-secret}"

Now fetch the full client representation first — the PUT replaces the entire object, so you need the existing data:

curl -X GET \
  "https://your-keycloak/admin/realms/{realm}/clients/{client-uuid}" \
  -H "Authorization: Bearer {access_token}"

Take that JSON, add (or merge) your webhook attributes into it, and PUT it back:

curl -X PUT \
  "https://your-keycloak/admin/realms/{realm}/clients/{client-uuid}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    ...existing client JSON...,
    "attributes": {
      ...existing attributes...,
      "api.url": "https://yourapi.com/webhooks/keycloak",
      "api.key": "your-secret-token"
    }
  }'

Don't skip the GET step. Sending a partial body to the PUT will wipe out existing client config.

That's the whole setup. Different clients can point to completely different endpoints with different secrets — a web app and mobile app posting to separate backends, each with their own auth key. No global config file, no redeploy.

The config, all in one place

Attribute	Required	Description
`api.url`	Yes	Your webhook endpoint
`api.key`	Yes	Bearer token, sent in the Authorization header
`disable.autologin`	No	`true` to prevent Keycloak from auto-logging in users after registration
`trusted.proxy.count`	No	Number of reverse proxies in front of Keycloak (default: 1). If client IPs are coming out wrong, this is probably why

What happens when your backend is down

Short answer: nothing bad. Keycloak keeps running, users keep getting logged in, and you get log lines that look like this:

WARN: Webhook request failed (attempt 1/3): 500 Internal Server Error
WARN: Webhook request failed (attempt 2/3): 500 Internal Server Error
WARN: Webhook request failed (attempt 3/3): 500 Internal Server Error
WARN: Max retries exceeded for webhook. Event: REGISTER, User: testuser

After three failures, the event is gone. There's no queue, no database, no replay mechanism. This is a deliberate tradeoff — adding durable queuing would mean adding infrastructure, and most people don't need it. For syncing a CRM or sending a welcome email, losing one webhook during a 3am outage is acceptable.

If you genuinely can't lose events, pair this with Keycloak's built-in event log as a backup, or replay from the admin API after recovery. But in practice, I've found that the retry behavior covers most real outage scenarios — by the third attempt, you're probably back up.

A note on async

Keycloak event listeners are synchronous. If I block on the HTTP POST, I block Keycloak — the user stares at a spinner while we wait for your endpoint to respond. That's a bad time.

Every webhook runs on a background thread pool instead. Your endpoint can take 10 seconds, throw a 503, or be unreachable. The user already logged in. Keycloak already moved on. This is non-negotiable — it's the whole reason the extension is useful in production.

What this doesn't do

No payload transformation, no event filtering, no guaranteed delivery, no replay.

If you only want REGISTER events, filter in your handler. If you need to reshape the payload for your CRM, do it in your backend. The extension does one thing — get events out of Keycloak and into your hands — and it does it without making itself complicated to operate.

Found a bug or want a feature? Open an issue on GitLab.

Protecting Keycloak Auth with Proof of Work

Mr. Buch — Wed, 06 May 2026 20:58:58 +0000

I got tired of watching our login endpoint get hammered by bots. Credential stuffing, brute force, the usual nonsense. Rate limiting helps, but it's blunt — one script kiddie from a datacenter and suddenly your whole office can't log in because they're all on the same IP.

That's why I built a Keycloak extension that does PoW (proof of work) challenges. Sounds complicated, but it's actually pretty elegant: make bots solve a math problem before they get to the password field. Real users barely notice. Attackers' ROI goes to zero ( not literally ;-) ).

The interesting part? I went with Argon2id as the default algorithm, not SHA-256. That decision deserves explaining because it's not what most people think of when they hear "PoW."

The Problem With Just SHA-256

Everyone knows SHA-256 PoW. Bitcoin uses it. It's simple: find a nonce where SHA256(data + nonce) has N leading zero bits. Done.

But here's the thing: SHA-256 is cheap to parallelize. If you've got a GPU (and attackers do), you can compute billions of hashes per second. Rent a cloud GPU for an hour, hammer someone's login endpoint with thousands of SHA-256 challenges, suddenly 5% of leaked passwords work.

I didn't want that.

Why Argon2id Changed My Mind

The reason is memory hardness — it requires a bunch of RAM per computation, not just CPU.

When you run Argon2id with 16 MB of memory per challenge (default), suddenly renting a GPU cluster becomes stupid. GPUs have tons of compute but memory bandwidth is bottlenecked. Your CPU on a $200 server does almost as well as a $10k GPU because the limiting factor shifts from compute to memory latency.

Real numbers: a CPU does ~5 SHA-256 PoW challenges per second (16-bit difficulty). Same CPU running Argon2id (16 MB, 1 iteration) does ~0.2 challenges per second. But an attacker's GPU, which crushes SHA-256 25× over, barely breaks even on Argon2id. It's not about being slow — it's about being GPU-resistant.

That's why it's the default.

How It Actually Works

There are three layers:

Honeypot field — There's a hidden input in the form. If it's filled, they're a bot. Silent reject, no hash work. Saves us CPU against dumb scrapers.

Solve-time validation — Every challenge gets timestamped. If someone submits in 100ms, they solved it offline. Reject. Minimum solve time is configurable.

The actual hash — Browser does SHA-256 (fast, just for UI responsiveness), but the server verifies with Argon2id (expensive, actual security gate). You can't bypass the server cost.

Plus, difficulty ramps up per IP. First few logins from an IP? Base difficulty (100ms on Argon2id). Try 50 times in a minute? Difficulty jumps. Try 100 times? It keeps climbing. Attacker's cost-per-attempt skyrockets.

Config Examples (Because Real Numbers Help)

Basic Setup

hash_algorithm = argon2
argon2_base_difficulty = 1
argon2_memory_kb = 16384      # 16 MB
argon2_iterations = 1
argon2_max_difficulty = 4
argon2_rate_threshold = 10    # per 60 sec

Legitimate login takes ~100ms extra. An attacker hammering from one IP hits difficulty=4 after ~50 requests. At that point, solving 1,000 challenges takes 5+ minutes. Not worth it.

If You Actually Care (Finance, Healthcare)

hash_algorithm = argon2
argon2_base_difficulty = 2
argon2_memory_kb = 32768      # 32 MB
argon2_iterations = 2
argon2_max_difficulty = 8
argon2_rate_threshold = 5     # stricter

Base load is 400ms. Rate-scaled attacks hit 1.6 seconds per attempt pretty quick. Someone trying 1,000 logins is looking at 25+ minutes of compute.

High-Traffic Site (If Argon2 Feels Too Heavy)

hash_algorithm = argon2
argon2_base_difficulty = 1
argon2_memory_kb = 8192       # 8 MB instead
argon2_iterations = 1
argon2_max_difficulty = 3
argon2_rate_threshold = 20    # more forgiving

Still GPU-resistant, but lighter. ~50ms base cost.

There's also SHA-256 fallback if you're doing 1,000+ logins per minute and profiling shows Argon2 is a real bottleneck. But honestly, unless you're a massive site, Argon2 is the right call.

Setting It Up

Grab it from GitLab:

git clone https://gitlab.com/mrbuch/keycloak/keycloak-pow.git
cd keycloak-pow
./mvnw clean package

Then drop the JAR into Keycloak:

docker run -p 8080:8080 \
  -v ./target/keycloak-pow.jar:/opt/keycloak/providers/keycloak-pow.jar \
  quay.io/keycloak/keycloak:26.6.1 start-dev

It's a Keycloak SPI, so it just... registers itself. Works on login, registration, password reset. No theme files to copy.

Want to tweak settings? Environment variables:

POW_HASH_ALGORITHM=argon2
POW_ARGON2_MEMORY_KB=16384
POW_ARGON2_BASE_DIFFICULTY=1
# ... etc

Or go to the Keycloak UI and edit per-flow. Your call.

Why This Matters

Rate limiting is defensive. Proof of Work makes the attack uneconomical. There's a difference.

Rate limiting says "you can try 10 times per minute." Attackers just spin up more IPs.

Argon2id PoW says "every attempt costs you 100-400ms of CPU and 16MB of RAM." Distributed across a botnet, suddenly you're looking at thousands of dollars in cloud costs to test 100k passwords. Or you just... don't.

One More Thing

I went with Argon2 because GPU-resistant proof of work is becoming table stakes. SHA-256 PoW made sense in 2015. In 2026, if you're serious about protecting auth, memory hardness matters.

It's not about being paranoid. It's about not making yourself the path of least resistance.

Questions? Issues? Hit up the GitLab repo.