Configure Apache HTTP Server to Authenticate Visitors Using OIDC

Body

Environment

Apache HTTP Server (httpd), mod_auth_openidc, OpenID Connect (OIDC), Single Sign-on

Issue

How do I configure httpd to authenticate visitors using using OIDC for Single Sign On ?

Resolution

Follow the example configuration at https://github.com/umich-iam/sso-examples-oidc-mod_auth_openidc

Additional Information

The ITS Web Hosting team uses the following on its web servers as an alternative to contents of apache2/conf.d/mod_auth_openidc.conf in the Git repository above. This alternative configuration preserves the content of POST bodies across access token refreshes, increases the idle timeout to 8 hours, and configures the OIDC session store.

IMPORTANT: The versions of mod_auth_openidc available through standard RPM repositories (such as EPEL) are very out of date (as of May 2022) and lack many important features and bug fixes. Make sure you use version 2.4.15.6 or later, which you can obtain from the mod_auth_openidc releases page at https://github.com/OpenIDC/mod_auth_openidc/releases. Newer releases of mod_auth_openidc also require a newer version of the cjose RPM. RHEL8 and above include cjose in its repositories. For RHEL7, you can obtain the URL to download cjose by running:

curl -sL 'https://api.github.com/repos/OpenIDC/mod_auth_openidc/releases?per_page=100' \
| jq -r '.[].assets[] | select(.name|test("^cjose-")) | .browser_download_url'

mod_auth_openidc requires the hiredis RPM, which can be obtained through EPEL.

Here are the Apache HTTP Server configuration directives for the newer versions of mod_auth_openidc (replace the ${...} variables below with your own actual values):

LoadModule auth_openidc_module modules/mod_auth_openidc.so

OIDCProviderMetadataURL "https://shibboleth.umich.edu/.well-known/openid-configuration"
OIDCClientID     "${OIDC_CLIENT_ID}"
OIDCClientSecret "${OIDC_CLIENT_SECRET}"

# OIDCRedirectURI is a vanity URL that must point to a path protected by this module
# but must NOT point to any content. Think of it as being similar to /cosign/valid
# or /Shibboleth.sso
#
# IMPORTANT: the redirect URI needs to be protected by mod_auth_openidc in order to
# work.  The URI below will work if mod_auth_openidc is used to protect the entire
# server.  If only things under /private are protected, though (as an example), then
# you'll need to change the redirect URI path to be something like /private/redirect_uri

OIDCRedirectURI "https://${WEBSITE_FQDN}/redirect_uri"

<Location /redirect_uri>
    AuthType openid-connect
    Require valid-user
</Location>

# Setup file-based session cache
OIDCCacheType              file
OIDCCacheDir               "${oidc_sessions_cache_directory}"
OIDCCacheFileCleanInterval 60

# Or, setup redis-based session cache
#OIDCCacheType                redis
#OIDCRedisCacheServer         ${REDIS_SERVER_FQDN}:6379
# database 0 may be used by the webapp, let's use a separate one for OIDC
#OIDCRedisCacheDatabase       1

OIDCSessionCacheFallbackToCookie On
OIDCSessionMaxDuration       28800
OIDCSessionInactivityTimeout 28800
OIDCSessionType server-cache
OIDCCacheEncrypt On

# just a random string for local encrypt/decrypt
# consider generating this via "openssl rand -hex 128" 
OIDCCryptoPassphrase "${OIDC_CRYPTO_PASSPHRASE}"

OIDCScope "openid profile email"
OIDCRemoteUserClaim sub

# Indicates whether POST data will be preserved across authentication requests.
# Preservation is done via HTML 5 local storage. Note that this can lead to private
# data exposure on shared terminals, that is why the default is "Off". Can be
# configured on a per Directory/Location basis.
OIDCPreservePost On
OIDCUnAuthAction auth

# Turn on authentication for locations that require login
<Location /content-that-requires-login>
    AuthType openid-connect
    Require valid-user
</Location>

Some additional considerations include:

If OIDCResponseType is omitted, it defaults to code, which returns just authorization code. If app developers need a JWT, then use code id_token instead
There is at least one Single Page App where OIDCStateMaxNumberOfCookies 7 true needs to be set, see the mod_auth_openidc issue for details.
OIDCInfoHook is really useful for certain apps to get information about the authenticated user and session.

Need additional information or assistance? Contact the ITS Service Center.