Skip to content

Caching

Jump to bottom Edit New page
Hans Zandbelt edited this page Sep 4, 2024 · 33 revisions

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 / Valkey
    shared across multiple Apache processes and/or servers, with an option for persistency across reboots and upgrades
    Note: support for Redis/Valkey over TLS, Redis Sentinel (TLS) and Redis Cluster (TLS) is available under a commercial license via [email protected], see the docs below
  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
  • refresh tokens during their usage in a refresh token request i.e. refreshing an access token and possible the refresh token itself
  • JWK sets that have been retrieved from jwk_uri's (to validate id_token, logout_token, JWT access_token and JWT userinfo response)
  • resolved OP metadata when using OIDCProviderMetadataUrl and/or OIDCOAuthServerMetadataURL
  • jti values from logout_token when receiving Backchannel Logout requests
  • temporary state associated with Request URI's
  • signed JWTs when using OIDCPassUserInfoAs signed_jwt and environment variable OIDC_USERINFO_SIGNED_JWT_CACHE_TTL
  • JQ filter results when using OIDCFilterClaimsExpr and/or OIDCUserInfoClaimsExpr and/or Require claims_expr

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 10000. 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"

Since version 2.4.11.4 the following advanced Memcache options are available:

# Minimum number of connections to each Memcache server per process. Defaults to
# OIDCMemCacheConnectionsHMax.
#OIDCMemCacheConnectionsMin <number>

# All connections above this limit will be closed if they have been idle for
# more than OIDCMemCacheConnectionsTTL. Defaults to OIDCMemCacheConnectionsHMax.
#OIDCMemCacheConnectionsSMax <number>

# Maximum number of connections to each Memcache server per process. Defaults to
# ThreadsPerChild or if mod_http2 is loaded to ThreadsPerChild - 1 + H2MaxWorkers.
#OIDCMemCacheConnectionsHMax <number>

# Maximum time in seconds a connection to a Memcache server can be idle before
# being closed. Defaults to 60 seconds.
# Only for Apache >= 2.4.x: By adding a postfix of ms, the timeout can be also
# set in milliseconds. Defaults to 60 seconds.
#OIDCMemCacheConnectionsTTL <seconds>

Redis/Valkey

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

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

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

    OIDCRedisCachePassword <password>

Since version 2.4.11.4 the following option is available for setting the username with Redis/Valkey >= 6 ACLs:

   OIDCRedisCacheUsername <username>

If required you can specify the database to be selected on the Redis/Valkey server as follows:

    OIDCRedisCacheDatabase <index>

Redis/Valkey TLS / Redis/ Cluster (TLS) / Redis Sentinel (TLS)

(commercial only)

This secton documents the configuration options for the commercially licensed binaries for Redis Cluster, Redis Sentinel and Redis/Valkey over TLS.

Sample config for Redis Cluster:

    OIDCCacheType redis-cluster
    OIDCRedisCacheServer 172.23.1.10:6379,172.23.1.20:6379,172.23.1.30:6379,172.23.1.40:6379,172.23.1.50:6379,172.23.1.60:6379

Sample config for Redis Sentinel:

    OIDCCacheType redis-sentinel
    OIDCRedisCacheServer 172.23.1.10:26379,172.23.1.20:26379,172.23.1.30:26379
    OIDCRedisCacheSentinelServiceName my_redis_master

Sample config for Redis/Valkey over TLS, possibly combined with Redis Cluster, Sentinel or standalone:

    OIDCRedisCacheKey /etc/redis.key
    OIDCRedisCacheCert /etc/redis.crt
    OIDCRedisCacheCA /etc/ca.crt

The TLS configuration options are described below:

# The filename of the PEM-encoded private key of the client certificate used to
# authenticate mod_auth_openidc to the Redis/Valkey Server with Mutual TLS.
# When not defined, no client certificate is used to authenticate.
#OIDCRedisCacheKey <filename>

# The filename of the PEM-encoded client certificate with the public key corresponding to the
# private key above, ie. used by mod_auth_openidc to authenticate to Redis/Valkey over Mutual TLS.
# When not defined, no client certificate is used to authenticate.
#OIDCRedisCacheCert <filename>

# The filename of the PEM-encoded Root certificate of the Certificate Authority that issued the
# TLS certificate presented by the Redis/Valkey Server. May contain a chain or multiple certificates as
# long as the Root CA is included.
#OIDCRedisCacheCA <filename>

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

Session Revocation

Available since version 2.4.11

To revoke a user session from an external application (without sending the user's browser through a logout flow) one can call the <redirect_uri> handler with the session identifier of the session that needs to be terminated as follows:

<redirect_uri>?revoke_session=<uuid>

Note that this only works for server side cached session i.e. OIDCSessionType server-cache (shm, memcache, redis, file)

Add a custom footer
Add a custom sidebar
Clone this wiki locally