Keycloak - Because Building Auth From Scratch Sucks

Keycloak is Red Hat's open source identity management system that handles authentication so you don't have to build login flows from scratch and inevitably introduce security bugs. It's what you reach for when you realize that "simple auth" is never actually simple.

What It Actually Does

Handles OAuth Without the Pain: Keycloak speaks OAuth 2.0, OpenID Connect, and SAML 2.0 out of the box. No more reading RFC documents at 2am trying to figure out why you're getting "invalid_token" with zero useful context. It handles token generation, validation, and refresh automatically - and actually gets the edge cases right that trip up homegrown implementations.

Plugs Into Everything: Need to authenticate against Active Directory? Works. Want social logins from Google and GitHub? Already built-in. Got some legacy LDAP server from 2003? Unfortunately, Keycloak can probably talk to that pile of shit too. User federation setup is surprisingly painless once you find the right config options.

Multi-Tenant by Design: Realms are Keycloak's way of keeping different environments or customers isolated. Think of them as completely separate security universes - prod users can't accidentally access dev, and Customer A can't see Customer B's data. It's multi-tenancy that actually works, unlike most SaaS solutions that fake it with application-level isolation.

The Production Reality

Clustering Works (With Caveats): You can run multiple Keycloak nodes behind a load balancer for high availability. Session replication mostly works, though you'll want to test failover scenarios thoroughly. Don't expect it to work perfectly on the first try - or the tenth. I've spent hours getting "HTTP 503" errors that mysteriously fix themselves after restart.

Performance Needs Babysitting: Out of the box, Keycloak will choke under serious load. You'll need to tune the caching layers, optimize database connections, and probably spend quality time with JVM heap settings. Budget 40% more server resources than you think you need, or enjoy watching your CPU spike to 100% during login storms like I did during our product launch.

Compliance Box Checking: Audit logging captures everything - login failures, permission changes, admin fuckups. Auditors love the detail, your disk space will hate the volume. Just make sure you're actually shipping those logs somewhere useful - the default file logging fills up disks fast. I learned this lesson when we found 200GB log files eating our disk because log rotation mysteriously broke after an upgrade.

Current Status (September 2025)

The latest stable version is 26.3.3, released in August 2025. Each release brings security fixes and new features, though also occasionally breaks things in subtle ways. Always test updates in staging first - I learned that lesson when an upgrade broke all our SAML integrations and I spent 4am debugging "Invalid SAML Response" errors that made zero fucking sense.

Real companies use Keycloak in production, from startups who can't afford Auth0's $10k/month bills to Fortune 500s with compliance requirements. It's battle-tested software, just don't expect it to work like the Docker compose example - production deployment is a completely different beast.

So how does it stack up against the alternatives? Let's be real about the trade-offs.

Authorization - More Complex Than You Think

Permission Hell Is Real: Keycloak's UMA 2.0 support lets you build complex authorization rules based on attributes, time, location, and custom logic. Cool in theory, nightmare in practice. I've seen permission evaluations take forever because someone built a policy checking way too many user attributes. Test your policies under load or you'll learn about performance bottlenecks when your app crawls to a halt during launch week.

Role Hell Is Real: Roles in Keycloak work at realm and client levels, which sounds clean until you have 50 applications with overlapping permissions. Composite roles help but create inheritance nightmares. Pro tip: Start simple and resist the urge to model your entire org chart in roles. I've seen teams spend weeks untangling role dependencies they created in the first month.

JavaScript Policies Will Bite You in the Ass: Keycloak lets you write JavaScript authorization policies, which seems great until someone writes buggy JS that crashes the auth flow. You'll get cryptic errors like "Script execution failed" with zero context, or my personal favorite: "PolicyEvaluationException: null" - thanks for nothing, Keycloak. Stick to basic policies unless you enjoy debugging JavaScript at 3am when your production auth shits the bed and all you get is "500 Internal Server Error".

Performance - The Hidden Gotchas

Database Will Be Your Bottleneck: Even with connection pooling, a poorly configured database will kill performance. PostgreSQL is recommended, but you need proper indexing, connection limits, and monitoring. I've seen Keycloak bring down entire Postgres clusters because nobody configured max_connections properly - watching connection attempts stack up while getting "FATAL: sorry, too many clients already" is not fun. Newer versions had connection leaks that took down our prod database - spent hours staring at "org.postgresql.util.PSQLException: FATAL: remaining connection slots are reserved" before figuring out what the hell was happening.

Caching Is Mandatory, Not Optional: Out of the box, Keycloak's Infinispan caching is configured for demo environments. Production needs cache tuning, proper invalidation, and monitoring. Cache misses will send you straight to the database, and your users will notice the 2-second login delays. I learned this the hard way during a load test when response times went from 50ms to 3 seconds, and our monitoring dashboard turned red like a Christmas tree.

Realm Scaling Hits a Wall: Don't plan on running more than 100-200 realms per Keycloak instance. The admin UI becomes unusable, startup times explode, and database queries get expensive. This limitation isn't well documented but is very real.

Customization - Powerful but Painful

Theme Development Is Frustrating: Keycloak's theme system lets you customize everything, but the template engine is janky and error messages are useless. Expect to spend hours figuring out why your CSS isn't loading or why the login form broke after changing one line. Recent versions broke custom themes with helpful errors like "Failed to parse theme template" - the migration guide was basically "good luck, figure it out yourself."

SPI Development Requires Java Skills: Want custom authentication flows? Better know Java and Maven. The SPI documentation assumes you're comfortable with Java deployment, classloaders, and the Keycloak extension lifecycle. Not a weekend project.

Admin API Has Sharp Edges: The REST API has everything you need but is inconsistent as hell. Some endpoints return different data structures for similar operations, error handling is inconsistent, and there's no rate limiting built in. Always validate API responses because the schema changes without warning between versions - learned this when our user management broke because they changed field types in a minor version update.

Security Features That Actually Work

Session Management Works Once Configured: The session controls are solid - timeouts, concurrent limits, forced logout all work. Just remember that changing session settings requires users to log out and back in. Found this out during a security audit when we couldn't force immediate policy changes - users kept their old session permissions for 30 minutes despite the "immediate" setting.

Audit Logging Generates Massive Logs: The event logging captures everything, and I mean everything. Login attempts, token refreshes, admin actions - it adds up fast. Plan for log rotation and shipping or you'll fill disks. We generated insane amounts of logs for a medium-sized deployment - 90% useless INFO spam. The disk filled up on a Friday night at 11pm, naturally, with "No space left on device" killing the entire auth service.

Password Policies Need Reasonable Defaults: The HaveIBeenPwned integration is nice, but the API calls add latency to password changes. Also, overly strict password policies just train users to use predictable patterns. "Password123!" meets complexity requirements but isn't actually secure. I've seen users cycling through "Password123!", "Password124!", "Password125!" to get around history checks - the password policy that took hours to configure was defeated in 30 seconds.

Now that you've seen what Keycloak can do (and where it'll frustrate you), let's address the questions everyone asks when they're deciding whether to take the plunge.