Skip to content
Connect2id

Database, caching and clustering

The Connect2id server uses Infinispan to:

  • Store its data, such as client registrations, with support for a variety of database technologies, including low-latency in-memory storage for short-lived and cached objects on the JVM heap or in Redis.

  • Cluster Connect2id server nodes together.

1. Supported databases

Choose a database for persisting Connect2id server data:

Database Version Type Deployment
MySQL 5.7.8+ SQL
  • On premise
  • Cloud
PostgreSQL 9.5+ SQL
  • On premise
  • Cloud
Microsoft SQL Server 2016+ SQL
  • On premise
  • Cloud
Oracle Database 12c r1+ SQL
  • On premise
  • Cloud
DynamoDB

 n/a NoSQL
  • AWS
H2

 2.2+ SQL
  • Embedded

Notes:

  1. MySQL: Compatible databases, such as MariaDB 10.2.7+ or AWS Aurora, are supported.
  2. PostgreSQL: Compatible databases, such as CockroachDB, are supported.
  3. The lightweight embedded relational H2 database is intended for testing and development purposes. This is the database the Connect2id server is configured with out of the box.
  4. For high-availability and durability of Connect2id server data use a database cluster set up for replication and fail-over.

2. Supported cluster modes

Choose a cluster mode for your scaling needs:

Replication Mode Stateless Mode
Server nodes 1 - 2 1 - ∞
Storage of short-lived and cached data Local: JVM heap External: Redis or the main database
Ideal for
  • small to medium loads
  • predictable loads
  • small to large loads
  • quick up/down scaling

To make the OpenID Connect and OAuth 2.0 service highly-available deploy a Connect2id server cluster with two nodes at minimum. A single node handles in the order of 100 to 300 OpenID Connect requests (in the code flow) per CPU core per second, assuming the tokens are signed with an RSA 2048 bit key. Server nodes can be added and removed dynamically to / from the cluster.

Replication – Ideal for medium, predictable loads. For improved performance sessions and other short-lived objects are stored in Infinispan on the JVM heap. Persisted server data that is frequently used is also cached there. The in-memory data is continuously replicated between the nodes. The JVM on each node should be provisioned with sufficient heap capacity for the expected maximum number of sessions and other objects stored in memory.

Stateless – Ideal for large loads, allows quick up / down cluster scaling. The Connect2id server state is stored entirely in the underlying database(s).

  • Basic – Using the configured SQL or DynamoDB database to store all short and long-lived server data.

  • Redis – Improves performance and latency by using Redis as an additional in-memory database to cache frequently used server data and store sessions and other short-lived objects. The Redis instance(s) should be provisioned with sufficient memory to handle peak usage.

Standalone – Intended primarily for Connect2id server testing and development. Clustering is disabled, data is persisted to an embedded relational H2 database, caching is on the JVM heap. This is the out-of-the-box configuration.

One way to estimate your memory requirements is to load the Connect2id server with a number of simulated sessions containing typical data via the session store API.

3. Configuration

After choosing a backend database and cluster mode the set up is as simple as:

  1. Link to the appropriate Infinispan XML configuration file.

  2. Configure the database connection.

  3. Tune the expiration interval (optional).

  4. Allow inbound port access for sync messages (replication clusters only).

  5. Configure a health check URL.

The four steps are explained below.

3.1 Link to the Infinispan XML configuration file

The Connect2id server comes with a set of Infinispan configuration files for each cluster mode and database combination in the WEB-INF directory of its c2id.war package.

  • Cluster in replication mode:

    /WEB-INF/infinispan-replication-mysql.xml
/WEB-INF/infinispan-replication-postgres95.xml
/WEB-INF/infinispan-replication-sqlserver.xml
/WEB-INF/infinispan-replication-oracle.xml
/WEB-INF/infinispan-replication-dynamodb.xml

  • Cluster in stateless mode:

    /WEB-INF/infinispan-stateless-mysql.xml
