mod_auth_openidc

This fork of mod_auth_openidc is NOT an OpenID Certified™ authentication and authorization module for the Apache 2.x HTTP server that implements the OpenID Connect Relying Party functionality.

This version of the module can also authenticate against an OAuth2.0 server using the Code Authorization Grant flow and a UserInfo endpoint. This has been tested with the Phabricator OAuthServer implementation. Other servers implementing Oauth 2.0 Code Authorization Grant Flow, and which provide a suitable API for getting UserInfo as a JSON object may also work. I tried to make these changes without breaking any existing functionality, but have not tested against any OpenID Connect servers, so it cannot be guaranteed.

Note that the changes to support OAuth 2.0 Code Authorization Grant relax some checks, so if your server implements OpenID Connect, it is safer to use the upstream module from https://github.com/pingidentity/mod_auth_openidc

Use of this version is not recommended with public servers that are not completely under your control, as it may open possible attack vectors that may allow an attacker to impersonate a valid user using tokens issued for a different application. Please read : https://oauth.net/articles/authentication/ and understand the risks before deploying this version of the module.

Overview

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.

If the server is a non-OpenID Connect server that implements the OAuth 2.0 Code Authorization Grant flow, the authentication can still be performed, with all user identity information coming from a UserInfo endpoint. In this case, you almost certainly need to set the OIDCOAuthRemoteUserClaim to something that is returned from the UserInfo endpoint. Some additional options are provided for this case to allow more flexibility in the UserInfo endpoint implementation. OIDCProviderUserInfoResponseSubkey can be used to extract the claims from an object inside the JSON response, instead of extracting them directly from the response object. This was required to work with Phabricator's user.whoami API method, which returns user information inside a "result" object.

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.

Interoperability

mod_auth_openidc is OpenID Certified™ and supports the following specifications:

• OpenID Connect Core 1.0 (Basic, Implicit, Hybrid and Refresh flows)
• OpenID Connect Discovery 1.0
• OpenID Connect Dynamic Client Registration 1.0
• OAuth 2.0 Multiple Response Type Encoding Practices 1.0
• OAuth 2.0 Form Post Response Mode 1.0
• RFC7 7636 - Proof Key for Code Exchange by OAuth Public Clients
• OpenID Connect Session Management 1.0 see the Wiki for information on how to configure it)
• OpenID Connect Front-Channel Logout 1.0
• OpenID Connect Back-Channel Logout 1.0

Support

Community

Documentation can be found at the Wiki (including Frequently Asked Questions) at:
https://github.com/OpenIDC/mod_auth_openidc/wiki
For questions, issues and suggestions use the Github Discussions forum at:
https://github.com/OpenIDC/mod_auth_openidc/discussions

Commercial

For commercial support contracts, professional services, training and use-case specific support please contact:
sales@openidc.com

How to Use It

OpenID Connect SSO with Google+ Sign-In

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
OIDCClientID <your-client-id-administered-through-the-google-api-console>
OIDCClientSecret <your-client-secret-administered-through-the-google-api-console>

# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
OIDCRedirectURI https://www.example.com/example/redirect_uri
OIDCCryptoPassphrase <password>

<Location /example/>
   AuthType openid-connect
   Require valid-user
</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"
Require claim hd:<your-domain>

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.

Quickstart with a generic OpenID Connect Provider

1. install and load mod_auth_openidc.so in your Apache server
2. configure your protected content/locations with AuthType openid-connect
3. set OIDCRedirectURI to a "vanity" URL within a location that is protected by mod_auth_openidc
4. register/generate a Client identifier and a secret with the OpenID Connect Provider and configure those in OIDCClientID and OIDCClientSecret respectively
5. and register the OIDCRedirectURI as the Redirect or Callback URI with your client at the Provider
6. configure OIDCProviderMetadataURL so it points to the Discovery metadata of your OpenID Connect Provider served on the .well-known/openid-configuration endpoint
7. configure a random password in OIDCCryptoPassphrase for session/state encryption purposes

LoadModule auth_openidc_module modules/mod_auth_openidc.so

OIDCProviderMetadataURL <issuer>/.well-known/openid-configuration
OIDCClientID <client_id>
OIDCClientSecret <client_secret>

# OIDCRedirectURI is a vanity URL that must point to a path protected by this module but must NOT point to any content
OIDCRedirectURI https://<hostname>/secure/redirect_uri
OIDCCryptoPassphrase <password>

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

For details on configuring multiple providers see the Wiki.

Quickstart for Other Providers

See the Wiki for configuration docs for other OpenID Connect Providers:

• GLUU Server
• Keycloak
• Azure AD
• Sign in with Apple
• Curity Identity Server
• LemonLDAP::NG
• GitLab
• Globus and more

###OAuth 2.0 Code Authorization Grant Flow

Another example config for using a non-OpenID Connect server to perform authorization using the OAuth 2.0 Code Authorization Grant flow. As no useful info is available for identifying the REMOTE_USER from plain OAuth 2.0, this relies on having a UserInfo endpoint to return at least a user id of some sort. This need not be fully compliant with the OpenID spec for UserInfo endpoints, it just needs to return a JSON object. The example server used here is a Phabricator server (https://phabricator.com/), which provides a simple OAuth 2.0 server implementation, and a user.whoami API method to obtain information about the logged in user (under a result object in the JSON response).

OIDCSSLValidateServer Off
OIDCClientID PHID-OASC-abcdefghijklmnopqrst
OIDCClientSecret abc123DEFghijklmnop4567rstuvwxyzZYXWUT8910SRQPOnmlijhoauthplaygroundapplication
OIDCProviderIssuer phabricator.example.com
OIDCRedirectURI https://localhost/example/redirect_uri/
OIDCCryptoPassphrase <password>
OIDCScope "userName realName primaryEmail"
OIDCProviderAuthorizationEndpoint https://phabricator.example.com/oauthserver/auth/
OIDCProviderTokenEndpoint https://phabricator.example.com/oauthserver/token/
OIDCProviderTokenEndpointAuth client_secret_post
OIDCProviderUserInfoEndpoint https://phabricator.example.com/api/user.whoami
OIDCUserInfoTokenMethod post_param
OIDCProviderUserInfoResponseSubkey result
OIDCORemoteUserClaim userName


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

Support

Some support resources below for the upstream project may help with any queries you have, but please feedback any issues related to OAuth 2.0 Code Authorization Grant to https://github.com/make-all/mod_auth_openidc through the github issue tracker.

See the Wiki pages with Frequently Asked Questions at:
https://github.com/zmartzone/mod_auth_openidc/wiki
There is a Google Group/mailing list at:
mod_auth_openidc@googlegroups.com
The corresponding forum/archive is at:
https://groups.google.com/forum/#!forum/mod_auth_openidc
Any questions/issues should go to the mailing list.

Commercial Services

For commercial support and consultancy you can contact:
Globus and more

Disclaimer

The upstream software is open sourced by OpenIDC, subsidiary of ZmartZone Holding B.V.. For commercial support, please use the upstream version and you can contact OpenIDC as described above in the Support section.

Any questions/issues for this fork should go to the Github issues tracker directly.