From f702d8f1ff4ee233c256f361d6703ef59321bf64 Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Mon, 6 Oct 2014 13:58:22 +0200 Subject: [PATCH] KEYCLOAK-730 Document clustering --- docbook/reference/en/en-US/master.xml | 2 + .../reference/en/en-US/modules/clustering.xml | 217 ++++++++++++++++++ .../en/en-US/modules/server-installation.xml | 2 +- 3 files changed, 220 insertions(+), 1 deletion(-) create mode 100755 docbook/reference/en/en-US/modules/clustering.xml diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml index 39515eff454..3487d3c537a 100755 --- a/docbook/reference/en/en-US/master.xml +++ b/docbook/reference/en/en-US/master.xml @@ -32,6 +32,7 @@ + ]> @@ -121,6 +122,7 @@ This one is short &ExportImport; &ServerCache; &SecurityVulnerabilities; + &Clustering; &Migration; diff --git a/docbook/reference/en/en-US/modules/clustering.xml b/docbook/reference/en/en-US/modules/clustering.xml new file mode 100755 index 00000000000..613316f09ef --- /dev/null +++ b/docbook/reference/en/en-US/modules/clustering.xml @@ -0,0 +1,217 @@ + + Clustering + + To improve availability and scalability Keycloak can be deployed in a cluster. + + It's fairly straightforward to configure a Keycloak cluster, the steps required are: + + + + Configure a shared database + + + + + Configure Infinispan + + + + + Enable realm and user cache invalidation + + + + + Enable distributed user sessions + + + + + Start in HA mode + + + + + +
+ Configure a shared database + + Keycloak doesn't replicate realms and users, but instead relies on all nodes using the same + database. This can be a relational database or Mongo. To make sure your database doesn't become a single + point of failure you may also want to deploy your database to a cluster. + +
+ +
+ Configure Infinispan + + Keycloak uses Infinispan caches to share information between nodes. + + + 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. This reduces network traffic, as well as preventing sensitive data (such as + realm keys and password hashes) from being sent between the nodes. + + + User sessions supports either distributed caches or fully replicated caches. We recommend using a distributed + cache. + + + To configure the required Infinspan caches open standalone/configuration/standalone-ha.xml and add: + + + + + + + + ... + +]]> + + + + For more advanced options refer to the + Infinispan Subsystem + and + Infinispan + documentation. + + + Next open standalone/configuration/keycloak-server.json and add: + +"connectionsInfinispan": { + "default" : { + "cacheContainer" : "java:jboss/infinispan/Keycloak" + } +} + + +
+ +
+ Enable realm and user cache invalidation + + To reduce number of requests to the database Keycloak caches realm and user data. In cluster mode + Keycloak uses an Infinispan invalidation cache to make sure all nodes re-load data from the database + when it is changed. Using an invalidation cache instead of a replicated cache reduces the network traffic + generated by the cluster, but more importantly prevents sensitive data from being sent. + + + To enable realm and user cache invalidation open keycloak-server.json and change + the realmCache and userCache providers to infinispan: + +"realmCache": { + "provider": "infinispan" +}, + +"userCache": { + "provider": "infinispan" +} + + +
+ +
+ Enable distributed user sessions + + To help distribute the load of user sessions Keycloak uses an Infinispan 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 + (see Configure Infinispan). + + + To enable the Infinispan user sessions provider open keycloak-server.json and change the + userSessions provider to infinispan: + +"userSessions": { + "provider": "infinispan" +} + + +
+ +
+ Start in HA mode + + To start the server in HA mode, start it with: + # bin/standalone --server-config=standalone-ha.xml + + + Alternatively you can copy standalone/config/standalone-ha.xml to standalone/config/standalone.xml + to make it the default server config. + +
+ +
+ Enabling cluster security + + 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 to 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. + + + 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. + + + To enable encryption of cluster messages you first have to create a shared keystore (change the key and store passwords!): + + -storepass \ + -keyalg Blowfish -keysize 56 -keystore defaultStore.keystore -storetype JCEKS +]]> + + + + Copy this keystore to all nodes (for example to standalone/configuration). Then configure JGroups to encrypt all + messages by adding the ENCRYPT protocol to the JGroups sub-system (this should be added after + the pbcast.GMS protocol): + + + + ... + + + + ${jboss.server.config.dir}/defaultStore.keystore + + PASSWORD + PASSWORD + keycloak + + ... + + + ... + + + + ${jboss.server.config.dir}/defaultStore.keystore + + PASSWORD + PASSWORD + keycloak + + ... + + ... + +]]> + + See the JGroups manual for more details. + +
+ + diff --git a/docbook/reference/en/en-US/modules/server-installation.xml b/docbook/reference/en/en-US/modules/server-installation.xml index aadfba845f4..9e595a194de 100755 --- a/docbook/reference/en/en-US/modules/server-installation.xml +++ b/docbook/reference/en/en-US/modules/server-installation.xml @@ -122,7 +122,7 @@ keycloak-war-dist-all-&project.version;/
- Configuring the Server + Configuring the Server Although the Keycloak Server is designed to run out of the box, there's some things you'll need to configure before you go into production. Specifically: