Cookies

TL;DR

• don't use OIDCSessionType client-cookie
• 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 header in the Javascript call

Overview

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.

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.

Issues

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.

Symptoms

• 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)

Fixes

• don't use OIDCSessionType client-cookie
  the size of your cookies may easily become very large and the cookie gets truncated leading to cookie decryption errors

• protect Javascript paths with OIDCUnAuthAction 401
  instead of redirecting users away to the OpenID Connect provider with the default OIDCUnAuthAction auth

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: http://stackoverflow.com/questions/12533435/xmlhttprequest-not-adding-header-x-requested-with-xmlhttprequest