/WEB-INF/infinispan-stateless-postgres95.xml
/WEB-INF/infinispan-stateless-sqlserver.xml
/WEB-INF/infinispan-stateless-oracle.xml
/WEB-INF/infinispan-stateless-dynamodb.xml

  • Cluster in stateless mode, Redis used to store the short-lived objects and cache long-lived objects from the database:

    /WEB-INF/infinispan-stateless-redis-mysql.xml
/WEB-INF/infinispan-stateless-redis-postgres95.xml
/WEB-INF/infinispan-stateless-redis-sqlserver.xml
/WEB-INF/infinispan-stateless-redis-oracle.xml

  • Cluster in stateless mode, Redis used to store the short-lived objects and DynamoDB to store the long-lived (note, transparent caching of the long-lived objects in DynamoDB can be enabled with DAX):

    /WEB-INF/infinispan-stateless-redis-dynamodb.xml

  • Local (no clustering) mode:

    /WEB-INF/infinispan-local-h2.xml

Out of the box the Connect2id server is configured in local mode with an embedded H2 database:

/WEB-INF/infinispan-local-h2.xml

For the multi-tenant Connect2id server edition:

  • Cluster in stateless mode:

    /WEB-INF/infinispan-multitenant-stateless-mysql.xml
/WEB-INF/infinispan-multitenant-stateless-postgres95.xml
/WEB-INF/infinispan-multitenant-stateless-sqlserver.xml
/WEB-INF/infinispan-multitenant-stateless-oracle.xml
/WEB-INF/infinispan-multitenant-stateless-dynamodb.xml

  • Cluster in stateless mode, Redis used to store the short-lived objects and cache long-lived objects from the database:

    /WEB-INF/infinispan-multitenant-stateless-redis-mysql.xml
/WEB-INF/infinispan-multitenant-stateless-redis-postgres95.xml
/WEB-INF/infinispan-multitenant-stateless-redis-sqlserver.xml
/WEB-INF/infinispan-multitenant-stateless-redis-oracle.xml

  • Local (no clustering) mode:

    /WEB-INF/infinispan-multitenant-local-h2.xml

There are two ways to switch to a configuration of your choice, e.g. a stateless cluster mode with a PostgreSQL database:

  1. Set the infinispan.configurationFile Java system property:

    -Dinfinispan.configurationFile=/WEB-INF/infinispan-stateless-postgres95.xml

  2. Or, edit the infinispan.configurationFile context parameter in /WEB-INF/web.xml:

    <context-param>
    <description>
        The location of the Infinispan configuration file. Must be
        relative to the web application root directory.
    </description>
    <param-name>infinispan.configurationFile</param-name>
    <param-value>/WEB-INF/infinispan-stateless-postgres95.xml</param-value>
</context-param>

3.2 Configure the database connection

3.2.1 MySQL

To persist data to an MySQL 5.7.8+ database:

  • Create а new database, the character set must be UTF8:

    CREATE DATABASE c2id CHARACTER SET utf8

  • Set the JDBC properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • dataSource.url – The JDBC URL. The provided MariaDB JDBC driver supports MySQL, MariaDB and AWS Aurora specific configurations, with a set of fail-over and load-balancing modes. The default value is jdbc:mysql://localhost/c2id?useUnicode=yes&amp;characterEncoding=UTF-8.
    • dataSource.user – The database user, the default value is c2id.
    • dataSource.password – The database password.
    • dataSource.createTableIfMissing – Controls automatic table creation and table schema updating (when upgrading to a new major server version) on Connect2id server startup, the default value is true. Since v14.0.
    • dataSource.maxPoolSize – Controls the maximum size the connection pool is allowed to reach, including both idle and in-use connections. The default size is 5. Since v14.0.
    • dataSource.maxLifetime – Controls the maximum connection lifetime in the pool. The default value is 1800000 milliseconds (30 minutes). Since v14.10.
    • dataSource.expiredQueryPageLimit – Controls the page limit in SQL select queries to purge expired records, such as records of sessions, from the database. The default value is 1000 records. Since v14.10.

  • The Connect2id server uses HikariCP to manage its SQL connection pool. The default pool settings are suitable for most deployments. To tune it add an appropriate property to the SQL store parameters in the Infinispan XML configuration.

  • If automatic table creation is disabled manually apply the SQL statements provided in WEB-INF/sql/create-table-statements-mysql.sql (available since v14.0) before starting the Connect2id server.

