From 08a0862369e4adce740ad4dec1ba1faaa3f071b5 Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Thu, 7 Apr 2016 09:36:34 +0200 Subject: [PATCH] KEYCLOAK-2763 Document requirement to use a secure private network for clustering --- .../reference/en/en-US/modules/clustering.xml | 83 ++++++++----------- 1 file changed, 36 insertions(+), 47 deletions(-) diff --git a/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml b/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml index cb36fc4c09..fc9cc558c8 100755 --- a/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml +++ b/docbook/auth-server-docs/reference/en/en-US/modules/clustering.xml @@ -58,13 +58,13 @@ point of failure you may also want to deploy your database to a cluster.
- DB lock - Note that Keycloak supports concurrent startup by more cluster nodes at the same. This is ensured by DB lock, which prevents that some - startup actions (migrating database from previous version, importing realms at startup, initial bootstrap of admin user) are always executed just by one - cluster node at a time and other cluster nodes need to wait until the current node finishes startup actions and release the DB lock. + Migration lock + + Keycloak locks the database during startup. This guarantees that only startup actions like migration and importing realms are not executed + concurrently by multiple nodes. - By default, the maximum timeout for lock is 900 seconds, so in case that second node is not able to acquire the lock within 900 seconds, it fails to start. + By default, the maximum timeout for lock is 900 seconds. If a node is unable to acquire the lock within 900 seconds, it fails to start. The lock checking is done every 2 seconds by default. Typically you won't need to increase/decrease the default value, but just in case it's possible to configure it in standalone/configuration/keycloak-server.json: @@ -89,35 +89,33 @@ For realm and users Keycloak uses a invalidation cache. An invalidation cache doesn't share any data, but simply - removes stale data from remote caches and makes sure all nodes re-load data from the database when it is changed. This reduces network traffic, as well as preventing sensitive data (such as - realm keys and password hashes) from being sent between the nodes. + removes stale data from remote caches and makes sure all nodes re-load data from the database when it is changed. This reduces network traffic, + as well as preventing sensitive data (such as realm keys and password hashes) from being transmitted. - User sessions and login failures supports either distributed caches or fully replicated caches. We recommend using a distributed - cache. A distributed - cache splits user sessions into segments where each node holds one or more segment. It is possible + User sessions and login failures supports either distributed caches or fully replicated caches. The default is a distributed + cache. A distributed cache splits user sessions into segments where each node holds one or more segment. It is possible to replicate each segment to multiple nodes, but this is not strictly necessary since the failure of a node - will only result in users having to log in again. If you need to prevent node failures from requiring users to - log in again, set the owners attribute to 2 or more for the sessions cache + will only result in users having to re-authenticate. If you need to prevent node failures from requiring users to + re-authenticate, set the owners attribute to 2 or more for the sessions cache of infinispan/Keycloak container as described below. - The infinispan container is set by default in standalone/configuration/keycloak-server.json: - -"connectionsInfinispan": { - "default" : { - "cacheContainer" : "java:jboss/infinispan/Keycloak" - } -} - + For cluster configuration edit the configuration of infinispan/Keycloak container in standalone/configuration/standalone-ha.xml. - As you can see in this file, the realmCache, userCache and userSession providers are configured to use infinispan by default, which applies for both cluster and non-cluster environment. +
+ +
+ Secure Private Network - For non-cluster configuration (server executed with standalone.xml ) is the infinispan container infinispan/Keycloak just uses local infinispan caches for realms, users and userSessions. + Best practice is to put intra-cluster traffic on a separate network from the network handling user request. This is both for performance reasons as + well as reducing the risk of exposing clustering to unwanted, possibly malevolent, traffic. As this is the best practice there's a separate + network interface to configure the address for clustering. This means that changing the bind address by adding -b <address> + to the startup command will only affect user request. - For cluster configuration, you can edit the configuration of infinispan/Keycloak container in standalone/configuration/standalone-ha.xml (or standalone-keycloak-ha.xml - if you are using overlay or demo distribution) . + To configure bind address for clustering add -bprivate=<private address> to the startup command. As mentioned in the previous + paragraph you should only expose this on a secure private network.
@@ -125,33 +123,24 @@ Start in HA mode To start the server in HA mode, start it with: - # bin/standalone --server-config=standalone-ha.xml - or if you are using overlay or demo distribution with: - # bin/standalone --server-config=standalone-keycloak-ha.xml - - - Alternatively you can copy standalone/config/standalone-ha.xml to standalone/config/standalone.xml - to make it the default server config. + # bin/standalone --server-config=standalone-ha.xml -bpublic=<public address> -bprivate=<private address> + Replace public address with the address used for user request and private address with the address used for + cluster communication.
- Enabling cluster security + Enabling cluster authentication and encryption - By default there's nothing to prevent unauthorized nodes from joining the cluster and sending potentially malicious - messages to the cluster. However, as there's no sensitive data sent there's not much that can be achieved. - For realms and users all that can be done is to send invalidation messages to make nodes load data from the - database more frequently. For user sessions it would be possible to modify existing user sessions, but creating - new sessions would have no affect as they would not be linked to any access tokens. There's not too much that - can be achieved by modifying user sessions. For example it would be possible to prevent sessions from expiring, - by changing the creation time. However, it would for example have no effect adding additional permissions to the - sessions as these are rechecked against the user and application when the token is created or refreshed. + By default anyone that has access to the secure private network is able to join the cluster and could potentially send malicious messages to the + cluster. As mentioned earlier the realm and user caches are invalidation caches so no sensitive information is transmitted. There is also limited + risk with regards to user sessions as even though a malicious node could potentially create a new user session they would need to be able to sign + associated tokens which is not possible without the realm private key. It would be possible to prevent user sessions from expiring and reset + failed login attempts if brute force protection is enabled. - In either case your cluster nodes should be in a private network, with a firewall protecting them from outside - attacks. Ideally isolated from workstations and laptops. You can also enable encryption of cluster messages, - this could for example be useful if you can't isolate cluster nodes from workstations and laptops on your private - network. However, encryption will obviously come at a cost of reduced performance. + If you are not able to fully isolate the network used for clustering communication from potential attackers you may want to enable authentication + and encryption of the cluster. This will have an impact on performance. To enable encryption of cluster messages you first have to create a shared keystore (change the key and store passwords!): @@ -219,9 +208,9 @@ ISPN000094: Received new cluster view: [node1/keycloak|1] (2) [node1/keycloak, n Usually it's best practice to have your cluster nodes on private network without firewall for communication among them. Firewall could be enabled just on public access point to your network instead. If for some reason you still need to have firewall enabled on cluster nodes, you will need to open some ports. Default values are UDP port 55200 and multicast port 45688 - with multicast address 230.0.0.4. Note that you may need more ports opened if you want to enable additional features like diagnostics for your JGroups stack. - Keycloak delegates most of the clustering work to Infinispan/JGroups, so consult EAP or JGroups documentation for more info. + with multicast address 230.0.0.4. Note that you may need more ports opened if you want to enable additional features like diagnostics for your + JGroups stack. Keycloak delegates most of the clustering work to Infinispan/JGroups, so consult EAP or JGroups documentation for more info.
- + \ No newline at end of file