Keycloak 26.5.0 release notes

Highlights

This release features new capabilities for users and administrators of Keycloak. The highlights of this release are:

Workflows to automate administrative tasks and process within a realm.
JWT Authorization Grants, our recommended alternative to external to internal token exchange.
Guide for using Keycloak as an authorization server for Model Context Protocol (MCP) servers.
Authenticating clients with Kubernetes service account tokens to avoid static client secrets.
OpenTelemetry support for metrics and logging, combining all observability information in this popular standard.

Read on to learn more about each new feature. If you are upgrading from a previous release, review also the changes listed in the upgrading guide.

Security and Standards

JWT Authorization Grant (preview)

Keycloak 26.5 introduces a new feature called JWT Authorization Grant, which adds support for RFC 7523 to use external signed JWT assertions to request OAuth 2.0 access tokens.

To accept signed JWT assertions, a trust relationship must be established between the external provider and Keycloak. This trust relationship can be configured through an identity provider in a dedicated section of the OpenID Connect v1.0 identity provider, or through the new JWT Authorization Grant identity provider.

JWT Authorization Grant is recommended as an alternative to External to internal token exchange V1. This feature is in preview, and additional details are available in the dedicated documentation.

Using Keycloak as an authorization server for Model Context Protocol (MCP) servers

Using Keycloak as an authorization server for Model Context Protocol (MCP) servers is becoming popular, so this release ships additional documentation on how to do this.

See Integrating with Model Context Protocol (MCP) for the new guide.

Many thanks to Takashi Norimatsu for the contribution.

CORS enhancements

CORS (Cross Origin Resource Sharing) is a browser security feature that controls how web pages on one domain can request resources from a different domain.

For the OpenID Connect Dynamic Client Registration, you can now specify which CORS headers are allowed via the client registration access policies.

For the overall CORS configuration, you can now allow environment specific headers to be allowed using the SPI option spi-cors--default--allowed-headers.

Logout confirmation page

The client logout configuration now includes an option to show a logout confirmation page. When enabled, users will see a “You are logged out” confirmation page upon successful logout.

Many thanks to Sebastian Łaskawiec for the contribution.

Hiding OpenID Connect scopes from the discovery endpoint

Previously, all scopes of an OpenID Connect client were advertised in the discovery endpoint.

In some situation you might want to avoid it, as the calling client, for example, an MCP server might not support it, or you might want to hide some scopes for preventing their discovery via public APIs.

You can now prevent this by disabling Include in OpenID Provider Metadata.

Administration

Workflows (preview)

Keycloak introduces a new preview feature called Workflows, which allows administrators to automate administrative tasks and process within a realm, introducing a key capability for Identity Governance and Administration (IGA).

For more details, see the Server Administration Guide.

Federated client authentication (preview)

Federated client authentication remains preview due to receiving a number of enhancements and fixes.

There is now preview support to use Kubernetes service accounts tokens as credentials for clients, which avoids static secrets for OpenID Connect clients.

See Kubernetes identity providers in the Server Administration Guide for details.

Organization invitation management

Organization administrators can now manage organization invitations through both the Admin Console and REST API:

View all sent invitations with their current status (Pending, Expired)
Resend pending invitations to recipients
Delete invitation records from the system
Filter invitations by status for easier management

All invitations are now persistently stored in the database, providing better tracking and management capabilities.

The invitation management features are available in the Invitations tab when managing an organization in the Admin Console, and through the Organizations REST API endpoints under /admin/realms/{realm}/orgs/{orgId}/invitations.

New event `USER_SESSION_DELETED`

For each expired user session there is a new user event USER_SESSION_DELETED fired. This event is published approximately 3-10 minutes after the session has expired depending on job scheduling and load on the system. By default, this event is not persisted.

Configuring and Running

Containers for PowerPC 64-bit Little Endian architecture

The containers for both the Keycloak and its operator are not available as well for the PowerPC 64-bit Little Endian (ppc64le) architecture. This is in addition to the existing amd64 and arm64.

We expect this to allow users to optimize their usage of open hardware and power consumption.