3.2.2 PostgreSQL

To persist data to a PostgreSQL 9.5+ database:

  • Create а new database, the character set must be UTF8:

    CREATE DATABASE c2id ENCODING UTF8

  • Set the JDBC properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • dataSource.host – The database host name / IP address, the default value is localhost.
    • dataSource.user – The database user, the default value is c2id.
    • dataSource.password – The database password.
    • dataSource.databaseName – The database name, the default value is c2id.
    • dataSource.createTableIfMissing – Controls automatic table creation and table schema updating (when upgrading to a new major server version) on Connect2id server startup, the default value is true. Since v14.0.
    • dataSource.databaseSchema – optional property for the PostgreSQL schema (namespace) to use. The default value is empty, implying the default public schema. Since v14.8.
    • dataSource.maxPoolSize – Controls the maximum size the connection pool is allowed to reach, including both idle and in-use connections. The default size is 5. Since v14.0.
    • dataSource.maxLifetime – Controls the maximum connection lifetime in the pool. The default value is 1800000 milliseconds (30 minutes). Since v14.10.
    • dataSource.expiredQueryPageLimit – Controls the page limit in SQL select queries to purge expired records, such as records of sessions, from the database. The default value is 1000 records. Since v14.10.

  • The Connect2id server uses HikariCP to manage its SQL connection pool. The default pool settings are suitable for most deployments. To tune it add an appropriate property to the SQL store parameters in the Infinispan XML configuration.

  • If automatic table creation is disabled manually apply the SQL statements provided in WEB-INF/sql/create-table-statements-postgres.sql (available since v14.0) before starting the Connect2id server.

3.2.3 Microsoft SQL Server

To persist data to an SQL Server 2016+ database:

  • Create а new database, the collation is irrelevant, the character should be the default UCS-2 / UTF-16 supporting i18n or may be set to UTF8 (supported from SQL Server version 2019 on):

    CREATE DATABASE c2id

  • Set the JDBC properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • dataSource.url – The JDBC URL, the default value is jdbc:sqlserver://localhost:1433;databaseName=c2id;applicationName=c2id;.
    • dataSource.user – The database user, the default value is c2id.
    • dataSource.password – The database password.
    • dataSource.createTableIfMissing – Controls automatic table creation and table schema updating (when upgrading to a new major server version) on Connect2id server startup, the default value is true. Since v14.0.
    • dataSource.maxPoolSize – Controls the maximum size the connection pool is allowed to reach, including both idle and in-use connections. The default size is 5. Since v14.0.
    • dataSource.maxLifetime – Controls the maximum connection lifetime in the pool. The default value is 1800000 milliseconds (30 minutes). Since v14.10.
    • dataSource.expiredQueryPageLimit – Controls the page limit in SQL select queries to purge expired records, such as records of sessions, from the database. The default value is 1000 records. Since v14.10.

  • The Connect2id server uses HikariCP to manage its SQL connection pool. The default pool settings are suitable for most deployments. To tune it add an appropriate property to the SQL store parameters in the Infinispan XML configuration.

  • If automatic table creation is disabled manually apply the SQL statements provided in WEB-INF/sql/create-table-statements-sqlserver.sql (available since v14.0) before starting the Connect2id server.

3.2.4 Oracle Database

