Skip to content

Home

Jump to bottom Edit New page
Hans Zandbelt edited this page Nov 26, 2024 · 96 revisions

Frequently Asked Questions

1. How do I configure mod_auth_openidc?

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

2. After authentication with my Provider there's an error on return.

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.

3. What about sessions, timeouts and caching?

See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Sessions-and-Timeouts
and: https://github.com/OpenIDC/mod_auth_openidc/wiki/Caching

4. How can I use the Access Token and Refresh Tokens?

See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Access-Tokens-and-Refresh-Tokens

5. How can I get more claims from the OpenID Connect Provider?

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"

6. Why don't I see any HTTP headers being set in my browser?

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.

7. Will mod_auth_openidc work when combined with Apache Proxy modules (mod_proxy_*)?

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).

8. How do I run mod_auth_openidc behind a (reverse) proxy?

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

9. How do I logout users?

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.

10. Can you show me a simple application?

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>

11. Where can I get binary packages?

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

12. How can I customize the IDP Discovery (or: initial login) page?

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&amp;target_link_uri=https%3A%2F%2Flocalhost%2Fprotected%2Findex.html">
      Google</a></p>
  <p><a href="https://localhost/protected/?iss=seed.gluu.org&amp;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>

13. How can I add custom parameters to the authorization request?

  • a. When using a single statically configured provider, you can add one ore more URL-encoded <name>=<value parameters to the OIDCAuthRequestParams in 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>.conf in the metadata directory and set the auth_request_params parameter so that it looks like:

      {
    "auth_request_params" : "<param-name1>=<urlencoded-param-value1>&<param-name2>=<urlencoded-param-value2>&<etc.>"
  }

    The setting for OIDCAuthRequestParams will function as the default for multiple OPs when no explicit auth_request_params has 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_params in 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 OIDCProviderMetadataURL or need to override the authorization_endpoint setting in there, you can also set the OIDCProviderAuthorizationEndpoint and 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=#"

14. Does mod_auth_openidc provide migration of Google's OpenID 2.0 identifiers to OpenID Connect?

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

15. Does mod_auth_openidc implement OpenID Connect Session Management?

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.

16. What does a minimal Apache configuration file look like?

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>

17. Restricted web server environments

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

18. How do the state and session cookies work?

See: https://github.com/OpenIDC/mod_auth_openidc/wiki/Cookies

19. How do I customize the user-facing error pages?

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_ERROR contains the error message
  • REDIRECT_OIDC_ERROR_DESC contains a description of the error
  • REDIRECT_OIDC_AUTHZ_ERROR contains a description of the scopes that did not match in case of a Require claim authorization error resulting in a HTTP 403 Forbidden response

Use of the OIDCHTMLErrorTemplate configuration directive was deprecated in versions >= 2.4.14 and removed since version 2.4.16.2.

20. Why is my ticket closed as invalid?

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.

21. How can I identify mod_auth_openidc?

An external entity (user, provider) can observe the protocol flow to find out that it is interacting through mod_auth_openidc in the following ways:

  • client side: by inspecting the state cookie(s) in the browser,
    their name is prefixed with mod_auth_openidc_state_ unless the default is modified with OIDCStateCookiePrefix

  • client side: by inspecting the session cookie(s) in the browser,
    named mod_auth_openidc_session unless the default is modified with OIDCCookie

  • client/provider side: by inspecting the fixed order of the parameters in an authentication request:
    response_type, scope, client_id, state, redirect_uri, nonce, code_challenge, code_challenge_method, response_mode, login_hint, id_token_hint, <extra-configured-parameters>

  • provider side: by inspecting the fixed order of the parameters in the token request:
    grant_type=authorization_code, code, redirect_uri, code_verifier, <extra-configured-parameters>

  • provider side (since version 2.4.15): by inspecting the User-Agent header in backchannel interactions (i.e. token request, userinfo request) with the provider. set to [<ip-address>:<port>:<process-id>] <mod_auth_openidc-version> <curl-version> <openssl-version> e.g. [172.17.0.3:443:16] mod_auth_openidc-2.4.16.5 libcurl-7.81.0 openssl-3.0.2

Add a custom footer
Add a custom sidebar
Clone this wiki locally