Caching

Overview

mod_auth_openidc implements server-side caching across different Apache processes through one of the following options:

1. shared memory (default)
   shared across a single logical Apache server running as multiple Apache processes (using mpm_prefork) on the same machine
2. memcache
   shared across multiple Apache processes and/or servers, possibly across different memcache servers living on different machines
3. Redis
   shared across multiple Apache processes and/or servers, with an option for persistency across reboots and upgrades
   (Note: support for Redis over TLS, Redis Sentinel (TLS) and Redis Cluster (TLS) is available under a commercial license)
4. file storage
   in a temp directory - possibly a shared file system across multiple Apache processes and/or servers

Cache Contents

The following information is cached:

• authenticated user session state
• nonce values from authorization requests (to prevent replay attacks)
• validated OAuth 2.0 access tokens
• JWK sets that have been retrieved from jwk_uri's (to validate ID tokens)
• resolved OP metadata when using OIDCProviderMetadataUrl
• temporary state associated with Request URI's

Cache Configuration

Shared Memory

For shared memory caching you can configure the number of fixed size slots that are available for caching. As you'll note from the previous section, these slots are used for caching 6 different pieces of information, they're not just for user sessions. The default setting for the maximum number of elements that can be cached simultaneously is 500. The cache will use a Least Recently Used (LRU) strategy for re-using slots if all slots are occupied.

    OIDCCacheType shm
    OIDCCacheShmMax <number-of-slots>

The size of the cache key is a compiled in setting of 512 bytes. The cache value slot size is 16384 bytes by default and can be configured (with a minimum of 8192 bytes) with the following setting (calculate in 512+17 bytes of non-payload overhead):

    OIDCCacheShmEntrySizeMax <bytes>

Memcache

For memcache based caching you'll need to point the module to the memcache servers that you want to use, as in:

    OIDCCacheType memcache
    OIDCMemCacheServers (<hostname>[:<port>])+

If no port is specified, the default port 11211 will be used. Notice that if you want to configure multiple servers, you'll need to enclose the whole value in double quotes as in:

    OIDCMemCacheServers "memcache-server1 memcache-server2 memcache-server3"

Redis

For Redis based caching you'll need to point the module to the Redis server that you want to use, as in:

    OIDCCacheType redis
    OIDCRedisCacheServer <hostname>[:<port>]

When the port is not specified, the Redis default port 6379 will be used. If your Redis server requires a password then you can use:

    OIDCRedisCachePassword <password>

File

For file based caching you'll need to specify the path where the (temporary) files are stored. If it is not specified, the default /tmp will be used. You can also specify the cache clean interval, which defines the minimum interval between cache writes that will be used to go through the cache directory and clean expired cache entries. The default for the cache clean interval is 60 seconds.

    OIDCCacheType file
    OIDCCacheDir <directory>
    OIDCCacheFileCleanInterval <seconds>

Advanced Options

For session caching (and only for session caching) there's an option to use client side caching where all session state is encoded in a browser cookie as opposed to the server side caching mechanisms listed above where state is stored server side, by configuring OIDCSessionType:

# (Optional)
# OpenID Connect session storage type.
# "server-cache" server-side caching storage.
# "client-cookie" uses browser-side sessions stored in a cookie; see also OIDCSessionCookieChunkSize next
# A suffix ":persistent" can be added if you want to use a persistent cookie that survives browser restarts
# instead of a session cookie that is tied to the lifetime of the browser session.
# The "expires" value of the persistent cookie is controlled by the OIDCSessionInactivityTimeout setting.
# When not defined the default "server-cache" is used.
OIDCSessionType server-cache[:persistent]|client-cookie[:persistent]

# (Optional)
# OpenID Connect session cookie chunk size.
# When using "OIDCSessionType client-cookie" the session cookie may become quite large if a lot of session
# data needs to be stored, typically the size depends on the "scopes" of information you request. To work
# around cookie size limitations for most web browsers (usually 4096 bytes), the "client-cookie" will be split
# over a number of "chunked" cookies if the resulting session data is over a certain number of bytes, 
# If you want to prevent splitting the session cookie regardless of its size, set the value to 0.
# When not defined the default chunk size is 4000 bytes
OIDCSessionCookieChunkSize 4000