To persist data to an Oracle 12c r1+ database:

  • Create а new database. The configured national database character set must be UTF8 (NLS_NCHAR_CHARACTERSET=AL32UTF8).

    CREATE DATABASE c2id

  • Set the JDBC properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • jdbc.url – The JDBC URL, the default value is jdbc:oracle:thin:@//localhost:1521/XE.
    • dataSource.user – The database user, the default value is c2id.
    • dataSource.password – The database password.
    • dataSource.databaseName – The database name, the default value is c2id.
    • dataSource.createTableIfMissing – Controls automatic table creation and table schema updating (when upgrading to a new major server version) on Connect2id server startup, the default value is true. Since v14.0.
    • dataSource.maxPoolSize – Controls the maximum size the connection pool is allowed to reach, including both idle and in-use connections. The default size is 5. Since v14.0.
    • dataSource.maxLifetime – Controls the maximum connection lifetime in the pool. The default value is 1800000 milliseconds (30 minutes). Since v14.10.
    • dataSource.expiredQueryPageLimit – Controls the page limit in SQL select queries to purge expired records, such as records of sessions, from the database. The default value is 1000 records. Since v14.10.

  • The Connect2id server uses HikariCP to manage its SQL connection pool. The default pool settings are suitable for most deployments. To tune it add an appropriate property to the SQL store parameters in the Infinispan XML configuration.

  • If automatic table creation is disabled manually apply the SQL statements provided in WEB-INF/sql/create-table-statements-oracle.sql (available since v14.0) before starting the Connect2id server.

3.2.5 DynamoDB

To persist data to DynamoDB in the AWS cloud:

  • Set the connection properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • dynamodb.region – The preferred AWS region, e.g. eu-central-1.

      If this system property is undefined the default AWS region provider chain takes over to determine the region, using alternative methods like reading the AWS_REGION environment variable.

      The default AWS region provider chain is helpful in cases like deployments in AWS EKS or where the AWS access credential is a web identity token obtained from the AWS STS.

    • dynamodb.httpProxyHost, dynamodb.httpProxyPort – Optional proxy for accessing the DynamoDB endpoint.

    • dynamodb.encryptionAtRest – If true the DynamoDB tables will be created with encryption at-rest. The default value is false.

    • dynamoDB.hmacSHA256Key – Optional 256-bit secret key (BASE64-encoded) to secure the integrity and authenticity of the stored DynamoDB items by including a SHA-256 based Message Authentication Code (HMAC) in a _hmac#256 binary attribute.

      To generate a key with OpenSSL:

      openssl rand -base64 32

      If a retrieved DynamoDB item is missing the _hmac#256 attribute or its verification fails the Connect2id server will produce an HTTP 500 Internal Server Error, log the error with a DS0131 code and increment the <cache-name>.dynamoDB.invalidItemHmacCounter metric.

      The HMAC protection must be enabled for newly provisioned or empty DynamoDB tables. Enabling the protection for DynamoDB tables with prior existing items will cause HMAC validation errors on their retrieval.

    • dynamodb.enableStream – If true the DynamoDB tables will be created with an enabled stream (intended for global tables). The default value is false.

    • dynamodb.enableDeletionProtection – If true deletion protection will be enabled for all DynamoDB tables. If false this configuration has no effect on tables with already enabled deletion protection (use the AWS console or another method to disable it). The default value is false. Since v16.1.

    • dynamodb.enableContBackups – If true to continuous backups / point-in-time recovery will be enabled for all DynamoDB tables where crucial or long-lived data is persisted: id_access_tokens, long_lived_authorizations, revocation_journal, clients, federation_clients and tenants (in the multi-tenant Connect2id server edition). If false this configuration has no effect on tables with already enabled deletion protection (use the AWS console or another method to disable it). The default value is false.

    • dynamodb.tablePrefix – Optional DynamoDB table name prefix. The default value is none.

    • dynamodb.applyRangeKey – Optional range key to apply to all DynamoDB operations. Enables sharing of the DynamoDB tables between multiple Connect2id server deployments. If set the value should be tid. Not available in the multi-tenant Connect2id server edition.

    • dynamodb.rangeKeyValue – The value of the optional range key, uniquely identifying the Connect2id server deployment. Not available in the multi-tenant edition of the Connect2id server.

    • dynamodb.enableTTL.sessionStore.sessionMap – If true enables automatic expiration of subject sessions by DynamoDB (via a ttl attribute). When enabled set the sessionStore.sessionMap.expirationInterval Java system property to zero (0) to disable the Infinispan expiration thread. Expiration may be moved to DynamoDB if there are no relying parties registered for OpenID Connect back-channel logout notifications, as session expiration notifications can no longer be delivered to them.

    • dynamoDB.purgeMaxReadCapacity – The maximum read capacity units that may be consumed during a scan of the subject sessions table to purge it of expired sessions. Any write capacity units consumed to delete expired sessions are bounded by this value and will always stay below it. The value is specified as an absolute number of read capacity units, for example 25, or as a percentage of the current provisioned read capacity units for the table (evaluated before a purge commences), for example 10.0%. The default value is 10.0%. This property has no effect when dynamodb.enableTTL.sessionStore.sessionMap is enabled.

  • Make sure the AWS credentials for accessing the DynamoDB tables are configured so that the default AWS credentials provider chain can look them up, ideally via IAM instance profile roles.

    The Connect2id server requires access to the following DynamoDB actions:

    • “dynamodb:BatchGetItem”
    • “dynamodb:BatchPutItem”
    • “dynamodb:CreateTable”
    • “dynamodb:DeleteItem”
    • “dynamodb:DescribeContinuousBackups”
    • “dynamodb:DescribeTable”
    • “dynamodb:DescribeTimeToLive”
    • “dynamodb:GetItem”
    • “dynamodb:PutItem”
    • “dynamodb:Query”
    • “dynamodb:Scan”
    • “dynamodb:UpdateContinuousBackups”
    • “dynamodb:UpdateItem”
    • “dynamodb:UpdateTimeToLive”

    Note, when the AWS access credential is a web identity token obtained from the AWS STS the dynamodb.region system property must be left undefined in order to let the default AWS region provider chain determine the region, typically by reading the AWS_REGION environment variable. The region of the AWS STS endpoint is set by the AWS_STS_REGIONAL_ENDPOINT environment variable.

    Example to set the DynamoDB and STS endpoints to the same region:

    AWS_REGION=eu-west-2
