Keycloak Knowledge Patch

Keycloak Knowledge Patch

Use this skill when configuring, extending, integrating, administering, or upgrading Keycloak. Start with the breaking-change checks below, then open the topic reference that matches the task.

Reference index

Breaking-change triage

Preserve sessions before crossing into 26

• Upgrade through 25 and enable preview persistent-user-sessions on that first upgrade.
• Only sessions already backed by remote Infinispan or embedded-cache JDBC persistence can migrate.
• Do not enable persistence later and expect persisted and non-persisted sessions to merge safely.
• Expect 26 to clear caches because Protostream is incompatible with the former JBoss Marshalling format.

Replace removed hostname and proxy configuration

• Treat hostname v2 as the active model: hostname accepts a host or full URL, and hostname-admin requires a full URL.
• Replace removed hostname-v1 path and port settings.
• Replace proxy with exactly one trusted proxy-headers format and explicit HTTP/hostname settings.
• Use a full frontend URL with hostname-backchannel-dynamic=true for dynamic backchannel resolution.

Move caches and transactions to runtime-safe settings

• Supply cache, cache-stack, and cache-config-file at runtime; they are no longer build options.
• Account for transaction-xa-enabled=false by default.
• With multiple datasources, configure all but at most one as XA.
• Bound custom session-cache definitions consistently with the standard configuration.

Update themes and browser clients

• Migrate welcome themes from PatternFly 3 to 5 and Account Console themes from keycloak.v2 to keycloak.v3.
• Replace shared node_modules/... theme paths with the appropriate vendor/... path; bundle Alpine.js or jQuery when needed.
• Import from keycloak-js or keycloak-js/authz; the server no longer serves the library and the global UMD build is gone.
• Pass adapter configuration explicitly and await login(), createLoginUrl(), and createRegisterUrl().

Audit identity and token compatibility

• Use dedicated identity-provider endpoints for normal realm reads; only exports embed identity providers.
• Treat an identity-provider alias as immutable after creation.
• Attach compatibility mappers when clients still require session_state in tokens or nonce after refresh.
• Use standards-based RP-Initiated Logout; legacy logout redirect_uri behavior is removed.
• Update custom code that assumed UserRepresentation.getAttributes() included root user fields.

Rework removed and renamed extension APIs

• Replace token convenience setters expiration, notBefore, and issuedAt with exp, nbf, and iat.
• Pass Config.Scope to EnvironmentDependentProviderFactory.isSupported.
• Do not restart a request's KeycloakSession transaction; a transaction may be started only once.
• Give asynchronous REST work its own session and transaction lifecycle.
• Update event listeners for credential events and realm deletion behavior.

Plan large-schema migrations

• Inspect startup output for manual index SQL when affected tables exceed 300,000 rows.
• Run the emitted statements after startup; do not assume automatic migration created those indexes.
• Check USER_ATTRIBUTE, FED_USER_ATTRIBUTE, RESOURCE_SERVER_PERM_TICKET, and IDENTITY_PROVIDER according to the upgrade path.

Security-critical checks

Apply post-release security fixes

• Use the 26.7.2 fixes when account linking or reset-credentials flows are exposed; both received account-takeover corrections.
• Ensure Admin REST does not expose vault-resolved rotated secrets and show-config does not reveal the vault keystore password.
• Verify disabling client-secret rotation invalidates the rotated secret.
• Confirm fine-grained permissions protect Role Groups, hidden group parents, and parameterized user-property mappings.

Harden redirects and browser requests

• Prefer exact, case-sensitive redirect URIs.
• Never use the full * redirect pattern in production.
• Know that userinfo and /../ paths force exact matching even when a trailing wildcard is configured.
• Protect browser-carried LoA requests with PAR or a request object, and verify the returned acr.

Anchor credentials and sender constraints

• Configure the X.509 client's exact Certificate Authority subject DN; regex matching is deprecated.
• Use HAProxy ssl-cert-chain, not ssl-cert-chain-prefix.
• Exchange DPoP- or mTLS-bound tokens only as the original client with the corresponding proof or certificate.
• Reject implicit and hybrid flows for clients requiring DPoP-bound tokens.

Protect legacy token exchange

• Prefer standard token exchange v2 for same-realm Keycloak access tokens.
• Keep public clients out of v2; confidential requesters must authenticate and explicitly enable the capability.
• Treat legacy v1 as deprecated and narrowly authorize its token-exchange permission.
• Do not rely on legacy external JWT exchange to validate aud.

