Summary

This document will guide you through the steps to enable multi-factor authentication and Single-Sign On for the Apache 2.x authentication/authorization module mod_auth_openidc (https://github.com/zmartzone/mod_auth_openidc) using OpenID Connect to integrate with PhenixID Authentication Services.

mod_auth_openidc is an OIDC Relying party (RP) can be used to easily add strong authentication and authorization to any web application / page hosted on the Apache web server. (For example a simple html page or a tomcat web application).

System Requirements

• PhenixID Authentication Server 3.2 or higher
• Apache web server 2.x with php installed (on Linux OS. For Windows, a commercial agreement with zmartzone for mod_auth_openidc is required).
• (For the simple example page protected below to work, PHP must be installed on the Apache server.)

Instruction

Overview

This document will guide you through the steps to enable multi-factor authentication and Single-Sign on for mod_auth_openidc.

Setup Relying Party trust on PhenixID Authentication Services

1. Login to Configuration Manager
2. Go to Scenarios->OIDC
3. Add a new Relying party
   client_id = rp
   client_secret = password
   redirect_uri = https://<apache server domain>/protected_by_oidc_rp.php/callback

   Change <apache_server_domain> to suite your environment. Example: https://integration.phenixid.se/protected_by_oidc_rp.php/callback

Configure PhenixID Authentication Services as OpenID Connect Provider

1. Setup PhenixID Authentication Services as a OpenID Connect Provider using one of the OIDC scenarios described here. (If the desired authentication method is not provided by a scenario, use the SAML Identity Provider bridge and use applicable SAML scenario to set it up).
2. Use Authorization code flow.
3. Once done, if you need to change token attribute population, please do so below the Execution Flow tab.
4. Select Advanced->OIDC_OP
5. Locate the OpenID Connect Provider created in previous step.
6. Change the token_endpoint_auth_methods_supported to client_secret_post.

   "token_endpoint_auth_methods_supported": [
   "client_secret_post"
   ],

7. Click Stage changes and commit changes.
8. Go back to Scenarios->OIDC and find the OP created in previos step
9. Click View OP Discovery
10. Copy the URL of the page that just opened. This will be used in later step when configuring mod_auth_openidc.

Install mod_auth_openidc

1. Access the server running Apache using SSH
2. Run the command sudo apt-get install libapache2-mod-auth-openidc
   (Follow any instructions that may follow)
3. Run the command sudo a2enmod auth_openidc to enable the new module
4. Run the command service apache2 restart to restart Apache to apply the new setting.

Configure mod_auth_openidc

(In this example below, the simple php page protected_by_oidc_rp.php is protected with OIDC RP authentication. Change this to suite your environment by changing the params OIDCRedirectURI and Location below. The OIDCRedirectURI value must also be added to the PAS RP Trust (allowed redirect uris)

1. Open the Apache main configuration file (httpd.conf or httpd-ssl.conf).
2. Add this to the configuration:

   OIDCProviderMetadataURL https://demo.phenixid.net/oidc/.well-known/openid-configuration
   OIDCClientID rp
   OIDCClientSecret password
   OIDCCryptoPassphrase ChangeThisToAnyValueOfYourChoice
   OIDCRedirectURI https://integration.phenixid.se/protected_by_oidc_rp.php/callback
   OIDCResponseType code
   OIDCScope "openid"
   OIDCSSLValidateServer Off
   OIDCPassClaimsAs environment
   OIDCClaimPrefix USERINFO_
   OIDCPassIDTokenAs payload
   
   <Location "/protected_by_oidc_rp.php">
   Require valid-user
   AuthType openid-connect
   </Location>

   Change the values for:
   – OIDCProviderMetadataURL
   – OIDCCryptoPassphrase (this can be set to any value. Just generate a random value and use that)
   – OIDCRedirectURI
   to suite your environment.

3. Save the changes and restart Apache

Add test page to Apache

1. Create a new file, /var/www/html/protected_by_oidc_rp.php.
2. Add this content:

   <html>
      <body>
         <h1>If you can see this, the OIDC login procedure was successful.</h1>
       <a href="/protected_by_oidc_rp.php/callback?logout=%2Findex.html">Logout</a>
         <H2>OIDC ID TOKEN PAYLOAD:</H2>
         <pre><?php echo str_replace(' ', '&nbsp;', (json_encode(json_decode($_SERVER['OIDC_id_token_payload']), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES))); ?> </pre>
         <H2>All content</H2>
         <pre><?php print_r($_SERVER); ?></pre>
      </body>
   </html>

3. Save the file.

Test

1. Browse to https://<apache server domain>/protected_by_oidc_rp.php
2. You should now be redirected to the PhenixID Authentication Services OpenID Connect Provider
3. Authenticate
4. This page should now be presented.
   The value of OIDC_id_token_payload should contain the id_token claims.

Troubleshooting

• If error message is presented on PhenixID Authentication Services page, please check server.log for details.
• If error message is presented on the OIDC RP, check Apache logs for errors.
• If an error message regaring token type is displayed on the OIDC RP, please add the property “token_type: Bearer” to the token endpoint execution flow.