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. Make sure you use version 2.4 or later, which you can obtain from the mod_auth_openidc releases page at https://github.com/zmartzone/mod_auth_openidc/releases Newer releases of mod_auth_openidc also require a newer version of the cjose RPM. You can obtain the URL to download the required version of cjose by running
curl -sL 'https://api.github.com/repos/zmartzone/mod_auth_openidc/releases?per_page=100' \
| jq -r '.[].assets[] | select(.name|test("^cjose-")) | .browser_download_url'
Here are the Apache HTTP Server configuration directives for the newer versions of mod_auth_openidc:
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"
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
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
OIDCRefreshAccessTokenBeforeExpiry 300 logout_on_error
OIDCUnAuthAction auth
OIDCUnAutzAction 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.