Skip to content

Keycloak

Placeholder — documentation in progress

This page collects what is already documented elsewhere and outlines what still needs writing. Items marked TBD have not been verified. Keycloak is complex, so once this outgrows one page it will become its own nav group (Overview, Realm & Clients, oauth2-proxy, Operations, …) following the navigation convention.

Role in the home lab

Keycloak is the single sign-on (SSO) identity provider for selected web applications. It works alongside Samba Active Directory, which handles domain logins, DNS and LDAP-backed applications.

Property Value
Realm BarnesBears
Integration oauth2-proxy → Traefik ForwardAuth middleware
Cookie domains .barnesbears.xyz, .davidplace.net
Host / deployment TBD
Version TBD
Admin console URL TBD
User source (local users vs AD/LDAP federation) TBD

How a login flows

Browser → Traefik router
        → OAuth error handler + OAuth ForwardAuth middleware
        → oauth2-proxy  (no valid cookie? → redirect to Keycloak)
        → Keycloak realm BarnesBears (login)
        → back to oauth2-proxy callback → cookie set → application

The standard middleware chain is described in Traefik → Authentication and middleware. Not every service uses it: applications with their own authentication, and API/webhook paths, need exceptions (Requestrr, for example, uses Discord authentication).

Integration patterns

Two authentication patterns are present in the home lab:

  • Traefik-protected applications: Traefik delegates access checks to oauth2-proxy through ForwardAuth; oauth2-proxy redirects unauthenticated browsers to the BarnesBears Keycloak realm. The historical middleware order is OAuth error handling, OAuth ForwardAuth, then compression.
  • Applications with native OIDC: Immich was configured to use the BarnesBears Keycloak realm directly. Verify its current OIDC client and redirect settings in the application and Keycloak before making changes.

These patterns are not interchangeable. A native-OIDC application's own login callback and an oauth2-proxy callback may need different redirect URIs and authentication policies. Not every proxied application should receive ForwardAuth: API endpoints, webhooks, and applications with their own login flow may require deliberate exceptions.

Login and authentication checks

Start with the public-facing hostname rather than assuming a particular container or deployment host:

curl -I https://auth.barnesbears.xyz/

The auth.barnesbears.xyz hostname was used for authentication in the Traefik environment; confirm its current routing and the Keycloak issuer URL before treating it as the realm endpoint. A redirect or HTTP response proves only that the endpoint responds, not that login works.

In Keycloak, the realm's OIDC discovery document is conventionally available at:

https://<verified-keycloak-host>/realms/BarnesBears/.well-known/openid-configuration

Replace the placeholder with the verified Keycloak hostname. The returned issuer must match what the OIDC client expects; compare the discovery document's authorization, token and JWKS URLs with the actual application configuration. Do not paste tokens, client secrets or authorization headers into logs or documentation.

Troubleshooting checklist

Symptom What to check
Redirect loop between application and login External scheme/host, trusted proxy headers, cookie domain and secure-cookie settings, callback URL, browser cookie behavior
invalid_redirect_uri Exact client redirect URI registration in Keycloak, including scheme, hostname, path and any required port
Login works but application rejects the user Client ID, issuer, audience/claims, group or role mapping, and any oauth2-proxy authorization restrictions
Login works on one domain but not another oauth2-proxy cookie domains (.barnesbears.xyz, .davidplace.net), callback host and cross-domain browser behavior; separate cookies or proxy instances may be required
Intermittent authentication or token errors Client and Keycloak clock synchronization, session/token expiry, TLS certificate validity and reverse-proxy reachability
Application works directly but not through Traefik Router and middleware attachment, ForwardAuth endpoint, OAuth error middleware and intended API/webhook exclusions

When diagnosing an incident, compare timestamps across Traefik, oauth2-proxy, Keycloak and the affected application. See AD Time Synchronization for Chrony checks. Use temporary, minimal logging and redact cookies, authorization headers and tokens.

Verification and maintenance

On the host running the relevant Docker stack, use read-only inspection to locate the services and their mounts:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Do not assume Keycloak and oauth2-proxy share a host or stack. Check the actual deployment and persistent database before upgrading or recreating either service.

Before changing a Keycloak client or authentication middleware:

  1. Record the existing client ID, issuer, redirect URI patterns, scopes and access policy (not secrets).
  2. Confirm the affected app's authentication method: native OIDC or Traefik ForwardAuth.
  3. Preserve a working administrator login and an appropriate recovery path.
  4. Test a normal browser login, logout and session renewal, then verify any API or webhook exceptions.
  5. Review Traefik, oauth2-proxy and application logs for unexpected authentication failures.

Details still to verify

In addition to the TBD fields above, document the Keycloak issuer hostname, proxy-header configuration, persistence/database backup method, oauth2-proxy deployment layout, actual client inventory and recovery procedure after inspecting the live environment.

To document

  • [ ] Deployment: host/container, version, database, persistent storage, how it is started and updated
  • [ ] Realm BarnesBears: login settings, themes, session and token lifetimes
  • [ ] User federation: whether users and groups come from Samba AD (LDAP) or are local, plus sync settings
  • [ ] Clients: one entry per protected application or oauth2-proxy instance, with client IDs, redirect URIs and scopes (no secrets)
  • [ ] Groups and roles: who gets access to what, and how that is enforced (oauth2-proxy allowed_groups, client roles)
  • [ ] oauth2-proxy: instances, cookie domains, upstream/redirect configuration, the error-handler middleware
  • [ ] Onboarding a new application: a step-by-step procedure (client → oauth2-proxy → Traefik middleware → test)
  • [ ] Backup and restore: realm export, database backup, recovery order relative to AD and Traefik
  • [ ] Troubleshooting: login loops, invalid redirect URI, clock skew (see AD Time Synchronization), expired certificates

Secrets

Never commit client secrets, oauth2-proxy cookie secrets, admin credentials, or realm exports that contain credentials. Reference where a secret is stored instead.