AWS_STS_REGIONAL_ENDPOINTS=regional

  • The Connect2id server will automatically create the tables it requires when it accesses DynamoDB for the first time.

  • After the DynamoDB tables are created enable auto-scaling for each table.

  • If you want to run Connect2id server instances in two or more AWS regions, replicating data between them asynchronously, set up global DynamoDB tables.

  • Note, data in DynamoDB tables can be transparently cached for quicker access via DAX.

3.2.6 H2

To persist data to an H2 2.2+ database:

  • Set the JDBC properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • dataSource.user – The database user, the default value is c2id.
    • dataSource.password – The database password.
    • dataSource.createTableIfMissing – Controls automatic table creation and table schema updating (when upgrading to a new major server version) on Connect2id server startup, the default value is true.
    • dataSource.maxPoolSize – Controls the maximum size the connection pool is allowed to reach, including both idle and in-use connections. The default size is 5. Since v14.0.
    • dataSource.maxLifetime – Controls the maximum connection lifetime in the pool. The default value is 1800000 milliseconds (30 minutes). Since v14.10.
    • dataSource.expiredQueryPageLimit – Controls the page limit in SQL select queries to purge expired records, such as records of sessions, from the database. The default value is 1000 records. Since v14.10.

  • The Connect2id server uses the default settings of its Hikari JDBC connection pool. They can be tuned by adding an appropriate property to the SQL store parameters in the Infinispan XML configuration.

  • If automatic table creation is disabled manually apply the SQL statements provided in WEB-INF/sql/create-table-statements-h2.sql (available since v14.0) before starting the Connect2id server.

Check the instructions if you need console access to the embedded H2 database.

3.2.7 Redis

