Keycloak Knowledge Patch

Keycloak Knowledge Patch

Use this skill for Keycloak implementation, configuration, authentication, administration, extension, operation, and upgrade work. Establish the exact server, Operator, adapter, and client-library versions before applying version-dependent guidance. Prefer the deployment's manifests, configuration, code, and observed behavior when they differ from general guidance.

Reference index

Working method

1. Identify the exact Keycloak image and Operator versions from deployment manifests, build metadata, or startup output.
2. Identify separately versioned consumers such as keycloak-js, Java extensions, themes, adapters, generated clients, and custom resources.
3. Load the reference matching the task. For an upgrade, load both the operational and extension/theme references, plus any protocol reference used by the deployment.
4. Treat preview and experimental features as explicit opt-ins. Verify their feature flags and profile before depending on endpoints or persisted data.
5. Test authentication, token refresh, logout, proxy, readiness, database, and rolling-upgrade behavior at their actual boundaries.
6. Preserve exact option spelling and distinguish build-time options from runtime configuration.

Breaking changes and deprecations

Preserve sessions during major upgrades

• When carrying online sessions forward, take the required intermediate persistence migration path; enabling persistence after the migration point cannot safely merge persisted and non-persisted sessions.
• Expect incompatible cache-marshalling changes to clear caches. Verify that sessions are database-backed before the cache transition.
• Apply explicit bounds to custom session caches instead of assuming the standard cache limits carry over.

Replace legacy hostname and proxy settings

• Use hostname v2 semantics. Supply a full frontend URL when scheme, port, or path matters, and always give the admin hostname as a full URL.
• Replace proxy with one trusted proxy-headers format plus the required hostname and HTTP settings.
• Enable dynamic backchannel resolution only with a full frontend URL.

Migrate browser integrations and themes

• Import browser code from keycloak-js or keycloak-js/authz; do not rely on deep imports, a server-hosted script, or a UMD/global build.
• Pass configuration explicitly, run in a secure context, and await login and URL-construction APIs.
• Move maintained themes to the current parent and shared-resource paths, and test custom FreeMarker templates against the newer compatibility level.

Update authentication and logout entry points

• Use OIDC RP-Initiated Logout instead of legacy redirect_uri behavior.
• Use prompt=create for registration and the supported /forgot-credentials authorization-path variant for credential reset.
• Do not deep-link into /login-actions or /broker.
• Replace the boolean WebAuthn discoverable-credential option with required, preferred, or discouraged.

Update extensions and API representations

• Treat UserRepresentation.getAttributes() as custom attributes only; use dedicated root properties or server-side getRawAttributes() as needed.
• Query identity providers through their dedicated endpoint rather than expecting them in ordinary realm representations.
• Do not restart a request transaction. Asynchronous work must own a separate session and transaction lifecycle.
• Replace removed token convenience methods and update provider-factory and test-builder APIs before recompiling extensions.

Remove obsolete configuration and dependencies

• Remove obsolete token-exchange and persistent-session batching switches.
• Replace dynamic-scopes with parameterized-scopes.
• Supply removed drivers and frontend libraries explicitly, and migrate away from removed handlers, BOMs, test helpers, admin clients, and brokers.
• Replace deprecated bootstrap administrator variables with KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD.

Security-critical quick reference

Redirects, origins, and logout

• Match redirect URIs exactly and case-sensitively unless the registered value has a trailing wildcard.
• Force exact matching when a wildcard request contains userinfo or /../, and never use a full * pattern in production.
• Treat token-embedded Web Origins as adapter-specific behavior, not portable OIDC client metadata.
• Validate post_logout_redirect_uri; logout confirmation presents it as a continuation instead of automatically redirecting.

Token exchange

• Use standard token exchange v2 only with confidential, authenticated requesters that explicitly enable the capability.
• Treat audience as a filter, never as a way to add an audience, and do not send the unsupported resource parameter.
• Require the original sender and matching DPoP proof or mTLS certificate for sender-constrained subject tokens.
• Restrict legacy exchange permission to trusted clients because its external JWT path does not validate aud.

Authentication assurance

• Order conditional LoA subflows from lowest to highest.
• Use an essential claims request when failure is required; acr_values is non-essential.
• Protect browser-carried assurance requests with PAR or a request object and verify the returned acr.
• Place the session limiter after the user is known and avoid checking normal SSO-cookie reuse a second time.

Secrets, trust, and client credentials

• Use KCRAW_ for literal environment values containing dollar signs, and do not define its KC_ counterpart simultaneously.
• Never place secrets in build options because build values are persisted in plaintext.
• Trust the authenticator CA for direct WebAuthn attestation.
• Anchor X.509 client credentials to an exact CA subject DN and move away from regex subject matching.
• Allow at least 86 characters in stores receiving newly generated client secrets, and verify rotated-secret invalidation behavior.

High-value features

Declarative client administration

• Enable Client Admin API v2 for strictly validated OIDC and SAML client management over REST, Java, generated JavaScript, CLI, or Operator resources.
• Use its management-interface OpenAPI document as the schema contract.
• Apply q filtering to the full representation before fields projection.

Organizations and provisioning

• Separate organization write, read, and query roles, and combine member listing with user-view permission.
• Use fine-grained organization resources for per-organization delegation.
• Enable group-role mappings when organization group roles must appear in realm, client, and organization token claims.
• Enable scim-api for preview user and group provisioning, PATCH, filtering, pagination, extensions, and schema discovery.

Policy, credential, and event protocols

• Enable authzen for single or batch authorization-policy evaluations.
• Enable ssf for signed CAEP or RISC events delivered through durable push or poll streams.
• Enable identity-assertion-jwt only for the receiving authorization-server role; the complete ID-JAG flow is not implemented.
• Configure OID4VCI refresh separately from credential lifetime, and use the dedicated client-attestation feature when required.
• Enable token-exchange delegation only when consent and refresh-time reassessment match the intended impersonation policy.

Operational resilience

• Route traffic with /health/ready; startup and liveness may be UP while asynchronous initialization remains incomplete.
• Bound queued requests with http-max-queued-requests to shed excess work with HTTP 503.
• Give provider JARs deterministic modification times before optimized builds.
• Treat the synchronously replicated database and its invalidation outbox as central to stateless multi-cluster operation.
• Roll clustered shutdowns one node at a time and account for cache-rebalance time.