Improved server response times

Authentication, user, and client sessions are now created on the respective Keycloak node and avoid extra remote calls to neighbors when reading or writing them to the embedded caches. When you have sticky sessions enabled in your loadbalancer, you will benefit from this feature automatically, and you should see reduced response times when authenticating users.

Expired user sessions are now deleted from the database in small batches, instead of issuing a delete statements that affects the whole table. This should allow for better response times when there are a lot of sessions in the table.

Enhanced HTTP performance (preview)

You can now enable a more efficient way to handle JSON data in the HTTP layer. This change increases throughput by ~5%, stabilizes response times, and reduces system resource usage.

In order to apply it, you need to explicitly enable the feature http-optimized-serializers.

Note	This feature is preview. We gather more feedback about potential issues in this discussion. We appreciate any feedback.

For more details, see the Configuring Keycloak for production guide.

Configure retry behavior for outgoing HTTP requests

Keycloak has now more flexibility how to configure retrying of outgoing HTTP requests. This is useful for handling transient network errors or temporary unavailability of the service where Keycloak needs to send HTTP request. Retry behavior is disabled by default and must be explicitly enabled. More details are available in the Outgoing HTTP requests documentation.

Many thanks to Chance Coleman for the contribution.

Enable/disable features via a single option

You can now enable or disable individual features using the feature-<name> option (like feature-spiffe=enabled).

This provides a more fine-grained way to manage features and eliminates the need to maintain long lists of enabled or disabled features.

The feature-<name> option takes precedence over both features and features-disabled.

For more details, see the Enabling and disabling features guide.

Client certificate lookup compliant with RFC 9440

You can now use a new client certificate lookup provider that is compliant with RFC 9440. This enables native support e.g. for Caddy and other reverse proxies that follow the RFC. For details, navigate to Enabling Client Certificate Lookup section of the documentation.

Running Keycloak as a Windows service

Keycloak can now be installed and run as a Windows service using Apache Commons Daemon (Procrun). The new tools windows-service CLI subcommand simplifies service installation and uninstallation.

The service runs kc.bat start as an external process, ensuring all environment variables and configuration files are respected. This provides seamless integration with the Windows Services management console and enables automatic startup on system boot without requiring a user to be logged on.

For more information, see the Running Keycloak as a Windows Service guide.

Observability

OpenTelemetry enhancements

OpenTelemetry Logs (preview)

Keycloak now supports exporting logs to OpenTelemetry collectors, enabling centralized log management. This preview feature allows you to export Keycloak logs to any OpenTelemetry-compatible backend and use the same OpenTelemetry collector for logs, metrics and traces.

For more details, see the Centralize your observability stack with OpenTelemetry guide.

OpenTelemetry Metrics (experimental)

Keycloak now provides the experimental support for exporting metrics to OpenTelemetry collectors by using the Micrometer-to-OpenTelemetry bridge. This experimental feature allows you to export Keycloak metrics to any OpenTelemetry-compatible backend and use the same OpenTelemetry collector for logs, metrics and traces.

For more details, see the Centralize your observability stack with OpenTelemetry guide.

Export traces with custom request headers

It is now possible to set request headers for exporting traces via OpenTelemetry Protocol (OTLP). It is mainly useful for providing tokens in the request.

You can specify these headers via the tracing-header-<header> wildcard option, accepting any custom header name.

For more details, see the Root cause analysis with tracing guide.

MDC Logging feature (supported)

The log-mdc:v1 feature has been promoted from a preview feature to a supported feature.

MDC enables Keycloak to enrich log entries with contextual information such as realm, client, user ID and IP address, significantly improving debugging and observability.

For more details, see the Adding context for log messages guide.

Upgrading

Before upgrading refer to the migration guide for a complete list of changes.

All resolved issues

Deprecated features

#44121 Deprecate Fine-Grained Admin Permissions v1 admin/fine-grained-permissions

Removed features

#42905 Remove PostgreSQL 13.x support

New features

