Keycloak

Last reviewed Aug 26, 2026 · 854 words

Keycloak is the right identity server for perhaps 1 in 10 self-hosters, and the wrong one for the rest. If you need SAML 2.0 for a corporate app, identity brokering across several upstream providers, or a Red Hat-backed product your employer will sign off on, nothing else in the open-source identity category matches it. If you want single sign-on for a dozen Docker services at home, Authentik does the same job with a friendlier UI and a fraction of the operational reading. This guide is for the first group, and for anyone who wants to know which group they are in.

The 1 GB minimum is a floor, not a typical figure

Keycloak is a Java application running on Quarkus. The 1,024 MB minimum is honest: an idle instance with a single realm sits around 500 to 700 MB of resident memory, and the JVM grows toward whatever heap you allow it during imports and token-heavy traffic. Budget 2 GB on the host if the same box also runs Postgres, which it should, because the default dev-file H2 database is explicitly for development only and loses data in ways that are unpleasant to discover.

It also wants its own Postgres database, not a shared one. Keycloak owns its schema and runs migrations on every upgrade; sharing that database with another app is asking for a bad afternoon.

Realms, clients, and roles: the model you must learn first

Everything in Keycloak hangs off a realm. The master realm exists to administer other realms and should hold nothing else; create a second realm (call it home or your domain) and put every user and application in there. Each application you protect is a client inside that realm, with its own client ID, redirect URIs, and protocol (OpenID Connect or SAML). Users get roles, roles get mapped into tokens, and applications read the tokens.

That is 4 concepts, and the admin console exposes roughly 40 more. Ignore the rest until an application demands it. Most self-hosted apps need exactly one OIDC client with a client secret and one redirect URI, and the Authelia vs Authentik comparison shows how much simpler that looks in the smaller tools.

The proxy and hostname settings that break every first login

Nearly every "Keycloak works but login redirects to the wrong place" thread comes down to two settings. Keycloak generates absolute URLs from what it believes its public hostname is, and behind a reverse proxy it believes wrong unless told.

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: change-me
      KC_HOSTNAME: https://sso.example.com
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: change-me-too
    ports:
      - "8080:8080"

KC_HOSTNAME must be the full public URL. KC_HTTP_ENABLED lets the container speak plain HTTP to the proxy; KC_PROXY_HEADERS=xforwarded makes it trust the X-Forwarded-* headers from Caddy or Traefik so it reconstructs https:// correctly. Use start, not start-dev, for anything that survives a reboot: dev mode disables caching and hostname checks, and people forget they left it on. Older images use KEYCLOAK_ADMIN instead of the bootstrap variables; check the release notes for the tag you pull.

LDAP federation is where it earns its keep

If you already run a directory, Keycloak can federate it rather than replace it: users authenticate against LDAP or Active Directory, Keycloak issues the tokens, and group membership maps to roles. That is the feature that justifies the weight in a small business, and it is why the tool shows up as the open answer in the Okta replacement guide. At home, a lightweight directory like LLDAP behind Keycloak gives every app a single user list for about 30 MB of extra RAM.

Social login and identity brokering (sign in with Google, GitHub, or another Keycloak) are the other headline features. They work well and configure in minutes once the realm exists.

Upgrades are safe if you read, and risky if you do not

Keycloak ships releases often, and major versions change defaults, deprecate configuration keys, and occasionally require a manual step. Pin a specific image tag rather than latest, take a pg_dump before every upgrade, and read the upgrading guide for each major jump. Skipping several majors at once is supported through the automatic schema migration, but the configuration side, particularly the hostname options that were reworked in recent releases, is where a blind upgrade bites.

What I'd do

For a home network with fewer than 20 apps and no SAML requirement, I would not run Keycloak; Authentik covers the same OIDC use case and asks for less. If SAML, brokering, or an LDAP-backed staff directory is on the list, run Keycloak with its own Postgres on a host with 2 GB free, KC_HOSTNAME set from day one, start mode, a pinned tag, and a pre-upgrade dump in the runbook. Treated that way it is the most complete identity server you can self-host, and it has been since 2014.