If the Connect2id server is deployed in stateless cluster mode where short-lived and cached data will be stored in Redis:

  • We recommend that you set up two separate Redis servers:

    • One Redis server for transient data, such as sessions. This Redis server should be provisioned with enough memory to hold all current sessions and other objects in it. Make sure the eviction policy of this Redis server is set to volatile-lru:

      maxmemory-policy volatile-lru

      An practical way to estimate the Redis memory requirements is to load the Connect2id server with N sample sessions via the session POST API and then check the resulting memory usage.

      The Redis store for transient data may be additionally configured to persist the data to disk using two strategies - periodic snapshots (RDB) and / or write log (AOF).

    • Another Redis server for caching data only. Configure it with an allkeys-lru policy, to let Redis evict the least recently keys when the maxmemory limit is reached. There is no particular recommendation how much memory to allocate to the caching Redis server. See what works best for you in terms of service latency and budget.

      maxmemory-policy allkeys-lru

      Persisting the cached data is not necessary and brings no benefits.

    • The two Redis servers must be configured with 24 logical databases each. Every Redis database will be dedicated to store a particular Connect2id server object type.

      databases 24

      Database zero (0) will never be used, to prevent a conflict in AWS ElastiCache which inserts a special ElastiCacheMasterReplicationTimestamp key in the default database (at zero index) to aid replication.

    • Note that the Redis cluster topology is not supported because it cannot handle logical databases.

  • Set the Redis connection properties in the Infinispan XML configuration, or better still, override them with Java system properties:

    • redisMapHost, redisMapPort – To point to the host and port of the Redis server for storing transient data, such as sessions.
    • redisCacheHost, redisCachePort – To point to the host and port of the Redis server for cached data.
    • redisMapPassword, redisCachePassword – Optional password to access Redis.

3.3 Tune the expiration interval (optional)

The Connect2id server manages a number of objects, such as sessions, that must be periodically expired to prevent the database from filling up. Unless the Connect2id server is configured with Redis or DynamoDB where the object expiration is handled by the object store itself, the expiration is performed at the application layer by Infinispan. Infinispan periodically wakes up and scans its maps and caches for objects that have reached their max lifetime or max idle time, and purges them.

The default Infinispan expiration interval is 300000 ms (5 minutes). To override it set the infinispan.defaultExpirationInterval Java system property.

To increase the interval to 1 hour:

-Dinfinispan.defaultExpirationInterval=3600000

Note, the expiration interval of subject sessions is configured separately, by the sessionStore.sessionMap.expirationInterval Java system property.

The expiration can be disabled entirely, by setting the interval to zero. This is a mean to set up a stateless cluster where the object expiration is dedicated to a single Connect2id server node, leaving the rest to service API requests only.

3.4 Open inbound ports (replication cluster)

TCP

For a Connect2id server in a replication cluster mode with an SQL database or DynamoDB allow inbound TCP traffic to these ports:

  • port 7800
  • port 7900 through 7905

These ports are required by the clustering layer (JGroups) to receive sync messages (7800) and detect node failures (7900-7905).

The Connect2id server will pick a “site local” (non-routable) IP address on the host machine to attach the TCP listening sockets, e.g. from the 192.168.0.0 or 10.0.0.0 address range. To specify the address otherwise set the jgroups.tcp.address Java system property, e.g. like this:

-Djgroups.tcp.address=match-interface:eth0

Check out the bind_addr section in the JGroups docs for information.

If for some reason IPv6 networking gets used by mistake, you can force the JVM to use IPv4:

-Djava.net.preferIPv4Stack=true

3.5 Health check URL

Configure your load balancer / reverse proxy to use the health-check endpoint for determining a node’s status. You can find more information in the health-check guide.

4. How to override an Infinispan XML configuration setting with a Java system property

Any ${property-name:default-value} placeholder found in the Infinispan XML configuration file can be overridden with a Java system property:

In this example, if a Java system property named dataSource.password is found, it will be used to set the database password, otherwise the default value (“secret”) will apply:

<property name="dataSource.password">${dataSource.password:secret}</property>

The external configuration guide has tips for setting system properties from environment variables, local files and other locations.