#20761 Support Caddy as a Reverse Proxy Provider for Client Certificate Authentication core
#37704 Support for running Keycloak as a Windows Service
#38809 Feature Request: Track Pending Organization Invitations in Keycloak Admin Console
#39221 Admin API v2: Blueprint
#41261 OpenTelemetry Support observability
#42482 Possibility to backchannel logout the clients belonging to a specific user session
#42912 Containers for ppc64le
#43020 Secure Client-Initiated Renegotiation - disable by default dist/quarkus
#43106 Expose scheduled tasks and start time
#44312 Add support to use `kcw` with remote test server test-framework
#44458 Expose a configuration option to always display a logout confirmation screen

Enhancements

#8863 Add CORS support to OIDC dynamic client registration endpoints
#10388 Allow to hide client scopes from scopes_supported in discovery endpoint
#12682 Allow CORS Access-Control-Allow-Headers customization core
#14509 Allow configuration for SMTP timeouts via configuration
#15502 Ability to remove offline_access tokens from the Account Management client and/or Admin interface core
#17268 [KC 20+] Obsolete/wrong documentation about service accounts?
#22938 Fine-grained admin permission client manage does not work for an Authorization enabled client admin/fine-grained-permissions
#33009 Delete Client and role's admin event doesn't have representation while other delete entities have the representation admin/ui
#33146 Prevent users configuring max-count=-1 for caches with a default upper-bound infinispan
#35836 SMTP Timeout Override
#38843 Set `automountServiceAccountToken: false` on Keycloak pods operator
#39881 Picture of the token-exchange flow in the documentation docs
#40799 Provide a way to add custom labels to Realm Import job of Keycloak operator
#41006 [OTel] Micrometer to OpenTelemetry bridge support for metrics observability
#41007 Including OTLP headers for authorization
#41019 Validate client session session timeout and lifetime settings on edit authentication
#41205 Make MDC logging supported
#41263 [OTel] Provide general options for telemetry settings observability
#41264 [OTel] Introduce preview support for OpenTelemetry Logs observability
#41425 Add more fields to the Welcome Page
#42124 Add operation to cancel a workflow execution for a resource
#42223 Create a LocalCacheProvider SPI
#42386 [RLM] Review the action execution thread model
#42401 Add configurable retry logic for OCSP certificate validation checks core
#42445 Default to log color enabled
#42446 Make picocli auto color match the quarkus logic
#42618 [RLM] - Allow updating workflow conditions
#42644 No longer able to set a Keycloak Admin Client timeout admin/client-js
#42687 [RLM] - Ability to define workflows with YAML
#42694 Workflows: review test coverage workflows
#42695 Workflows: Add OpenAPI annotations to all API methods
#42696 [RLM] Review implemented conditions and add toPredicate implementation
#42704 SELECT COUNT(*) FROM called multiple times for an index creation core
#42715 incorrect flow with login_hint specified for user in org email domain organizations
#42776 Session cache affinity
#42835 Make API endpoint linkable in documentation docs
#42910 [RLM] - Restarting a workflow for a resource based on the step chain workflows
#42911 [RLM] - Canceling workflows for a given resources when a new event is triggered
#42913 [RLM] - Allow using time-based tokens when setting fields that expect a period or time
#42917 Chore: Add missing translations for Korean (ko)
#42945 [PERF] Jackson reflection-free serialization/deserialization dist/quarkus
#42961 [RLM] - Cache expressions using as a component note
#42990 Hide read-only email attribute in update profile context with update email enabled user-profile
#42991 Final review and update for UPDATE_EMAIL documentation docs
#43015 Log FIPS provider using info debug level
#43076 Add rate limiter for sending verification emails in context of update email
#43125 Divide logging guide to sub-guides for every log handler observability
#43137 [RLM] Review naming of events to be in the past tense workflows
#43156 [Docs] Warn users about printing headers in HTTP access logs docs
#43183 Relax CORS policy on credential offer endpoint
#43214 [OID4VC] Ensure authorization_details from PAR requests are properly returned in token responses for conformace tests oid4vc
#43256 Expiry event for user sessions and timely DB removal of sessions
#43351 Make pending email verification attribute removable by admin user-profile
#43357 JDBC_PING should publish its physical address on startup
#43360 Add the user session in the session context when it is validated or created
#43362 Reduce the number entity manager flushes when creating a realm
#43365 When reading events for the database, read them read-only
#43421 All config formatting for list options could be improved
#43450 Workflows UI needs to implement authorization admin/ui
#43456 Run time comparisons in SD-JWT and SD-JWT VP verification with account of possible clock skew
#43466 Picocli refinements
#43509 Role authorization for workflows. admin/api
#43512 Export default routes from npm UI packages
#43536 Remove need to specify workflow condition parameter in double quotes workflows
#43537 Fix inconsistencies in workflow condition evaluation workflows
#43538 Ensure delete-user step doesn't trigger removal of federated user from federation provider workflows
#43541 Ability to enable/disable feature via single property
#43559 Add validation for Workflwow, Condition and Steps fields workflows
#43604 Warn or error on duplicate options dist/quarkus
#43611 Allow non-optimized start to run without a separate vm launch
#43643 Upgrade to Quarkus 3.27.1 dist/quarkus
#43650 SPIFFE should support OIDC JWK endpoint
#43660 Add operation to retrieve the workflows that are currently active for a resource workflows
#43661 Allow groups to be referenced by path in workflow conditions workflows
#43665 Workflows UI must allow for definition of workflows using YAML admin/ui
#43666 Admin client should be able to handle YAML payloads for workflows workflows
#43694 Avoid using UserCredentialManager from user storage extensions
#43715 Provide a way to evaluate event properties when matching events to workflows workflows
#43777 Add missing secret warning status
#43801 [OID4VCI] Handling KeyAttestationRequired properly oid4vc
#43802 Add autofocus property to "Sign in with passkey" button in keycloak.v2 login theme.
#43843 [Login UI v2] Configurable Password Visibility-Toggle Icons
#43912 Store workflows YAML definition as a blob workflows
#43931 Downscoping for standard token exchange token-exchange/standard
#44005 Improve error message for the HTTPS material loading observability
#44164 Add pagination and search by name capabilities to the workflows endpoint workflows
#44183 Allow UI to retrieve Workflow definitions without their ids workflows
#44266 Provide additional benchmarks for more than 100k users
#44274 Keycloak compatibility with PostgreSQL 18
#44296 Avoid un-escaped strings in the login templates for HTML entities login/ui
#44396 Ignore null values when serializing workflows using YAML workflows
#44494 Support EDB 18
#44500 HttpClient provider should allow connectionRequestTimeout to be settable
#44518 Disable state transfer for session caches when persistent sessions are enabled
#44548 Add MariaDB to MySQL description and specify SQL to support UTF-8
#44571 MCP Documentation for 26.5
#44611 Document recommended transaction isolation level for MS SQL in guides and warn if wrong level is detected on startup
#44621 [OID4VCI] Realign naming of attribute configuring algorithms for credential signing oid4vc
#44634 Enhance health check docs
#44645 Improve workflow concurrency settings to allow cancelling a workflow based on an event workflows
#44708 Improvements to the notify step workflows
#44736 Fix OID4VCI Wallet Interoperability Issues (Draft 15 Compatibility & Metadata Compliance) oid4vc
#44753 Avoid using HTML in backend messages in the login theme
#44787 Avoid flushing user information in batch mode
#44789 Allow restarting the step chain at a specific position workflows
#44801 Infinispan: LoginFailures entries should expire
#44842 Publish an event for logging out a single session or all sessions or all sessions via the Account Console events
#44843 Publish an event when the UserSessionLImitsAuthenticator terminates an older session events
#44865 Allow running scheduled workflows workflows
#44890 Update the Quarkus README for better clarity
#44910 Validate client session timeout and lifetime settings on realm settings edit
#44915 Add Basque (eu) translation support for Keycloak UI
#44936 Support running test methods on the server side
#45070 ServiceMonitor is not created by keycloak operator docs