High-value authentication guidance

Configure standard token exchange v2

1. Enable Standard token exchange on the confidential requester.
2. Authenticate the requester at the token endpoint.
3. Send a same-realm Keycloak access token as subject_token.
4. Request an access token, ID token, or permitted refresh token.
5. Use audience only to filter already-resolved audiences; it cannot add one.
6. Apply downscope-assertion-grant-enforcer when requested scopes must be bounded by the subject token.

V2 does not support RFC 8693 resource, never creates a new user session, and requires the requester in the subject token's aud unless the token was issued to that requester.

Build passkey-aware conditional 2FA

• Combine Condition - User Configured with Condition - credential in the conditional 2FA branch.
• The credential condition skips 2FA after passwordless WebAuthn already authenticated the user.
• Make WebAuthn and recovery codes Alternative when configured users should see them under Try Another Way.
• Use required, preferred, or discouraged for discoverable credentials; the former boolean option is deprecated.

Express LoA and AMR correctly

• Order Conditional - Level Of Authentication subflows from lowest to highest.
• Remember the first LoA subflow always runs on initial authentication.
• Use an essential claims request when the level must be enforced; acr_values is only advisory.
• Map successful execution references into amr with the AMR protocol mapper.
• Use Client Policies and AuthenticationFlowSelectorExecutor when flow and level selection depend on client conditions.

Place the session limiter safely

• Put User Session Count Limiter after the user is known in Browser, Direct Grant, Reset Credentials, and Post Broker flows.
• Reuse one consistent configuration.
• In Browser, put it inside an alternative real-authentication branch alongside the top-level Cookie execution so SSO-cookie reuse is not counted again.
• Choose whether overflow denies the new session or terminates the oldest; 0 disables the relevant limit.
• Do not design around this authenticator for CIBA, where it is unavailable.

High-value API and identity features

Use Client Admin API v2 deliberately

• Enable client-admin-api:v2 for strictly validated declarative OIDC and SAML client management.
• Use REST, Java, generated JavaScript, CLI, or the management-interface OpenAPI document.
• Filter collections with the supported SCIM subset and project fields only after filtering.
• Expect HTTP 400 for malformed expressions, unknown fields, or ordering operators.

Choose the right identity capability

• Enable scim-api for preview user/group CRUD, PATCH, filtering, pagination, Enterprise User extensions, and schema discovery.
• Enable identity-assertion-jwt when Keycloak must receive a signed identity assertion and issue an access token without another login.
• Enable authzen for single or batch permit/deny policy evaluations.
• Enable ssf to transmit signed CAEP or RISC Security Event Tokens over push or poll delivery.
• Enable stateless for multi-cluster v2's embedded caches and database-backed invalidation outbox.

Administer organizations safely

• Assign manage-organizations, view-organizations, or query-organizations for coarse-grained access.
• Require view-users or equivalent fine-grained permission before viewing members.
• Use organization-specific fine-grained permissions for scoped access.
• Expect organization group roles in members' realm_access and resource_access claims.
• Enable Add group role mappings to group those roles by organization in the organization claim.

High-value operational guidance

Preserve exact environment values

• Use KCRAW_ instead of KC_ when dollar characters and ${...} must remain literal.
• Never define both raw and evaluated forms for the same key.
• Pair KC_<suffix> with KCKEY_<suffix> when normalization cannot represent the exact option key.

Keep optimized builds reproducible

• Never place secrets in build options; every build option is persisted in plaintext.
• Under start --optimized, repeated matching build options are ignored and differing values are rejected.
• Rebuild to change a build option.
• Normalize provider JAR modification times before kc.sh build in container images.

Gate traffic on readiness

• With health enabled, startup and liveness may be UP while initialization continues.
• Route traffic only when /health/ready is UP.
• Set server-async-bootstrap=false when endpoints must remain closed until initialization finishes.
• Set http-max-queued-requests to bound waiting requests; excess requests receive HTTP 503.

Working method

1. Identify whether the task concerns integration behavior, authentication, an API, an extension, or deployment.
2. Run the relevant breaking-change and security checks above.
3. Open the matching reference file and apply all constraints for that topic.
4. Prefer explicit feature names and exact option keys over assumptions based on older defaults.
5. Test migrations against representative realms, sessions, custom providers, themes, and client token expectations.