5. FAQ

5.1 How to add a new node to a Connect2id server cluster?

Start the new node and let the load balancer direct HTTP requests to it once the health check endpoint becomes available and returns status 200.

In a cluster in replication mode the joining node will automatically discover the coordinator (via the configured discovery protocol, e.g. JDBC_PING) and begin communicating with it and the other nodes.

In a cluster in stateless mode the nodes don’t sync data between them and hence there is no need for them to discover one another.

5.2 How to remove a node from a Connect2id server cluster?

Stop directing HTTP requests from the load balancer, then shut down the node graciously. On Tomcat this is done by calling its bin/shutdown.sh script.

5.3 How to obtain the cluster size?

For a cluster in replication mode check the infinispan.numClusterMembers metric. The gauge will get incremented when a new node joins, decremented when a node leaves.

5.4 Where are the cluster events and errors logged?

The Infinispan and JGroups messages are appended to the log of the Connect2id server.

Check out the guide how to interpret Infinispan and JGroups messages written to the log.

5.5 What JGroups protocols are used?

In a replication mode the JGroups clustering layer is configured to use these protocols:

5.6 Is WAN / cross-datacentre replication supported?

Yes.

Full cross-datacentre replication can be implemented in the stateless mode when configured with a DynamoDB backend database and global tables.

Partial replication is possible in the stateless mode with an SQL database for the persisted data, such as client registrations and long-lived authorisations. An OAuth 2.0 or OpenID Connect client application would not be able to switch seamlessly between regions, e.g. in the middle of an OAuth 2.0 flow. Its credentials and authorisations (refresh tokens), however, will work. The subject sessions can be replicated in those configurations where they are persisted to an SQL database.

5.7 What is the default transaction isolation of the JDBC driver?

5.8 Where are the database SQL schemas?

The relational database schemas can be found in the c2id.war package, in the WEB-INF/sql/ directory.

6. Description of the Infinispan maps and caches

Here is a description of the individual Infinispan maps and caches used by the Connect2id server. This information can be useful to tune the storage parameters.

Key / value maps that must be persisted:

  • clients.registrationsMap – The registered OAuth 2.0 / OpenID Connect clients. For best performance aim to have all client entries cached in memory.

  • federation.registrationsMap – The registered OpenID Connect Federation 1.0 clients. For best performance aim to have all client entries cached in memory.

  • authzStore.longLivedAuthzMap – The long-lived (sticky) OAuth 2.0 authorisations (consent), including the associated refresh tokens. Caching of these entries speeds up processing of login requests as well as refresh token lookup.

  • authzStore.revocationJournalMap – The authorisation revocation journal.

  • tenantRegistry.tenants – The Connect2id server tenants. Applies to the multitenant edition of the server only.

Key / value maps where persistence is recommended, but not critical:

  • authzStore.accessTokenMap – 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.

  • sessionStore.sessionMap – The end-user sessions with the Connect2id server. When stored in memory enough capacity must be allocated to accommodate the maximum expected number of sessions.

  • sessionStore.subjectMap – An index of the sessions for each logged in end-user.

Key / value maps and caches where persistence generally isn’t needed:

  • authzStore.codeMap – The pending OAuth 2.0 authorisation codes awaiting exchange for a token.

  • authzStore.expendedTokens – Tracks expended client authentication JWTs, rotated self-contained (JWT-encoded) refresh tokens, and expended initial client registration tokens.

  • op.authSessionMap – The authentication session state for every end-user who has a login page currently opened. When stored in memory enough capacity must be allocated to accommodate the expected number of open login pages at any one time.

  • op.consentSessionMap – The consent session state for each end-user who has an login page currently opened. If stored in memory enough capacity should be allocated to accommodate the expected number of open login pages at any one time.

  • clients.remoteJWKSetCache – Caches remote client JWK sets referenced by URL.

  • clients.remoteRequestJWTClaimsCache – Caches the claims of validated OAuth 2.0 request objects referenced by URL.