Bugs

#26374 Workflow failure: Quarkus IT - FipsDistTest#testUnsupportedHttpsPkcs12KeyStoreInStrictMode ci
#30939 Vulnerability in brute force detection settings authentication
#31401 Kcadm.sh: (Better) Error messages on 302 redirect responses
#34868 [Jenkins Operator CI] - Test remote - ClusteringTest on OpenShift ci
#38438 Avoid 'duplicated mappers' Quarkus message for kc.dir dist/quarkus
#38506 keycloak-test-framework-bom manages more dependencies than intended test-framework
#38991 [Test framework] Embedded server -> dependency download error when no version is specified test-framework
#39660 Failed shouldPreventPathFileSeparatorInVaultSecretId test on Windows testsuite
#40058 [FGAP] Make additional rest endpoints respect permissions admin/fine-grained-permissions
#40712 Authorization -> Evaluate: always returns "No search results" authorization-services
#40756 Wrong dependency registering in the testsuite testsuite
#40965 Group permission denies to view user admin/fine-grained-permissions
#40990 Fallback to English translations for unknown locale despite German being the realm default translations
#41270 Cannot save new attribute group admin/ui
#41271 Changing user profile attribute results in an error everytime admin/ui
#41292 openid-connect flow is missing response type on language change authentication
#42000 Incorrect logic of getArray() in ComponentModelScope core
#42166 [Keycloak CI - Store MSSQL] GroupTest.createMultiDeleteMultiReadMulti:157 testsuite
#42225 Slow initial GET /admin/realms/{realm}/users with cache enabled and large max parameter admin/api
#42470 UserStorageProviderModel parameter in ImportSynchronization.sync() method contains stale configuration data core
#42541 Searching by non-searchable attributes returns all clients core
#42552 Missing license field and miscellaneous fields in NPM packages admin/ui
#42565 Standard Token Exchange: chain of exchanges eventually fails token-exchange
#42588 Key Type is not EC: ECDSA oidc
#42601 Flaky test: org.keycloak.testsuite.broker.KcOidcBrokerTest#testPostBrokerLoginFlowWithOTP ci
#42676 Security Defenses realm settings lost when switching between Headers and Brute Force Detection tabs (v25+) admin/ui
#42794 [Windows] Make TrustedHostClientRegistrationPolicyTest Robust to Canonical Hostname localhost testsuite
#42795 [Windows] Stabilize ResourceLoaderTest testsuite
#42851 Group description missing on partial import import-export
#42907 Race condition in authorization service leads to NullPointerException when evaluating permissions during concurrent resource deletion authorization-services
#42914 Make sure TestEventsListenerProvider does not reuse the events in memory testsuite
#42960 KC_VERBOSE is not honored for a fast start dist/quarkus
#42971 create clients without required value admin/ui
#43022 Incorrect Basic Auth encoding for OIDC IDentity Provider when Client ID contains colon identity-brokering
#43034 Saving Client “Advanced” sets Request Object signature/encryption attributes to “any” even when not changed oidc
#43042 Avoid NPE in FederatedJWTClientAuthenticator when checking for supported assertion types core
#43061 Option description stuck with link admin/ui
#43070 Update email page with pending verification email messages prefilled with old email user-profile
#43080 Fix punctuation for deleteConfirmGroup_one message admin/ui
#43082 ExternalLinksTest is broken due to missing path parameters docs
#43084 Fix anchors in the documentation docs
#43087 "Service accounts roles" should be "Service account roles" translations
#43091 Duplicate Email Fields on Temporarily Locked Out Sign In With Organization Identity-First Login login/ui
#43096 keycloak-operator 26.4.0 missing clusterrole permissions docs
#43104 Release notes fix for update email docs
#43160 Regression in DEBUG_PORT handling since 26.4.0 – host binding (*:port / 0.0.0.0:port) no longer works dist/quarkus
#43161 Restarting an user session broken for persistent sessions infinispan
#43164 Keycloak docs state that only TLSv

These notes run past the length kept in the archive. The rest is on the publisher’s page.