November 22 2024
+ + +To download the release go to Keycloak downloads.
+ +In this release, admin events might hold additional details about the context when the event is fired. When upgrading you should
+expect the database schema being updated to add a new column DETAILS_JSON to the ADMIN_EVENT_ENTITY table.
Potential vulnerable configurations have been identified in the X.509 client certificate lookup when using a reverse proxy. +Additional configuration steps might be required depending on your current configuration. Make sure to review the updated +reverse proxy guide if you have configured +the client certificate lookup via a proxy header.
+Before upgrading refer to the migration guide for a complete list of changes.
+ +| Keycloak | +Distribution powered by Quarkus | ++ + + + ZIP + +(sha1) + + + + + TAR.GZ + +(sha1) + + | +
| Container image | +For Docker, Podman, Kubernetes and OpenShift | ++ + + Quay + + | +
| Operator | +For Kubernetes and OpenShift | ++ + + OperatorHub + + | +
| Third-party licenses | +License and source code information for third-party dependencies | ++ + + HTML + + | +
| Quickstarts distribution | ++ + + + + GitHub + + + + + + ZIP + + + | +
docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.5 start-devdocker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.6 start-devpodman run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.5 start-devpodman run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.6 start-devDownload and extract keycloak-26.0.5.zip +
Download and extract keycloak-26.0.6.zip from the Keycloak website.
After extracting this file, you should have a directory that is named keycloak-26.0.5.
After extracting this file, you should have a directory that is named keycloak-26.0.6.
From a terminal, open the keycloak-26.0.5 directory.
From a terminal, open the keycloak-26.0.6 directory.
Enter the following command:
diff --git a/high-availability/bblocks-multi-site.html b/high-availability/bblocks-multi-site.html index 263758edbc94..90aaf42789da 100644 --- a/high-availability/bblocks-multi-site.html +++ b/high-availability/bblocks-multi-site.html @@ -118,7 +118,7 @@Not considered: Two regions on the same or different continents, as it would increase the latency and the likelihood of network failures. -Synchronous replication of databases as a services with Aurora Regional Deployments on AWS is only available within the same region.
+Synchronous replication of databases as services with Aurora Regional Deployments on AWS is only available within the same region.A load balancer which checks the /lb-check URL of the Keycloak deployment in each site, plus an automation to detect Infinispan connectivity problems between the two sites.
Blueprint: Deploy an AWS Global Accelerator loadbalancer together with Deploy an AWS Lambda to disable a non-responding site.
+Blueprint: Deploy an AWS Global Accelerator load balancer together with Deploy an AWS Lambda to disable a non-responding site.
The vCPU requirement is given as a range, as with an increased CPU saturation on the database host the CPU usage per request decreased while the response times increase. A lower CPU quota on the database can lead to slower response times during peak loads. Choose a larger CPU quota if fast response times during peak loads are critical. See below for an example.
+The vCPU requirement is given as a range, as with an increased CPU saturation on the database host the CPU usage per request decreases while the response times increase. A lower CPU quota on the database can lead to slower response times during peak loads. Choose a larger CPU quota if fast response times during peak loads are critical. See below for an example.
db.t4g.large instance or a 4 vCPU db.t4g.xlarge instance.
-A 2 vCPU db.t4g.large would be more cost-effective if the response times are allowed be higher during peak usage.
+A 2 vCPU db.t4g.large would be more cost-effective if the response times are allowed to be higher during peak usage.
In our tests, the median response time for a login and a token refresh increased by up to 120 ms once the CPU saturation reached 90% on a 2 vCPU db.t4g.large instance given this scenario.
For faster response times during peak usage, consider a 4 vCPU db.t4g.xlarge instance for this scenario.)
OpenShift 4.16.x deployed on AWS via ROSA.
Machinepool with m5.4xlarge instances.
Machine pool with m5.2xlarge instances.
Keycloak deployed with the Operator and 3 pods in a high-availability setup with two sites in active/active mode.
OpenShift’s reverse proxy running in passthrough mode were the TLS connection of the client is terminated at the Pod.
+OpenShift’s reverse proxy runs in the passthrough mode where the TLS connection of the client is terminated at the Pod.
Database Amazon Aurora PostgreSQL in a multi-AZ setup.
@@ -313,7 +313,7 @@All authentication sessions in distributed caches as per default, with two owners per entries, allowing one failing Pod without losing data.
All user and client sessions are stored in the database and are not cached in-memory as this was tested a multi-site setup. +
All user and client sessions are stored in the database and are not cached in-memory as this was tested in a multi-site setup. Expect a slightly higher performance for single-site setups as a fixed number of user and client sessions will be cached.
Keycloak node
Multiple Keycloak instances run in each site. If one instance fails some incoming requests might receive an error message or are delayed for some seconds.
Multiple Keycloak instances run on each site. If one instance fails some incoming requests might receive an error message or are delayed for some seconds.
No data loss
Less than 30 seconds
The number of JGroup threads is 200 by default.
-While it can be configured using the property Java system property jgroups.thread_pool.max_threads, we advise keeping it at this value.
+While it can be configured using the Java system property jgroups.thread_pool.max_threads, we advise keeping it at this value.
As shown in experiments, the total number of Quarkus worker threads in the cluster must not exceed the number of threads in the JGroup thread pool of 200 in each node to avoid deadlocks in the JGroups communication.
Given a Keycloak cluster with four Pods, each Pod should then have 50 Quarkus worker threads.
Use the Keycloak configuration option http-pool-max-threads to configure the maximum number of Quarkus worker threads.
Keycloak’s liveness probe is non-blocking to avoid a restart of a Pod under a high load.
The overall health probe and the readiness can probe in some cases block to check the connection to the database, so they might fail under a high load. +
The overall health probe and the readiness probe can in some cases block to check the connection to the database, so they might fail under a high load. Due to this, a Pod can become non-ready under a high load.
This guide explains how to resolve a split-brain scenarios between two sites in a multi-site deployment. +
This guide explains how to resolve split-brain scenarios between two sites in a multi-site deployment. It also disables replication if one site fails, so the other site can continue to serve requests.
In the event of a network communication failure between sites in a multi-site deployment, it is no longer possible for the two sites to continue to replicate data between them. +
In the event of a network communication failure between sites in a multi-site deployment, it is no longer possible for the two sites to continue to replicate the data between them.
The Infinispan is configured with a FAIL failure policy, which ensures consistency over availability. Consequently, all user requests are served with an error message until the failure is resolved, either by restoring the network connection or by disabling cross-site replication.
In such scenarios, a quorum is commonly used to determine which sites are marked as online or offline. However, as multi-site deployments only consist of two sites, this is not possible. -Instead, we leverage “fencing” to ensure that when one of the sites is unable to connect to the other site, only one site remains in the loadbalancer configuration, and hence only this site is able to serve subsequent users requests.
+Instead, we leverage “fencing” to ensure that when one of the sites is unable to connect to the other site, only one site remains in the load balancer configuration, and hence only this site is able to serve subsequent users requests.In addition to the loadbalancer configuration, the fencing procedure disables replication between the two Infinispan clusters to allow serving user requests from the site that remains in the loadbalancer configuration. +
In addition to the load balancer configuration, the fencing procedure disables replication between the two Infinispan clusters to allow serving user requests from the site that remains in the load balancer configuration. As a result, the sites will be out-of-sync once the replication has been disabled.
In a true split-brain scenario, where both sites are still up but network communication is down, it is possible that both sites will trigger the webhook simultaneously. We guard against this by ensuring that only a single Lambda instance can be executed at a given time. -The logic in the AWS Lambda ensures that always one site entry remains in the loadbalancer configuration.
+The logic in the AWS Lambda ensures that always one site entry remains in the load balancer configuration.AWS CLI Installed
AWS Global Accelerator loadbalancer
+AWS Global Accelerator load balancer
jq tool installed
To ensure user requests are routed to each Keycloak site we need to utilise a loadbalancer. To prevent issues with +
To ensure user requests are routed to each Keycloak site we need to utilise a load balancer. To prevent issues with DNS caching on the client-side, the implementation should use a static IP address that remains the same when routing clients to both availability-zones.
In this guide we describe how to route all Keycloak client requests via an AWS Global Accelerator loadbalancer. +
In this guide we describe how to route all Keycloak client requests via an AWS Global Accelerator load balancer. In the event of a Keycloak site failing, the Accelerator ensures that all client requests are routed to the remaining healthy site. If both sites are marked as unhealthy, then the Accelerator will “fail-open” and forward requests to a site chosen at random.
@@ -160,7 +160,7 @@Login to the ROSA cluster
Create a Kubernetes loadbalancer service
+Create a Kubernetes load balancer service
Optional: Configure your custom domain
If you are using a custom domain, pointed your custom domain to the AWS Global Loadbalancer by configuring an Alias or CNAME in your custom domain.
+If you are using a custom domain, pointed your custom domain to the AWS Global Load Balancer by configuring an Alias or CNAME in your custom domain.
To ensure that request forwarding works as expected, it is necessary for the Keycloak CR to specify the hostname through
which clients will access the Keycloak instances. This can either be the DualStackDnsName or DnsName hostname associated
-with the Global Accelerator. If you are using a custom domain and pointed your custom domain to the AWS Global Loadbalancer, use your custom domain here.
The transaction.locking: PESSIMISTIC is the only supported locking mode; OPTIMISTIC is not recommended due to its network costs.
-The same settings also prevent that one site it updated while the other site is unreachable.
The backup.strategy: SYNC ensures the data is visible and stored in the other site when the Keycloak request is completed.
Now that an Infinispan server is running, here are the relevant Keycloak CR changes necessary to connect it to Keycloak. These changes will be required in the Deploy Keycloak for HA with the Keycloak Operator guide.
+Now that the Infinispan server is running, here are the relevant Keycloak CR changes necessary to connect it to Keycloak. These changes will be required in the Deploy Keycloak for HA with the Keycloak Operator guide.
All the memory, resource and database configurations are skipped from the CR below as they have been described in Deploy Keycloak for HA with the Keycloak Operator guide already. +
All the memory, resource and database configurations are skipped from the CR below as they have been described in the Deploy Keycloak for HA with the Keycloak Operator guide already. Administrators should leave those configurations untouched.
11222.11222.
Deploy Keycloak for HA with the Keycloak Operator
Deploy an AWS Lambda to disable a non-responding site
diff --git a/high-availability/operate-site-offline.html b/high-availability/operate-site-offline.html index d4b51126503f..786e9cd79189 100644 --- a/high-availability/operate-site-offline.html +++ b/high-availability/operate-site-offline.html @@ -77,7 +77,7 @@During the deployment lifecycle it might be required that one of the sites is temporarily taken offline for maintenance or to allow for software upgrades. To ensure that no user requests are routed to the site requiring -maintenance, it is necessary for the site to be removed from your loadbalancer configuration.
+maintenance, it is necessary for the site to be removed from your load balancer configuration.Follow these steps to remove a site from the loadbalancer so that no traffic can be routed to it.
+Follow these steps to remove a site from the load balancer so that no traffic can be routed to it.
docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.5 start-devdocker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.6 start-devpodman run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.5 start-devpodman run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.6 start-devDownload and extract keycloak-26.0.5.zip +
Download and extract keycloak-26.0.6.zip from the Keycloak website.
After extracting this file, you should have a directory that is named keycloak-26.0.5.
After extracting this file, you should have a directory that is named keycloak-26.0.6.
From a terminal, open the keycloak-26.0.5 directory.
From a terminal, open the keycloak-26.0.6 directory.
Enter the following command:
diff --git a/nightly/operator/installation.html b/nightly/operator/installation.html index 543a66697a0d..f9a55dfa05dd 100644 --- a/nightly/operator/installation.html +++ b/nightly/operator/installation.html @@ -157,8 +157,8 @@Install the CRDs by entering the following commands:
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.5/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
-kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.5/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.ymlkubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.6/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
+kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.6/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.ymlInstall the Keycloak Operator deployment by entering the following command:
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.5/kubernetes/kubernetes.ymlkubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.6/kubernetes/kubernetes.ymlThis CR should be created in the same namespace as the Keycloak Deployment CR, defined in the field keycloakCRName.
-The realm field accepts a full RealmRepresentation.
realm field accepts a full RealmRepresentation.
The recommended way to obtain a RealmRepresentation is by leveraging the export functionality Importing and Exporting Realms.
If you are installing from a zip file then by default there will be an install root directory of keycloak-26.0.5, which can be created anywhere you choose on your filesystem.
If you are installing from a zip file then by default there will be an install root directory of keycloak-26.0.6, which can be created anywhere you choose on your filesystem.
/opt/keycloak is the root install location for the server in all containerized usage shown for Keycloak including Running Keycloak in a container, Docker, Podman, Kubernetes, and OpenShift.
Install the CRDs by entering the following commands:
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.5/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
-kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.5/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.ymlkubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.6/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
+kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.6/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.ymlInstall the Keycloak Operator deployment by entering the following command:
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.5/kubernetes/kubernetes.ymlkubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.0.6/kubernetes/kubernetes.ymlThis CR should be created in the same namespace as the Keycloak Deployment CR, defined in the field keycloakCRName.
-The realm field accepts a full RealmRepresentation.
realm field accepts a full RealmRepresentation.
The recommended way to obtain a RealmRepresentation is by leveraging the export functionality Importing and Exporting Realms.
Keycloak comes with a client-side JavaScript library called keycloak-js that can be used to secure web applications. The adapter also comes with built-in support for Cordova applications.
Keycloak comes with a client-side JavaScript library called keycloak-js that can be used to secure web applications. The adapter also comes with built-in support for Cordova applications.
+The adapter uses OpenID Connect protocol under the covers. You can take a look at the Secure applications and services with OpenID Connect guide for the more generic information about OpenID Connect endpoints and capabilities.
Keycloak provides a Node.js adapter built on top of Connect to protect server-side JavaScript apps - the goal was to be flexible enough to integrate with frameworks like Express.js.
+Keycloak provides a Node.js adapter built on top of Connect to protect server-side JavaScript apps - the goal was to be flexible enough to integrate with frameworks like Express.js. +The adapter uses OpenID Connect protocol under the covers. You can take a look at the Secure applications and services with OpenID Connect guide for the more generic information about OpenID Connect endpoints and capabilities.
The library can be downloaded directly from Keycloak organization and the source is available at diff --git a/securing-apps/oidc-layers.html b/securing-apps/oidc-layers.html index f77d85d655bf..fe9e98222d63 100644 --- a/securing-apps/oidc-layers.html +++ b/securing-apps/oidc-layers.html @@ -72,7 +72,7 @@
As a fully-compliant OpenID Connect Provider implementation, Keycloak exposes a set of endpoints that applications @@ -206,7 +206,7 @@
The dynamic client registration endpoint is used to dynamically register clients.
For more details, see the Client registration service guide and the +
For more details, see the <@links.securingapps id="client-registration" /> guide and the OpenID Connect Dynamic Client Registration specification.
If you are installing from a zip file then by default there will be an install root directory of keycloak-26.0.5, which can be created anywhere you choose on your filesystem.
If you are installing from a zip file then by default there will be an install root directory of keycloak-26.0.6, which can be created anywhere you choose on your filesystem.
/opt/keycloak is the root install location for the server in all containerized usage shown for Keycloak including Running Keycloak in a container, Docker, Podman, {links_getting-started_getting-started-kubernetes_name}, and OpenShift.
/opt/keycloak is the root install location for the server in all containerized usage shown for Keycloak including Running Keycloak in a container, Docker, Podman, Kubernetes, and OpenShift.
-in the rest of documentation relative paths are understood to be relative to the install root - e.g. conf/file.xml means <install root>/conf/file.xml
+In the rest of the documentation, relative paths are understood to be relative to the install root - for example, conf/file.xml means <install root>/conf/file.xml
|
From this point, it is beneficial if load balancer forwards all the next requests to the node2 as this is the node, who is owner of the authentication session with ID 123 and hence Infinispan can lookup this session locally. After authentication is finished, the authentication session is converted to user session, which will be also saved on node2 because it has same ID 123 .
The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to sticky over the AUTH_SESSION_ID cookie. How exactly do this is dependent on your loadbalancer.
+The sticky session is not mandatory for the cluster setup, however it is good for performance for the reasons mentioned above. You need to configure your loadbalancer to stick over the AUTH_SESSION_ID cookie. The appropriate procedure to make this change depends on your loadbalancer.
If your proxy supports session affinity without processing cookies from backend nodes, you should set the spi-sticky-session-encoder-infinispan-should-attach-route option
@@ -349,6 +349,51 @@
When the proxy is configured as a TLS termination proxy the client certificate information can be forwarded to the server through specific HTTP request headers and then used to authenticate clients. You are able to configure how the server is going to retrieve client certificate information depending on the proxy you are using.
| + + | +
+
+
+Client certificate lookup via a proxy header for X.509 authentication is considered security-sensitive. If misconfigured, a forged client certificate header can be used for authentication. +Extra precautions need to be taken to ensure that the client certificate information can be trusted when passed via a proxy header. +
+
+
|
+
The server supports some of the most commons TLS termination proxies such as:
To process the secret correctly, you double all underscores in the <realmname> or the <secretname>, separated by a single underscore.
-Realm Name: sso_realm
Desired Name: ldap_credential
Resulting file Name:
-sso__realm_ldap__credential-
Note the doubled underscores between sso and realm and also between ldap and credential.
-To process the secret correctly, you double all underscores in the <secretname>. When REALM_UNDERSCORE_KEY key resolver is used, underscores in <realmname> are also doubled and <secretname> and <realmname> is separated by a single underscore.
Realm Name: sso_realm
Desired Name: ldap_credential
Resulting file name:
+sso__realm_ldap__credential+
Note the doubled underscores between sso and realm and also between ldap and credential.
+To learn more about key resolvers, see Key resolvers section in the Server Administration guide.
+