Chapter 8. Server Cache Configuration

There are multiple different caches configured for Red Hat Single Sign-On. There is a realm cache that holds information about secured applications, general security data, and configuration options. This size of this cache is unbounded and does not have a limit on entries. This might scare you a little bit, but the number of entries in this cache is pretty low compared to the user cache. There is also a user cache that contains user metadata. It defaults to a maximum of 10000 entries and uses a least recently used eviction strategy. There are also separate caches for user sessions, offline tokens, and login failures. These caches are unbounded in size as well.

The eviction policy and max entries for these caches can be configured in the standalone.xml, standalone-ha.xml, or domain.xml depending on your operating mode.

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
   <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
       <local-cache name="realms"/>
       <local-cache name="users">
          <eviction max-entries="10000" strategy="LRU"/>
       </local-cache>
       <local-cache name="sessions"/>
       <local-cache name="offlineSessions"/>
       <local-cache name="loginFailures"/>
       <local-cache name="work"/>
       <local-cache name="realmVersions">
          <transaction mode="BATCH" locking="PESSIMISTIC"/>
       </local-cache>
   </cache-container>

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
   <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
       <transport lock-timeout="60000"/>
       <invalidation-cache name="realms" mode="SYNC"/>
       <invalidation-cache name="users" mode="SYNC">
           <eviction max-entries="10000" strategy="LRU"/>
       </invalidation-cache>
       <distributed-cache name="sessions" mode="SYNC" owners="1"/>
       <distributed-cache name="offlineSessions" mode="SYNC" owners="1"/>
       <distributed-cache name="loginFailures" mode="SYNC" owners="1"/>
       <replicated-cache name="work" mode="SYNC"/>
       <local-cache name="realmVersions">
           <transaction mode="BATCH" locking="PESSIMISTIC"/>
       </local-cache>
   </cache-container>

To limit or expand the number of allowed entries simply add, edit, or remove the eviction element from the invalidation-cache or distributed-cache declaration you want to change.

The sessions, offlineSessions and loginFailures caches are the only caches that may perform replication. Entries are not replicated to every single node, but instead one or more nodes is chosen as an owner of that data. If a node is not the owner of a specific cache entry it queries the cluster to obtain it. What this means for failover is that if all the nodes that own a piece of data go down, that data is lost forever. By default, Red Hat Single Sign-On only specifies one owner for data. So if that one node goes down that data is lost. This usually means that users will be logged out and will have to login again.

You can change the number of nodes that replicate a piece of data by change the owners attribute in the distributed-cache declaration.

<subsystem xmlns="urn:jboss:domain:infinispan:4.0">
   <cache-container name="keycloak" jndi-name="infinispan/Keycloak">
       <distributed-cache name="sessions" mode="SYNC" owners="2"/>
...

Here’s we’ve changed it so at least two nodes will replicate one specific user login session.

To disable the realm or user cache, you must edit the keycloak-server.json file in your distribution. Where this file lives depends on your operating mode Here’s what the config looks like initially.

    "userCache": {
        "default" : {
            "enabled": true
        }
    },

    "realmCache": {
        "default" : {
            "enabled": true
        }
    },

To disable the cache set the enabled field to false for the cache you want to disable. You must reboot your server for this change to take effect.

To clear the realm or user cache, go to the Red Hat Single Sign-On admin console Realm Settings→Cache Config page. On this page you can clear the realm cache or the user cache. This will clear the caches for all realms and not only the selected realm.