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: