What is Keycloak?
Keycloak is an open-source IAM server maintained by Red Hat. It runs as a standalone server (the Quarkus distribution) and your applications integrate with it over standard protocols. Your apps never see passwords — they send users to Keycloak and receive signed tokens back.
Core capabilities
Section titled “Core capabilities”Single Sign-On (SSO)
Section titled “Single Sign-On (SSO)”Once a user authenticates with Keycloak, any other application in the same realm can receive a valid token without asking the user to log in again. The session lives in Keycloak, not in your apps.
Standard protocols
Section titled “Standard protocols”Keycloak speaks OpenID Connect (OIDC) and OAuth2 as its primary protocols. It also supports SAML 2.0 for legacy enterprise integrations. Any compliant application — regardless of language or framework — can integrate without custom auth code.
User management
Section titled “User management”The admin console and REST API let you create, update, disable, and search users. Users can reset passwords, verify their email, configure TOTP, and manage sessions — all through Keycloak, not your app.
Identity brokering and social login
Section titled “Identity brokering and social login”Keycloak can delegate authentication to external identity providers — Google, GitHub, Microsoft, Facebook, or any OIDC/SAML-compatible IdP. Users click “Sign in with Google” on YOUR realm’s login page; Keycloak handles the federation.
User federation
Section titled “User federation”If your organisation already has users in LDAP or Active Directory, Keycloak can connect directly. Users authenticate against their existing directory; Keycloak synchronises attributes and manages sessions.
Admin console and REST API
Section titled “Admin console and REST API”Every operation available in the admin console is also available via the REST API. You can automate realm setup, client registration, and user creation using the API or the Keycloak Terraform provider.
What changed in recent versions
Section titled “What changed in recent versions”Keycloak moved fast between versions 22 and 26, and a lot of older tutorials are now wrong. This course targets Keycloak 26.x (26.7 at the time of writing). These are the changes most likely to trip you up if you have read an older guide.
| Change | Landed in | What it means for you |
|---|---|---|
| Quarkus distribution only | 17 (WildFly retired in 2022) | There is no standalone.xml. Configuration is CLI options and KC_* environment variables. |
| New account console is the default | 24 | The v1 and v2 account console themes were removed in 22 and 25. |
| Most Java adapters removed | 25 | Use your framework’s standard OIDC/OAuth2 support instead. |
| Persistent user sessions by default | 25 | Sessions are stored in the database, so they survive a restart. |
| Organizations | 26 | A first-class multi-tenancy model inside one realm. |
| Hostname v2 | 26 | --hostname accepts a full base URL, and the old hostname options are gone. |
| Bootstrap admin variables renamed | 26 | KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD became KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD. |
| New default login theme | 26 | The keycloak.v2 login theme replaced the old one. |
If a blog post tells you to edit an XML file, download a keycloak-connect adapter, or set KEYCLOAK_ADMIN, it predates the server you are running.
Where Keycloak sits in your architecture
Section titled “Where Keycloak sits in your architecture”Keycloak sits between your users and your applications. Users authenticate once with Keycloak and receive signed tokens. Your apps validate those tokens locally — without calling Keycloak on every request.
flowchart TD U[Users] --> K[Keycloak auth server] K -- issues signed tokens --> A[Your apps]
Trade-offs
Section titled “Trade-offs”| Option | Benefit | Cost |
|---|---|---|
| Self-host Keycloak | Full control over data residency, no per-monthly-active-user fee, and every part is customisable, including themes and SPIs | You operate the infrastructure yourself (patching, scaling, backup, HA) and need a team that understands Keycloak internals |
| Managed IdP (Auth0, AWS Cognito) | Fast to get started, no server to run, and comes with vendor SLA and support | Cost grows with user count (MAU pricing), customisation is more limited, and user data lives outside your own infrastructure |
Common mistakes
Section titled “Common mistakes”- Treating Keycloak as “install it and you’re done” — Keycloak needs ongoing care: version upgrades, performance monitoring, and security patching, just like any other production service.
- Choosing self-hosting without evaluating the ops cost — teams with no experience running a stateful service often underestimate the infrastructure and on-call cost compared to paying for a managed IdP.
- Confusing Keycloak with application-level authorization — Keycloak only handles authentication and token issuance; the complex authorization logic specific to each application still has to be implemented by that application.
Real-world example
Red Hat build of Keycloak (RH-SSO) — Red Hat itself distributes Keycloak with commercial support under the name “Red Hat build of Keycloak” (formerly “RH-SSO”), for organisations that want an SLA and a certified build without losing open-source flexibility.
Large enterprises — companies with dozens of internal applications commonly self-host Keycloak to consolidate login into a single SSO, reducing password-reset helpdesk load and letting the security team control authentication policy from one place.