Home
Take a look at the (simple) examples in the README.md first:
https://github.com/OpenIDC/mod_auth_openidc/blob/master/README.md
For an exhaustive overview of all configuration options, see:
https://github.com/OpenIDC/mod_auth_openidc/blob/master/auth_openidc.conf
Here are some walkthrough articles on the web for a configuration against Google:
https://github.com/OpenIDC/mod_auth_openidc/wiki/Useful-Links
This is usually a problem with the Cookie settings. Make sure that your OIDCRedirectURI is a path that is protected by mod_auth_openidc, also make sure that the target URL that you access matches the <proto>://<host>/<path> setting of OIDCRedirectURI and (when in use) make sure you align the OIDCCookiePath and/or OIDCCookieDomain settings with both the OIDCRedirectURI and the target application URL as well.
See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Sessions-and-Timeouts
and: https://github.com/OpenIDC/mod_auth_openidc/wiki/Caching
See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Access-Tokens-and-Refresh-Tokens
By adding additional scopes in the OIDCScope setting as in:
OIDCScope "openid email profile"(the openid scope always needs to be part of the requested scopes)
In a multi-provider setup this setting functions as the default and you can override it for a specific provider in the .conf file for that provider using the scope key, e.g.
"scope": "openid email profile"
The headers are not passed to the browser; they are set server-side only and can only be read by the protected application. This is for (obvious) security reasons and in fact any suspicious headers (i.e. starting with OIDC_ or the configured OIDCClaimPrefix) set by the browser will be scrubbed.
Yes, you may have to fiddle (or not) with the module loading order but it will work. In fact this is a primary usecase that allows you to deploy an Apache Proxy in front of the applications you want to protect so you can enable OpenID Connect authentication for your applications without touching the application's code. The user identity information will be passed to your application in HTTP headers (and, if enabled, the REMOTE_USER header).
mod_auth_openidc can be deployed behind a proxy by having that proxy pass in the X-Forwarded-Proto and X-Forwarded-Port headers to make mod_auth_openidc aware of the external protocol (http/https) and port that browsers use to access the protected application. The proxy also needs to preserve the Host header that is sent by the browser, e.g. in an Apache Proxy one would use ProxyPreserveHost configuration primitive to do that. Alternatively the proxy can send the original hostname in the X-Forwarded-Host header.
Since version 2.4.11rc0 the module needs to be explicitly configured to interpret the headers above e.g. with:
OIDCXForwardedHeaders X-Forwarded-Host
You can kill the session from your application by redirecting the user to the OIDCRedirectURI with a parameter named logout. The value of that parameter contains the (URL-encoded) URL where the user will be redirected to after the session has been killed. In case of a front channel logout the browser is redirected to the end_session_endpoint of the OP with the post_logout_redirect_uri being set to the given URI. For example, a logout link on the protected HTML page could look like:
<a href="/protected/redirect_uri?logout=https%3A%2F%2Flocalhost%2Floggedout.html">Logout</a>Note: make sure that the (URL-encoded) callback URL passed in the logout parameter points to a location that is not protected by mod_auth_openidc or else the login process will be started again... (and most likely SSO will occur).
If the OP supports Session Management then the user will be redirected to the Provider for logout as well.
If the OP supports Front Channel Logout mod_auth_openidc can respond to Logout request initiated by the Provider. In that case the frontchannel_logout_uri for the mod_auth_openidc Client should be configured to <OIDCRedirectURI>?logout=get.
If the OP supports Back Channel Logout the backchannel_logout_uri for the mod_auth_openidc Client should be configured to <OIDCRedirectURI>?logout=backchannel.
If the OP is PingFederate and the "OpenID Connects Settings" in the "Authorization Server Settings" have been configured with "Track User Sessions for Logout", then the "Logout URIs" for the *mod_auth_openidc Client should be set to <OIDCRedirectURI>?logout=img.
Here's a minimal PHP sample application:
<html>
<body>
<h1>Hello, <?php echo($_SERVER['REMOTE_USER']) ?></h1>
<pre><?php print_r(array_map("htmlentities", apache_request_headers())); ?></pre>
<a href="/protected/redirect_uri?logout=https%3A%2F%2Flocalhost%2Floggedout.html">Logout</a>
</body>
</html>You can download pre-built binary packages for common recent releases of Debian/Ubuntu and CentOS/Redhat from the Github Releases pages.
mod_auth_openidc is also available through the package repositories of various Linux distributions through typically that results in an older version.
FreeBSD users can use one of the following two options to install mod_auth_openidc:
- To install the port:
cd /usr/ports/www/mod_auth_openidc/ && make install clean - To add the package:
pkg install ap24-mod_auth_openidc
Basically the answer is in the README.md (see OIDCDiscoverURL). Below is a simple example of a custom static discovery page in plain HTML where metadata for the (2) providers has been preconfigured in OIDCMetadataDir and a static deep link target (/protected/index.html) is used:
<html><body>
<p><a href="https://localhost/protected/?iss=accounts.google.com&target_link_uri=https%3A%2F%2Flocalhost%2Fprotected%2Findex.html">
Google</a></p>
<p><a href="https://localhost/protected/?iss=seed.gluu.org&target_link_uri=https%3A%2F%2Flocalhost%2Fprotected%2Findex.html">
Gluu</a></p>
</body></html>Note: if you want to preserve POST data across authentication requests (see: OIDCPreservePost for versions >= 2.0) you'll need to accept and return a dynamic method parameter as well, so that requires a setup that is able to parse and return HTTP query parameters like below.
Next is a more advanced PHP example that reads dynamically registered metadata from OIDCMetadataDir (/var/cache/mod_auth_openidc/metadata/) and provides OpenID Connect Provider Discovery and uses a dynamic deep link target:
<html><body>
<?php
$oidc_callback = $_GET['oidc_callback'];
$metadata_dir = '/var/cache/mod_auth_openidc/metadata/';
if ($handle = opendir($metadata_dir)) {
while (false !== ($entry = readdir($handle))) {
$type = ".provider";
$len = strlen($type);
if (substr($entry, -$len) !== $type) continue;
$json = json_decode(file_get_contents($metadata_dir . $entry));
echo '<p><a href="' . htmlspecialchars($oidc_callback . "?iss=" . urlencode($json->issuer) . "&" . $_SERVER['QUERY_STRING']) . '">' . htmlspecialchars($json->issuer) . '</a></p>';
}
closedir($handle);
}
?>
<form method="GET" action="<?php echo $oidc_callback ?>">
<p>Or enter your account name, your IDP identifier or your IDP's domain name:</p>
<input type="text" name="iss">
<?php
foreach ($_GET as $key => $value) {
echo '<input type="hidden" name="' . $key . '" value="' . $value . '">';
}
?>
<button type="submit">Submit</button>
</form>-
a. When using a single statically configured provider, you can add one ore more URL-encoded
<name>=<valueparameters to theOIDCAuthRequestParamsin the Apache configuration, as in:OIDCAuthRequestParams hd=example.com&approval_prompt=force
-
b. If you're using multiple OPs you can create a file named
<url-encoded-issuer>.confin the metadata directory and set theauth_request_paramsparameter so that it looks like:{ "auth_request_params" : "<param-name1>=<urlencoded-param-value1>&<param-name2>=<urlencoded-param-value2>&<etc.>" }The setting for
OIDCAuthRequestParamswill function as the default for multiple OPs when no explicitauth_request_paramshas been set for an OP. -
c. When using multiple OPs and you need to pass in parameters determined at runtime during the discovery phase, you can use additional mod_auth_openidc specific parameter named
auth_request_paramsin the discovery response, as in:<oidc_callback>?target_link_uri=<target_link_uri>&iss=[<issuer>|<domain>|<e-mail-style-account-name>][&login_hint=<name>][&auth_request_params=<urlencoded-query-string>]
Its value would contain dynamically determined custom parameters that need to be passed in the authorization requests and as such it is the runtime equivalent of the static OIDCAuthRequestParams configuration value and the auth_request_params in the .conf file. If you use more than one of the previous settings you'll need to make sure they do not conflict. Note that nested URL encoding is required e.g. passing both prompt=consent and max_auth_age=0 would result in:
auth_request_params=prompt%3Dconsent%26max_auth_age%3D0
-
d. Lastly and deprecated, for versions of mod_auth_openidc older than 1.6.0 and configurations that don't use
OIDCProviderMetadataURLor need to override theauthorization_endpointsetting in there, you can also set theOIDCProviderAuthorizationEndpointand add parameters to that, as in:OIDCProviderAuthorizationEndpoint https://accounts.google.com/o/oauth2/auth?hd=example.com&approval_prompt=force
Since version 2.3.0 there is also an option to add custom parameters to the authentication request based on the path that is accessed with OIDCPathAuthRequestParams, typically used to realize step-up authentication scenario's, see: https://github.com/OpenIDC/mod_auth_openidc/wiki/Step-up-Authentication
Since version 2.3.11rc1 one can pass on query parameters from the request to the authorization request by adding e.g. "foo=#" which which will dynamically pull in the query parameter value from the request query parameter and add it to the authentication request to the OP, as in:
OIDCAuthRequestParams "login_hint=#&kc_action=#"Yes, by using a custom parameter in the authentication request as described in the previous question. For Google accounts one can add the "openid.realm" parameter to the authentication request with the value of your OpenID realm to obtain OpenID 2.0 identifiers for migration purposes as described in #29. The OpenID 2.0 identifier will be returned in the openid_id claim and it will be passed in the HTTP header OIDC_CLAIM_openid_id. For Google documentation on the migration, see: https://developers.google.com/accounts/docs/OpenID#openid-connect
Yes, the functionality as specified in OpenID Connect Session Management draft 21 was added since release 1.6.0, see: https://github.com/OpenIDC/mod_auth_openidc/wiki/Session-Management.
Listen 443
User www
Group www
DocumentRoot <path>
ErrorLog "logs/error_log"
LogLevel info
ServerName <hostname>
LoadModule ssl_module modules/mod_ssl.so
LoadModule auth_openidc_module modules/mod_auth_openidc.so
<VirtualHost _default_:443>
SSLEngine on
SSLCertificateFile <path>
SSLCertificateKeyFile <path>
SSLCertificateChainFile <path>
OIDCProviderMetadataURL <url>
OIDCClientID <client_id>
OIDCClientSecret <client_secret>
OIDCCryptoPassphrase <password>
OIDCRedirectURI https://<hostname>/redirect_uri
<Location "/">
AuthType openid-connect
Require claim sub:<userid>
</Location>
</VirtualHost>In some environments it is not possible to connect directly to the Internet. If this is the case, it will prevent Apache from retrieving the OIDCProviderMetadataURL and result in an HTTP 500 error. You will see these messages in Apache's error log:
oidc_util_http_call: curl_easy_perform() failed on: https://my.op.org/.well-known/openid-configuration (Failed to connect to my.op.org port 443: Connection refused)
Such environments may deploy HTTP proxies to offer outside connectivity, for instance by setting the environment variables http_proxy or https_proxy.
You might need to explicitly configure Apache to use these in your vhost configuration:
SetEnv https_proxy "http://proxy.example.com"You will also need to set OIDCOutgoingProxy as documented here: https://github.com/OpenIDC/mod_auth_openidc/blob/v2.4.12.3/auth_openidc.conf#L839-L842
See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Cookies
Since release 2.4.14 you should use standard Apache ErrorDocument directives to handle the errors that come in as environment variables. The following variables are available:
-
REDIRECT_OIDC_ERRORcontains the error message -
REDIRECT_OIDC_ERROR_DESCcontains a description of the error -
REDIRECT_OIDC_AUTHZ_ERRORcontains a description of the scopes that did not match in case of aRequire claimauthorization error resulting in aHTTP 403 Forbiddenresponse
Use of the OIDCHTMLErrorTemplate configuration directive is deprecated since version 2.4.14.
Because you neglected, did not read and deliberately deleted the text that showed up in the issue template when you created the issue. As mentioned in the README.md, the issue tracker is not for end users, the Discussons forum is for questions and discussions. This means that the issue tracker:
- is NOT for questions in general, this includes questions about configuration, behavior, etc.
- is NOT for questions about your specific setup, environment or operating system package manager
- is NOT for questions about other products or interoperability with those
- is NOT for remarks about how good or bad mod_auth_openidc is
- is NOT for remarks about how bad the author is to neglect your question, not giving you support for free and how you won't use mod_auth_openidc at all now because it really sucks
If you have concluded that you've found a bug or a valid non-existing feature request, you must confirm this on the Discussons forum, and provide exhaustive information about your setup.