Hans Zandbelt edited this page Sep 12, 2018 · 9 revisions


  • don't use OIDCSessionType client-cookie on versions older than 2.0.0 or minimize the number of claims obtained from the provider
  • protect Javascript paths with OIDCUnAuthAction 401 or, if it is not possible to make a split between HTML and Javascript paths:
  • provide a X-Requested-With: XMLHttpRequest header in the Javascript call
  • provide an Accept: application/json header in the Javascript call


mod_auth_openidc leverages 2 types of cookies:

  1. a short-lived "state" cookie that correlates the authentication request and response
  2. a long-lived "session" cookie that maintains session state after successful authentication

Both cookies are non-persistent session cookies since version 1.8.8rc4 (in versions before that, the "state" cookie was a persistent cookie with a limited expiry time).

Common Settings

The cookie path and cookie domain settings are shared between the "state" and "session" cookies and can be controlled with the following configuration primitives:

# (Optional)
# Define the cookie path for the "state" and "session" cookies.
# When not defined the default is a server-wide "/".
#OIDCCookiePath <cookie-path>

# (Optional)
# Specify the domain for which the "state" and "session" cookies will be set.
# This must match the OIDCRedirectURI and the URL on which you host your protected
# application. When not defined the default is the server name.
#OIDCCookieDomain <cookie-domain>

State Cookie

The "state" cookie is created when the user is redirected away to the OpenID Connect Provider for authentication. It is a cookie with unique name (prefixed with a constant mod_auth_openidc_state_) that is tied to the state parameter that is sent in the authentication request. It is deleted when the user returns to the Apache server with an authentication response (indicating either success or failure). It is (should be) short-lived and its lifetime can be configured with the OIDCStateTimeout configuration primitive for which the default is 5 minutes. Note that the lifetime is enforced at the server by mod_auth_openidc, not by the lifetime of the cookie.

Since version 2.3.8 mod_auth_openidc limits the number of state cookies - i.e. the number of outstanding authentication request - to 7 by default, controlled by the OIDCStateMaxNumberOfCookies setting.

Session Cookie

The "session" cookie is created after the user returns from the OpenID Connect provider with a successful authentication response (note that the state cookie is deleted at the same time). The name of the session cookie can be configured with the OIDCCookie primitive, the default is mod_auth_openidc_session.


Cookie exceeds size limit

There are a number of circumstances that may lead to a message on the browser or the server that indicated that the cookie size has exceeded the size limit. This is often the case for unauthenticated or expired sessions when either a large number of pages are opened in the same browser simultaneously and/or pages loaded in the browser make a large number of parallel Javascript calls to the server. Typically this indicates a configuration issue that should be solved by reconfiguring the way in which your application is protected.

Version 2.0.0 adds chunked session cookies that give a lot more room for storing data in cookies.


  • Set-Cookie may exceed size limit:

    • size of session cookie is too large when OIDCSessionType client-cookie is used

          [warn] [client <ip>] oidc_util_set_cookie: the length of the cookie value (<size>) is greater than 4093(!) bytes, this may not work with all browsers/server combinations: consider switching to a server side caching!
  • Cookie is corrupted

      [warn] [client <ip>] oidc_session_load_cookie: cookie value possibly corrupted
      [error] [client <ip>] oidc_crypto_aes_decrypt: EVP_DecryptFinal_ex failed: error:06065064:digital envelope routines:EVP_DecryptFinal_ex:bad decrypt
  • Cookie may exceed size limit

    • size of session cookie combined with other cookies is too large when OIDCSessionType client-cookie is used
    • number of state cookies may exceed size limit
    • size of state cookie may exceed size limit when combined with other cookies (unlikely, only when using very long URLs)


  • use a configuration that obtains only a minimal set of claims from the OpenID Connect provider by:

    1. make the provider minimize the set of claims returned in the ID token and from the user info endpoint, and/or
    2. don't specify the user info endpoint in the mod_auth_openidc configuration for the provider so that only claims from the ID token will be present in the session
  • protect Javascript paths with OIDCUnAuthAction 401
    instead of redirecting users away to the OpenID Connect provider with the default OIDCUnAuthAction auth

  • don't use OIDCSessionType client-cookie

    1. the size of your cookies may easily become very large and the cookie gets truncated leading to cookie decryption errors
    2. alternatively use a version of mod_auth_openidc >= 2.0.0 so it supports chunked cookies

Since version 1.8.8rc4 mod_auth_openidc will look for a header with the name X-Requested-With and when that is present it will return a HTTP 401 response instead of creating a state cookie and redirecting the Javascript client to the OpenID Connect Provider (which will not terminate); the X-Requested-With header is set by default by JQuery; if your Javascript code doesn't set it, you can add it manually as described in:

Since version 2.1.6 the X-Requested-With header will need to have the specific value XMLHttpRequest to trigger the 401 behavior.

Since version 2.3.8 the Accept header is also inspected for content types that are not HTML c.q. if it finds a value that has only application/json in it, it will assume it is a non-browser request and will return HTTP 401 by default.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.