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, possibly across different Redis servers living on different machines, with an option for persistency across reboots and upgrades
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
• JWT ID claims (jti) when using OP-init-SSO draft-bradley-oauth-jwt-encoded-state-03

Cache Configuration

Shared Memory

For shared memory caching you can configure the number of slots that are available for caching. As you'll note below, these slots are shared across 6 information elements that can be cached, 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>

It is important to realize that the slot size and the size of the key is a compiled in setting. The cache slot size is 16384 bytes and the cache key size is 128 bytes. If you need to increase these settings, you'll need to recompile the module and modify these defines in src/cache/shm.c.

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.

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:

# "server-cache" server-side caching storage.
# "client-cookie" uses browser-side sessions stored in a cookie.
# When not defined the default "server-cache" is used.
#OIDCSessionType [server-cache|client-cookie]