Skip to content
Connect2id

Infinispan caching and clustering

Clustering of the Connect2id server is facilitated by Infinispan, a scalable data-grid which permits the server to cache and store transient objects across the server nodes.

The Infinispan configuration file is located in the WEB-INF directory of the web application:

WEB-INF/infinispan.xml

Infinispan map and cache names

The Connect2id server utilises a number of named Infinispan maps and caches.

What is the difference between a map and a cache?

  • A map stores primary data that is relatively critical. If RAM is not sufficient to keep the entire map in memory, overflowing entries can be saved (evicted) to disk. LRU is the suggested eviction algorithm for all Connect2id server maps.
  • A cache is similar to a map, but it stores redundant data for the purpose of speeding up request processing, by avoiding queries to the backend database. Caches need not have overflow to disk enabled.

This is a list of the Infinispan maps and caches used in the Connect2id server, with their names, usage and recommended settings.

  • Session store maps:

    • sessionStore.sessionMap – Stores the user sessions with the Connect2id server, keyed by a secure session identifier (SID) which is intended to be saved in the user’s browser as a cookie. If a maxEntries limit is set, it should equal the expected number of end-users times the permitted session quota per user. For example, if the total user count is 1 million and the session quota is five, the maxEntries should be set to 5 million. Can be overflown to disk to conserve RAM.
    • sessionStore.subjectMap – An index of the sessions for each logged in user. If a maxEntries limit is set, it should equal the expected total user count. Can be overflown to disk to conserve RAM.

  • Authorisation store maps and caches:

    • authzStore.codeMap – Stores the pending OAuth 2.0 authorisation codes before they get exchanged for an ID and access token. The code map maxEntries setting should be large enough to accommodate the pending OAuth 2.0 codes at any one time. Can be overflown to disk to conserve RAM.
    • authzStore.accessTokenMap – Stores the active identifier-based OAuth 2.0 access tokens. If only self-contained (JWT-encoded) access tokens are issued, this map will not be utilised. The access token map maxEntries limit should be large enough to accommodate all potential identifier-based access tokens in the system; this may be estimated as the total expected user count times the total expected number of client applications. Can be overflown to disk to conserve RAM.
    • authzStore.authzCache – Caches the issued long-lived (persisted) authorisations for each user and client application combination.

  • Authorisation session maps:

    • op.authSessionMap – Stores the authentication session state for each user who has an OpenID Connect login page currently opened. The maxEntries setting should be large enough for the expected number of login pages open at any one time.
    • op.consentSessionMap – Stores the consent session state for each user who has an OpenID Connect login page currently opened. A maxEntries setting is not required because the number of consent sessions is naturally limited by the maximum authentication session number.

  • Client registration cache:

    • op.regCache – Caches the client application registrations with the Connect2id server. The maxEntries setting should equal the total expected number of registered client applications. This cache is critical to the overall system performance and overflow to disk should be avoided if possible.
    • op.regTokenCache – Caches expended initial client registration tokens that may be used only once.

How to include Java system properties into the infinispan.xml configuration

Example, using a default value:

<replicated-cache name="op.clientRegMap" mode="ASYNC">
    <eviction strategy="LIRS" max-entries="${op.clientRegMap.maxEntries:5000}"/>
</replicated-cache>

Configuring cluster networking

Infinispan uses the popular JGroups library to provide reliable messaging between the Connect2id server nodes and features such as automatic cluster formation, node discovery and health checks.

Supported transport protocols:

How to setup a replicated Connect2id server cluster on your local network

All you need to do is put one or more additional Connect2id servers on your local network, which should be enabled for IP multicast. The nodes will automatically detect one another and form a replication cluster, using UDP as the message transport. The detection and negotiation process can be observed in the log of each server node (at DEBUG level), or by using a JMX console to Infinispan.

JGroups configuration

Out of the box the Connect2id server is configured to point to the default JGroups UDP settings in the default-jgroups-udp.xml file (for a local network with IP multicast). This XML file is packaged in Infinispan’s JAR:

WEB-INF/libs/infinispan-core-[version].jar

To use a different JGroups configuration edit the global transport configurationFile property in WEB-INF/infinispan.xml:

<jgroups>
    <stack-file name="jgroups-config" path="default-configs/default-jgroups-udp.xml"/>
</jgroups>

Also, check out our guides on:

You can read more about configuration of JGroups in the Infinispan manual, or on the JGroups website:

WAN replication

The Connect2id server can also be operated across data centres by means of WAN replication. The following Infinispan and JGroups documents offer further pointers on how to set that up:

Resources