diff --git a/docs/documentation/release_notes/topics/26_4_0.adoc b/docs/documentation/release_notes/topics/26_4_0.adoc index e6774ed4a4d..3235310a8ef 100644 --- a/docs/documentation/release_notes/topics/26_4_0.adoc +++ b/docs/documentation/release_notes/topics/26_4_0.adoc @@ -1,51 +1,26 @@ // Release notes should contain only headline-worthy new features, // assuming that people who migrate will read the upgrading guide anyway. -Read on to learn more about each new feature, and https://www.keycloak.org/docs/latest/upgrading/index.html[find additional details in the upgrading guide] if you are upgrading from a previous release of {project_name}. +This release features new capabilities focused on security enhancements, deeper integration, and improved server administration. The highlights of this release are: -= Federated client authentication preview +* Passkeys for seamless, passwordless authentication of users. +* Federated Client Authentication to use SPIFFE or Kubernetes service account tokens for client authentication. +* Simplified deployments across multiple availability zones to boost availability. +* FAPI 2 Final: Keycloak now supports the final specifications of FAPI 2.0 Security Profile and FAPI 2.0 Message Signing. +* DPoP: The OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) is now fully supported. Improvements include the ability to bind only refresh tokens for public clients, and securing all Keycloak endpoints with DPoP tokens. -Identity providers are now able to federate client authentication. This allows clients to authenticate with SPIFFE JWT SVIDs, -Kubernetes service accounts, or tokens issued by a OpenID Connect identity provider. -This feature is currently preview, and expected to become supported in 26.5. +Read on to learn more about each new feature. If you are upgrading from a previous release, https://www.keycloak.org/docs/latest/upgrading/index.html[review also the changes listed in the upgrading guide]. -= Update Email Workflow is now supported += Security and Standards -This feature provides a more secure and consistent flow to update user -emails. Accounts are forced to both re-authenticate and verify their -emails before any account updates. +== Passkeys integration (supported) -For more information, see link:{adminguide_link}#_update-email-workflow[Update Email Workflow]. - -= Passkeys integration is now supported - -This feature integrates passkeys seamlessly in the {project_name} forms using both conditional and modal UIs. To activate the integration in the realm, go to *Authentication*, *Policies*, *Webauthn Passwordless Policy* and switch *Enable Passkeys* to enabled. +Passkeys are now seamlessly integrated in the {project_name} login forms using both conditional and modal UIs. To activate the integration in the realm, go to *Authentication*, *Policies*, *Webauthn Passwordless Policy* and switch *Enable Passkeys* to enabled. For more information, see link:{adminguide_link}#passkeys_server_administration_guide[Passkeys]. -= New conditional authenticator `Conditional - credential` - -The *Conditional - credential* is a new authenticator that checks if a specific credential type has been used (or not used) during the authentication process. This condition is related to the *Passkeys* feature. It is added by {project_name} to the default *browser* flow to skip 2FA in case a passkey was used to log in as the primary credential. - -For more information about conditional flows, see link:{adminguide_link}#conditions-in-conditional-flows[Conditions in conditional flows]. - -= DPoP is now supported - -{project_name} has support for OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP), which was a preview feature since {project_name} 23. Also, the supported version includes some improvements and minor capabilities of the DPoP feature such as the following: - -* Possibility to make just refresh tokens of a public client to be DPoP bound and omit the binding of an access tokens -* All {project_name} endpoints that are secured by bearer token can now handle DPoP tokens. This includes for example admin REST API and account REST API -* Possibility to require the `dpop_jkt` parameter in the OIDC authentication request - -ifeval::[{project_community}==true] -Thanks to -https://github.com/tnorimat[Takashi Norimatsu] and https://github.com/dteleguin[Dmitry Telegin] for their contributions to the DPoP feature. -endif::[] - -For more information, see the link:{adminguide_link}#_dpop-bound-tokens[DPoP section] in the documentation. - -= FAPI 2 Final support +== FAPI 2 Final (supported) {project_name} has support for the latest versions of FAPI 2 specifications. Specifications *FAPI 2.0 Security Profile* and *FAPI 2.0 Message Signing* are already promoted to Final and {project_name} supports them. {project_name} client policies support @@ -59,54 +34,109 @@ endif::[] For more details, see the link:{securing_apps_base_link}/oidc-layers#_fapi-support[{securing_apps_name}]. -= Option to force management interface to use HTTP +== DPoP (supported) -A new option, `http-management-scheme`, may be set to `http` to force the management interface to use HTTP rather than inheriting the HTTPS settings of the main interface. +{project_name} has support for OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP), which was a preview feature since {project_name} 23. Also, the supported version includes some improvements and minor capabilities of the DPoP feature such as the following: -= Option to expose health endpoints on the main HTTP(S) port +* Possibility to make only refresh tokens of a public client to be DPoP bound and omit the binding of an access token. +* All {project_name} endpoints that are secured by bearer token can now handle DPoP tokens. This includes, for example, the Admin REST API and Account REST API. +* Possibility to require the `dpop_jkt` parameter in the OIDC authentication request. -With `health-enabled` set to true, you may set the `http-management-health-enabled` to `false` to indicate that health endpoints should be exposed on the main HTTP(s) port instead of the -management port. When this option is `false` you should block unwanted external traffic to `/health` at your proxy. - -= Additional context information for log messages (preview) - -You can now add context information via the mapped diagnostic context (MDC) to each log message like the realm or the client that initiated the request. -This helps you to track down a warning or error message in the log to a specific caller or environment ifeval::[{project_community}==true] -Thank you to https://github.com/eicki[@eicki] for contributing this. +Thanks to +https://github.com/tnorimat[Takashi Norimatsu] and https://github.com/dteleguin[Dmitry Telegin] for their contributions to the DPoP feature. endif::[] -For more details on this opt-in feature, see https://www.keycloak.org/server/logging[Configuring logging]. +For more information, see the link:{adminguide_link}#_dpop-bound-tokens[DPoP section] in the documentation. -= Ability to specify a `tlsSecret` on the Keycloak CR `ingress` spec +== FIPS 140-2 mode now supports EdDSA -To support basic TLS termination (edge) deployments by the operator, you may now set the Keycloak CR `spec.ingress.tlsSecret` field to a TLS Secret name in the namespace. +With the upgrade to Bouncy Castle 2.1.x, the algorithm EdDSA can now be used. -= HTTP access logging of incoming HTTP requests +== Listing supported OAuth standards on one page -{project_name} supports HTTP access logging to record details of incoming HTTP requests. -While access logs are often used for debugging and traffic analysis, they are also important for security auditing and compliance monitoring. +A new guide lists https://www.keycloak.org/securing-apps/specifications[all implemented OpenID Connect related specifications]. +ifeval::[{project_community}==true] +Thank you to https://github.com/tnorimat[Takashi Norimatsu] for contributing this. +endif::[] -For more information, see https://www.keycloak.org/server/logging[Configuring logging]. += Integration -== Possibility to hide identity providers from the Account Console + +== Federated client authentication (preview) + +Identity providers are now able to federate client authentication. This allows clients to authenticate with SPIFFE JWT SVIDs, +Kubernetes service account tokens, or tokens issued by an OpenID Connect identity provider. + +== Automatic certificate management for SAML clients + +The SAML clients can now be configured to automatically download the signing and encrypting certificates from the SP entity metadata descriptor endpoint. In order to use this new feature, in the client *Settings* tab, section *Signature and Encryption*, configure the *Metadata descriptor URL* option (the URL where the SP metadata information with the certificates is published) and activate *Use metadata descriptor URL*. The certificates will be automatically downloaded and cached in the `public-key-storage` SPI from that URL. +This also allows for seamless rotation of certificates. + +For more information, see link:{adminguide_link}#_client-saml-configuration[Creating a SAML client] in the {adminguide_name}. + +== Serving as an authorization server in MCP + +MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. Using MCP, AI applications can connect to data sources, tools and workflows enabling them to access key information and perform tasks. + +To comply with MCP specification, this version provides its OAuth 2.0 Server Metadata via a well-known URI whose format complies with RFC 8414 OAuth 2.0 Authorization Server Metadata specification. Therefore, Keycloak users can now use Keycloak as an authorization server for MCP. + +The latest MCP specification 2025-06-18 additionally requires support for resource indicators which are currently not implemented in {project_name}. + += Administration + +== Update Email Workflow (supported) + +Users can now update their email addresses in a more secure and consistent flow. Accounts are forced to both re-authenticate and verify their emails before any account updates. + +For more information, see link:{adminguide_link}#_update-email-workflow[Update Email Workflow]. + +ifeval::[{project_community}==true] +This feature is currently preview, and expected to become supported in 26.5. +endif::[] + +== Optional email domain for organizations + +In earlier versions, each organization required at least one email domain, which was a limitation for some scenarios. +Starting with this release, an email domain is optional. +ifeval::[{project_community}==true] +Thank you to https://github.com/SferaDev[Alexis Rico] for contributing this. +endif::[] + +When no domain is specified, organization members will not be validated against domain restrictions during authentication and profile validation. + +== Hiding identity providers from the Account Console You can now control which identity providers appear in the Account Console based on different options using the `Show in Account console` setting. You can choose to show only those linked with a user or hide them completely. For more information, see link:{adminguide_link}#_general-idp-config[General configuration]. -= Email domain for organizations is now optional +== Enforce recovery codes setup after setting up OTP -In earlier versions, each organization required at least one email domain, which was a limitation for some scenarios. -Starting with this release, an email domain is optional. +If you have enabled OTPs and recovery codes as a second factor for authentication, you can configure the OTP required action to ask users to set up recovery codes once they set up an OTP. ifeval::[{project_community}==true] -Thank you to https://github.com/SferaDev[@SferaDev] for contributing this. +Thank you to https://github.com/dasniko[Niko Köbler] for contributing this. endif::[] -When no domain is specified, organization members will not be validated against domain restrictions during authentication and profile validation. +== New conditional authenticator -= Enhancements for single-cluster and multi-cluster setups +The *Conditional - credential* is a new authenticator that checks if a specific credential type has been used (or not used) during the authentication process. This condition is related to the Passkeys feature. It is added by {project_name} to the default browser flow to skip 2FA in case a passkey was used to log in as the primary credential. + +For more information about conditional flows, see link:{adminguide_link}#conditions-in-conditional-flows[Conditions in conditional flows]. + +ifeval::[{project_community}==true] +== Translations managed by Weblate + +The {project_name} distribution now includes 35 community translations, with Kazakh, Azerbaijani and Slovenian added in this release. +Community volunteers now maintain some of the translations in https://hosted.weblate.org/projects/keycloak/[Weblate] to keep them up to date. + +If you want to volunteer to maintain an existing or a new translation via Weblate, you can find the necessary steps in the https://github.com/keycloak/keycloak/blob/main/docs/translation.md[translation guidelines]. +endif::[] + += Configuring and Running + +== Enhancements for single-cluster and multi-cluster setups This release renamed multi-site to multi-cluster. The updated documentation describes @@ -115,36 +145,43 @@ The {project_name} Operator now deploys {project_name} across multiple availabil This change should provide better availability for users who are running {project_name} in Kubernetes clusters that span multiple availability zones. -ifeval::[{project_community}==true] -= Translations managed by Weblate +== Support for additional databases and versions -The {project_name} distribution now includes 35 community translations. With Kazakh, Azerbaijani and Slovenian added in this release. -Community volunteers now maintain some of the translations in https://hosted.weblate.org/projects/keycloak/[Weblate] to keep them up to date. +With this release, we added support for the following new database vendors: -If you want to volunteer to maintain an existing or a new translation via Weblate, you can find the necessary steps in the https://github.com/keycloak/keycloak/blob/main/docs/translation.md[translation guidelines]. -endif::[] +* EnterpriseDB (EDB) Advanced 17.6 +* Azure SQL Database and Azure SQL Managed Instance -= Enforce set up of recovery codes after setting up OTP +Where the previous documentation stated only tested database version, it now states all the supported database versions as well. -If you have enabled OTPs and recovery codes as a second factor for authentication, you can configure the OTP required action to ask users to set up recovery codes once they set up an OTP. -ifeval::[{project_community}==true] -Thank you to https://github.com/dasniko[@dasniko] for contributing this. -endif::[] +== Expose management interface via HTTP -= Supported OAuth standards listed on one page +Previous versions exposed the management endpoint only via HTTPS when the main interface was using HTTPS. -A new guide exists with a list of https://www.keycloak.org/securing-apps/specifications[all implemented OpenID Connect related specifications]. -ifeval::[{project_community}==true] -Thank you to https://github.com/tnorimat[@tnorimat] for contributing this. -endif::[] +Set the new option `http-management-scheme` to `http` to have the management interface use HTTP rather than inheriting the HTTPS settings of the main interface. +This allows monitoring those endpoints in environments where no TLS client is available. -= Automatic certificate management for SAML clients +== Expose health endpoints on the main HTTP(S) port -The SAML clients can now be configured to automatically download the signing and encrypting certificates from the SP entity metadata descriptor endpoint. In order to use this new feature, in the client *Settings* tab, section *Signature and Encryption*, configure the *Metadata descriptor URL* option (the URL where the SP metadata information with the certificates is published) and activate *Use metadata descriptor URL*. The certificates will be automatically downloaded and cached in the `public-key-storage` SPI from that URL. +With `health-enabled` set to true, you may set the `http-management-health-enabled` to `false` to indicate that health endpoints should be exposed on the main HTTP(s) port instead of the +management port. When this option is `false` you should block unwanted external traffic to `/health` at your proxy. -For more information, see link:{adminguide_link}#_client-saml-configuration[Creating a SAML client] in the {adminguide_name}. +This allows using the health endpoints in environments where the load balancer might need access to those ports to direct traffic to the correct nodes. -= Operator creates a ServiceMonitor automatically +== Specify a `tlsSecret` on the Keycloak CR `ingress` spec + +To support basic TLS termination (edge) deployments by the operator, you may now set the Keycloak CR `spec.ingress.tlsSecret` field to a TLS Secret name in the namespace. + +== Additional datasources configuration (supported) + +Some {project_name} use cases like User Federation might require connecting to additional databases. +This was possible only through specifying unsupported raw Quarkus properties in previous {project_name} versions. In this release, there are now dedicated server options for additional datasources. This allows users to leverage additional databases in their extensions in a supported and user-friendly way. + +Read more about it in the link:https://www.keycloak.org/server/db#configure-multiple-datasources[Configure multiple datasources] guide. + += Observability + +== Operator creates a ServiceMonitor automatically The Operator now provisions a `ServiceMonitor` for the management endpoint if metrics are enabled and the `monitoring.coreos.com/v1:ServiceMonitor` Custom Resource Definition is present on the Kubernetes cluster. The @@ -152,36 +189,20 @@ specification of the `ServiceMonitor` takes into account the various management metrics can be scraped without any additional configuration. If you do not want a `ServiceMonitor` to be created, you can disable this by setting `spec.serviceMonitor.enabled: false`. For more details, see the link:{operatorguide_link}[{operatorguide_name}]. -== {project_name} automatically creates the necessary caches on the first startup if they do not exist +== HTTP access logging of incoming HTTP requests -You no longer need to manually create caches in your external Infinispan cluster. +{project_name} supports HTTP access logging to record details of incoming HTTP requests. +While access logs are often used for debugging and traffic analysis, they are also important for security auditing and compliance monitoring. -When using the `multi-site` or `clusterless` features, {project_name} now automatically creates the necessary caches during startup if they do not already exist on the Infinispan server. +For more information, see https://www.keycloak.org/server/logging[Configuring logging]. -Any existing caches, manually created before {project_name} startup, will be preserved, and their configuration will not be modified. +== Showing context information in log messages (preview) -For high availability, you can now easily configure cross-site replication. -Simply set the backup site name (e.g., availability zone) using the following option: +You can now add context information via the mapped diagnostic context (MDC) to each log message like the realm or the client that initiated the request. +This helps you to track down a warning or error message in the log to a specific caller or environment +ifeval::[{project_community}==true] +Thank you to https://github.com/eicki[Björn Eickvonder] for contributing this. +endif::[] -[source,bash] ----- ---cache-remote-backup-sites= ----- +For more details on this opt-in feature, see https://www.keycloak.org/server/logging[Configuring logging]. -When this option is set, Infinispan will automatically replicate the cache data to the specified location.¨ - -= Support for additional databases - -With this release, we added support for the following new database vendors: - -* EnterpriseDB (EDB) Advanced 17.6 -* Azure SQL Database and Azure SQL Managed Instance - -= Additional datasources configuration is supported - -Some {project_name} use cases (like User Federation) might require connecting to additional databases. -This was possible only through specifying unsupported raw Quarkus properties in previous {project_name} versions. In this release, we've refined dedicated server options for additional datasources and promoted them to supported. This allows users to leverage additional databases in their extensions in a supported and user-friendly way. - -Read more about it in the link:https://www.keycloak.org/server/db#configure-multiple-datasources[Configure multiple datasources] guide. - -For the information about the necessary migration from the old configuration to the new one, see the link:{upgradingguide_link}[{upgradingguide_name}]. diff --git a/docs/documentation/upgrading/topics/changes/changes-26_4_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_4_0.adoc index 3b7cd3d6b27..6fd83dd3ce4 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_4_0.adoc +++ b/docs/documentation/upgrading/topics/changes/changes-26_4_0.adoc @@ -29,7 +29,7 @@ See the link:{upgradingguide_link}[{upgradingguide_name}] for details on how to In previous releases, the only possible way to configure additional datasources was using raw Quarkus properties that are generally considered unsupported. At the same time, adding additional datasources was supported which led to unclear situation. -To provide supported and user friendly way to configure additional datasources, we introduced new dedicated server options for that. Configuring additional datasources using the original approach via the Quarkus properties is considered **unsupported** starting with this release. +To provide a supported and user-friendly way to configure additional datasources, we introduced new dedicated server options for that. Configuring additional datasources using the original approach via the Quarkus properties is considered **unsupported** starting with this release. Check the following examples on how to migrate your configuration: @@ -104,6 +104,18 @@ Starting with this release, and when using the original PostgreSQL driver, {proj You can override this behavior by setting your own value for `targetServerType` in the DB URL or additional properties. +=== Bouncy Castle libraries updated to 2.1.x + +If you are running {project_name} in FIPS 140-2 mode, note to update your Bouncy Castle libraries to the versions listed in the release documentation. + +With the upgrade to Bouncy Castle 2.1.x, EdDSA is now supported in FIPS 140-2 mode. + +== Creating remote caches automatically on the first startup + +When using remote caches, {project_name} now automatically creates the necessary caches during startup if they do not already exist on the {jdgserver_name} server. + +For a multi-cluster setup, it is still recommended to create the caches using Cache CRs in advance to verify the correct initialization of the caches and to avoid start-up errors while the caches are present in only one of the sites. + === MySQL and MariaDB wait_timeout validation In order to prevent connections being closed unexpectedly by the database server, it is necessary to ensure that the {project_name} @@ -277,8 +289,8 @@ If you have an SMTP server configured for your realm, perform the following migr === Aligning the count of users with the actual number of users returned from searches When searching for users in the Admin Console or by the User API, the count of users returned from the -`/admin/realms/{realm}/users/count` endpoint is now aligned with the actual number of users returned when executing -searches by `/admin/realms/{realm}/users`. +`+/admin/realms/{realm}/users/count+` endpoint is now aligned with the actual number of users returned when executing +searches by `+/admin/realms/{realm}/users+`. If you are relying on the users count endpoint, make sure to review your clients so that they expect the users count to be aligned with the actual number of users returned from searches. @@ -289,7 +301,7 @@ The Welcome Page creates regular Admin users instead of temporary ones. === Fine-grained admin permissions: new `reset-password` scope for Users -The fine-grained admin permissions (FGAP) feature now includes a new scope: `reset-password`. This scope allows for specific permissions to be granted to administrators to reset a user's password without granting them broader`manage` scope. +The fine-grained admin permissions (FGAP) feature now includes a new scope: `reset-password`. This scope allows for specific permissions to be granted to administrators to reset a user's password without granting them broader `manage` scope. By default, a user with the existing, broader `manage` scope for the `USERS` resource type will implicitly have permission to reset a user's password. The system checks for the explicit `reset-password` scope first. If that permission is not found, it falls back to checking if the administrator has the `manage` scope. This ensures that existing administrators with the `manage` scope continue to have the ability to reset passwords without any changes to their permissions. diff --git a/docs/guides/server/db.adoc b/docs/guides/server/db.adoc index 3546bf6eda1..efece59a822 100644 --- a/docs/guides/server/db.adoc +++ b/docs/guides/server/db.adoc @@ -21,7 +21,7 @@ The server has built-in support for different databases. You can query the avail |MariaDB Server | `mariadb` | ${properties["mariadb.version"]} | 11.8 (LTS), 11.4 (LTS), 10.11 (LTS), 10.6 (LTS) |Microsoft SQL Server | `mssql` | ${properties["mssql.version"]} | 2022, 2019 |MySQL | `mysql` | ${properties["mysql.version"]} | 8.4 (LTS), 8.0 (LTS) -|Oracle Database | `oracle` | ${properties["oracledb.version"]} | 23.x (i.e 23.5+), 19c (19.3+) (*Note: Oracle RAC is also supported if using the same database engine version, e.g 23.5+, 19.3+) +|Oracle Database | `oracle` | ${properties["oracledb.version"]} | 23.x (i.e 23.5+), 19c (19.3+) (*Note:* Oracle RAC is also supported if using the same database engine version, e.g 23.5+, 19.3+) |PostgreSQL | `postgres` | ${properties["postgresql.version"]} | 17.x, 16.x, 15.x, 14.x, 13.x |EnterpriseDB Advanced | `postgres` | ${properties["edb.version"]} | 17 |Amazon Aurora PostgreSQL | `postgres` | ${properties["aurora-postgresql.version"]} | 17.x, 16.x, 15.x