mod_auth_openidc
2.4.11.2
About: mod_auth_openidc is an authentication/authorization module for the Apache 2.x HTTP server that functions as an OpenID Connect Relying Party (RP), authenticating users against an OpenID Connect Provider (OP). It can also function as an OAuth 2.0 Resource Server.
![]() ![]() |
mod_auth_openidc is a certified authentication and authorization module for the Apache 2.x HTTP server that implements the OpenID Connect Relying Party functionality.
This module enables an Apache 2.x web server to operate as an OpenID Connect Relying Party (RP) towards an OpenID Connect Provider (OP). It relays end user authentication to a Provider and receives user identity information from that Provider. It then passes on that identity information (a.k.a. claims) to applications protected by the Apache web server and establishes an authentication session for the identified user.
The protected content, applications and services can be hosted by the Apache server itself or served from origin server(s) residing behind it by configuring Apache as a Reverse Proxy in front of those servers. The latter allows for adding OpenID Connect based authentication to existing applications/services/SPAs without modifying those applications, possibly migrating them away from legacy authentication mechanisms to standards-based OpenID Connect Single Sign On (SSO).
By default the module sets the REMOTE_USER
variable to
the id_token
[sub]
claim, concatenated with
the OP's Issuer identifier ([sub]@[iss]
). Other
id_token
claims are passed in HTTP headers and/or
environment variables together with those (optionally) obtained from the
UserInfo endpoint. The provided HTTP headers and environment variables
can be consumed by applications protected by the Apache server.
Custom fine-grained authorization rules - based on Apache's
Require
primitives - can be specified to match against the
set of claims provided in the id_token
/
userinfo
claims, see here.
Clustering for resilience and performance can be configured using one of
the supported cache backends options as listed here.
For an exhaustive description of all configuration options, see the
file auth_openidc.conf
.
This file can also serve as an include file for
httpd.conf
.
mod_auth_openidc is OpenID Connect certified and supports the following specifications:
Documentation can be found at the Wiki (including Frequently Asked
Questions) at:
https://github.com/zmartzone/mod_auth_openidc/wiki
For questions, issues and suggestions use the Github Discussions forum
at:
https://github.com/zmartzone/mod_auth_openidc/discussions
For commercial support contracts, professional services, training and
use-case specific support please contact:
sales@zmartzone.eu
Sample configuration for using Google as your OpenID Connect Provider
running on www.example.com
and
https://www.example.com/example/redirect_uri
registered as
the redirect_uri for the client through the Google API Console.
You will also have to enable the Google+ API
under
APIs & auth
in the Google API console.
OIDCProviderMetadataURL https://accounts.google.com/.well-known/openid-configuration<your-client-id-administered-through-the-google-api-console>
OIDCClientID <your-client-secret-administered-through-the-google-api-console>
OIDCClientSecret
# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
.com/example/redirect_uri
OIDCRedirectURI https://www.example<password>
OIDCCryptoPassphrase
<Location /example/>
AuthType openid-connect
valid-user
Require</Location>
Note if you want to securely restrict logins to a specific Google
Apps domain you would not only add the
hd=<your-domain>
setting to the
OIDCAuthRequestParams
primitive for skipping the Google
Account Chooser screen, but you must also ask for the email
scope using OIDCScope
and use a Require claim
authorization setting in the Location
primitive similar
to:
OIDCScope "openid email" claim hd:<your-domain> Require
The above is an authorization example of an exact match of a provided claim against a string value. For more authorization options see the Wiki page on Authorization.
mod_auth_openidc.so
in your Apache
serverAuthType openid-connect
OIDCRedirectURI
to a "vanity" URL within a location
that is protected by mod_auth_openidcOIDCClientID
and
OIDCClientSecret
respectivelyOIDCRedirectURI
as the Redirect or
Callback URI with your client at the ProviderOIDCProviderMetadataURL
so it points to the
Discovery metadata of your OpenID Connect Provider served on the
.well-known/openid-configuration
endpointOIDCCryptoPassphrase
for
session/state encryption purposes auth_openidc_module modules/mod_auth_openidc.so
LoadModule
<issuer>/.well-known/openid-configuration
OIDCProviderMetadataURL <client_id>
OIDCClientID <client_secret>
OIDCClientSecret
# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
<hostname>/secure/redirect_uri
OIDCRedirectURI https://<password>
OIDCCryptoPassphrase
<Location /secure>
AuthType openid-connect
valid-user
Require</Location>
For details on configuring multiple providers see the Wiki.
See the Wiki for configuration docs for other OpenID Connect Providers:
This software is open sourced by ZmartZone IAM. For commercial services you can contact ZmartZone IAM as described above in the Support section.