Public Knowledge Base - WebSSO: Install OpenID Connect module on Linux with Azure SSO

Article Intended For

Penn State students, faculty, staff and other affiliates.

Introduction

Single Sign-On is a feature of Microsoft's Azure Active Directory. Whether you're migrating an existing app from CoSign, or implementing WebSSO on a new app, this article provides step-by-step instructions for:

Installing OpenID Connect (OIDC) on a Linux based machine that runs Apache WebServer with RHEL and CentOS version 7 or 8, and Ubuntu.
Configuring it to use the Penn State's Azure Active Directory tenant for SSO.

Step-by-Step Instructions

Confirm that you have met the following prerequisites:
1. SSL Certificate:
  - This will be used at the web server to protect critical endpoints.
  - It will be seen by users, so it should be trusted by their browsers.
  - Commercial certificates are generally used.
  - If your website does not currently have a valid SSL certificate, visit securecerts.psu.edu to obtain one.
2. Operating System: Redhat or CentOS version 7 or 8, or Ubuntu
3. Web Server: Must have basic Apache installed and configured.
Submit an Azure AD Registration Request:
1. Use the WebSSO Azure App Registration Request form to ask for your app be registered in Azure AD.
2. See knowledge article Register your application with Penn State's Azure AD Tenant to learn how.

Install OpenID Connect:

While you're waiting for registration to be completed:

FOR VERSION 8 RHEL or CENTOS: Install latest release of mod_auth_openidc:
1. Enable the OpenIDC module:
  
  Syntax:
  
  dnf module enable mod_auth_openidc
2. Install OpenIDC:
  
  Syntax:
  
  dnf install mod_auth_openidc

FOR VERSION 7 RHEL OR CENTOS: Download the latest release of the mod_auth_openidc and cjose rpm files from GitHub:

NOTE: The GitHub release is required, as versions included with the base OS are out of date. See footnotes for Ubuntu Install commands. PSU servers leveraging the PSU satellite server, please review footnotes for dependencies and other issues.

Go to https://github.com/zmartzone/mod_auth_openidc/releases
The latest release is listed at the top of the webpage.

Identify and install the latest release of the cjose Java security rpm:
(This is a dependency for the latest release of mod_auth_openidc)

To find the correct file:
1. The latest release of mod_auth_openidc is listed at the top of the webpage.
  Scroll down slightly to the Packaging section under that release.
2. One of the bullets in this section explains that the latest version of the libcjos binaries on which mod-auth-openidc depends can be found further down the page, under an earlier release of mod-auth-openidc.
  Scroll down to the earlier release indicated.
3. Locate the cjose*.rpm file in the Assets section of that earlier release.
  Note that you may need to click the arrow next to the Assets heading to expand that section.
Right click the cjose*.rpm filename and choose Save link as... to save the link to your clipboard.
Log into your server as root (or using an account with sudo privileges).

Install the cjose*.rpm file on your server from a terminal window:If using a satellite server, retrieve the most current version

Syntax:	yum install [link_to_latest_release_of_cjoserpm_file* ]
Example:	yum install https://github.com/zmartzone/mod_auth_openidc/releases/download/<Most recent version available> /cjose-<Most recent version available>.x86_64.rpm

Optional: Use the wget command to save a copy of the file to the desired location on your server:

Syntax:	wget[link_to_latest_release_of_cjoserpm_file* ]
Example:	wget https://github.com/zmartzone/mod_auth_openidc/releases/download/<Most recent version>/cjose-<most recent version available>.x86_64.rpm

Identify and install the latest release of the mod_auth_openidc rpm:

On the GitHub webpage, scroll back up to the Assets section under the latest release.
Right-click the rpm file that begins with mod_auth_openidc and choose Save link as...

Install the mod_auth_openidc*.rpm file on your server: If using a satellite server, retrieve the most current version.

Syntax:	yum install [link_to_latest_release_of_mod_auth_openidcrpm_file*]
Example:	yum install https://github.com/zmartzone/mod_auth_openidc/releases/download/<Most recent version/mod_auth_openidc-<Most recent version>.x86_64.rpm

Optional: Use the wget command to save a copy of the file to the desired location on your server:

Syntax:

wget[link_to_latest_release_of_mod_auth_openidc*rpm_file ]

Example:

wget https://github.com/zmartzone/mod_auth_openidc/releases/download/v2.4.3/mod_auth_openidc-<Most recent version>.rpm

Expand the package: >tar xzvf mod_auth_openidc-<Most recent version>.tar.gz

Change configuration settings in Azure AD:

Once you've been notified that the application has been registered:
1. Log in to the Portal and find your application:
  1. Go to the Azure Portal and log in with your Penn State user ID and password.
  2. Select the tile "The Pennsylvania State University":
    1. On the left hand menu, Select App Registrations.
    2. If you had pre created your App Registration, it should appear in the list under App I own. You can also search for it under all applications.
2. Make UPN claim available:
  1. Select the pre created App Registration for Open ID Connect.
  2. Select the token configuration on the left hand menu.
  3. Add the claim:
    1. Click + Add optional claim. A dialog box opens in the right-hand pane.
    2. Under Token Type, choose ID.
    3. From the list of check boxes that's displayed, choose upn.
    4. Select "Turn on the Microsoft Graph profile permission(required for claims to appear in token)."
    5. Click the blue Add button at the bottom of the pane.
3. Verify and add additional API permissions and request All Access grant for all APIs:
  1. Select the pre created App Registration for Open ID Connect.
  2. Select the API permissions on the left hand menu.
  3. Add additional permissions as required by your application:
  4. You can request the access grant here. It is required.
    1. Under type of request, choose "Need Admin Approval"
    2. Enter the displayname of the application displayed in the Microsoft portal
    3. Enter the list of API permissions requesting
4. Identify the URL to which the identity provider should redirect users after authentication:
  1. Choose Authentication from the menu.
  2. Click +Add platform.
    The Configure Platforms window opens to the right.
  3. Under Web Applications, click the box that says Web.
  4. Under Redirect URI, enter the URL to which the user will be redirected after successful authentication (The host name followed by a virtual folder name of your choosing).
    
    Syntax:
    
    https://hostname/virtual_folder/redirect_uri
    
    Example:
    
    https://lost-puppy-dept.psu.edu/valid/redirect_uri
    
    NOTE: The folder you specify here does not need to actually exist; however, if it does exist, it should contain no content.
  5. Make a note of the value you enter, as you will need to reference it when you update the openidc.conf file in a later step.
  6. Click Configure to save the value.
  7. Leave the Azure AD Admin Center open while you continue with the next steps.
5. Optional: (Create a customized flyout portal menu.):
  1. Go to the Azure Portal and log in with your Penn State user ID and password.
  2. If you don't already see a left-hand navigation pane, make it visible:
    1. Click the Settings icon () in the upper right part of your window.
    2. Change the default mode for the portal menu from Flyout to Docked.
    3. Close the Settings window.
  3. Edit Favorites if necessary:
    1. Your left-hand navigation pane should include the following services:
      - Azure Active Directory
      - Enterprise Applications
    2. If it does not, click All Services (near the top of the left-hand navigation pane) and "star" the missing services.
6. Optional: (Configure additional properties.):
  1. Navigate to the Properties screen as follows:
    1. Choose Enterprise Applications from the left-hand navigation pane.
      
      The Enterprise Applications menu is displayed on the left, with menu item All Applications selected.
    2. Find and select your application using the search bar:
      1. Begin typing the display name under which your application was registered, starting with the prefix. Example: Z3-Lost-Puppy-Website. To find this value, check the notification you received that your registration was complete.
      2. Select your application from the search results.
        The Enterprise Application menu is displayed on the left, with menu item Overview selected.
    3. Choose Properties from the menu.
  2. Set User Assignment Required appropriately:
    1. To enable access control via Azure groups, leave this property set to Yes.
      Setting this property to Yes means that users will only be able to access the application if they are members of a group to which you assign access through Azure AD.
    2. To control access at the application level, change it to No.
      Setting this property to No means that any user who navigates to the application URL or deep link URL will be granted access; any further access control required must be handled within the application itself.
  3. Set Visible to Users property:
    1. To make the application visible on the Office 365 App Launcher, leave the default value of Yes.
    2. To prevent the application from showing up on the Office 365 App Launcher, change the value to No.
  4. Click the Save icon near the top of the page to save any property changes.

Create and customize the OIDC configuration file:

Create a file named openidc.conf under /etc/httpd/conf.d, and paste the following template into it, might require running a sudo:
(For Ubuntu, this file will be autocreated: /etc/apache2/mods-enabled/auth_openidc.conf)

# Next is only for httpd > 2.4, otherwise just "debug" if needed:
# LogLevel auth_openidc:debug

#LoadModule auth_openidc_module modules/mod_auth_openidc.so

OIDCProviderMetadataURL https://login.microsoftonline.com/7cf48d45-3ddb-4389-a9c1-c115526eb52e/v2.0/.well-known/openid-configuration
OIDCSSLValidateServer Off

OIDCRemoteUserClaim upn ^(.*)@
OIDCScope "openid profile"
# Next skips "Sign In" window:
OIDCPathAuthRequestParams "domain_hint=psu.edu"
# Next needed if many claims or a large one (e.g., group list) are being sent:
# OIDCCacheShmEntrySizeMax 21504

OIDCClientID Your-Azure-App-ID
OIDCClientSecret "Your-Azure-App-client-secret"
OIDCCryptoPassphrase "A-random-passphrase-known-only-to-this-module"

# For debugging/seeing session info. Can be removed for production:
# OIDCInfoHook iat access_token access_token_expires id_token userinfo refresh_token session

OIDCRedirectURI /your_apache_server_url/virtual_folder/redirect_uri

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

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

Protect the keys you store in /etc/httpd/conf.d/openidc.conf by setting the file permissions so that it is not readable outside of the server processes and admin team.

Example (on systems like RHEL that prefer root.apache user/group ownership and readability):

Command:	sudo chown root.apache /etc/httpd/conf.d/openidc.conf sudo chmod 440 /etc/httpd/conf.d/openidc.conf
Check Result:	ls -l /etc/httpd/conf.d/openidc.conf
Result:	-r--r----- 1 root apache 1159 Mar 16 11:15 /etc/httpd/conf.d/openidc.conf

Get your application ID from the Azure AD Admin Center and use it to update the openid.conf file into which you just pasted the template:

Choose Overview from Azure AD Admin Center App Registrations menu (the menu displayed when you choose App Registrations, then search for your app).
Copy the value shown under Application (client) ID.

Paste it into the OIDCClientID field in the openid.conf file, replacing Your-Azure-App-ID:

Find this line:	OIDCClientID Your-Azure-App-ID
Edit as follows:	Replace Your-Azure-App-ID with the value you copied from the Azure AD app.
Example :	OIDCClientID 123456x1-12f3-4c21-121e-2333d43215a5

Use Azure AD Admin Center to generate client secret and put it into the openid.conf file.

Back in the Azure AD Admin Center, choose Certificates and Secrets from the menu.
Click +New client secret. A dialog box opens in the right-hand pane.
Enter the name of the service in the Description box.
Choose Expires in 2 years; then click Add.
The new secret is displayed under Client Secrets.
Use the copy icon to the right of the value to copy the secret you just added.

Paste it into the OIDCClientSecret field in the openid.conf file, replacing "Your-Azure-App-client-secret": By default this is set to expire in 6 months, you can adjust it to the max of 24 months.

Find this line:	OIDCClientSecret "Your-Azure-App-client-secret"
Edit as follows:	Replace "Your-Azure-App-client-secret" with the value you copied from Azure AD.
Example:	OIDCClientSecret "Ax=mPQ=rJO5fE32abW5RMW:@mTEIFMmt"

Set OIDCryptoPassphrase to random value:

Generate a random value from the command line:
Command:
openssl rand -base64 24

Copy the resulting random alpha-numeric string and paste it under OIDCCryptoPassphrase:

Find this line:	OIDCCryptoPassphrase "A-random-passphrase-known-only-to-this-module"
Edit as follows:	Replace "A-random-passphrase-known-only-to-this-module" with the random value.
Example:	OIDCCryptoPassphrase "G3xIrewcglT3KE9KwKCw4Eqo+U+5Q"

Identify areas of the website that require authentication:

Identify OIDCRedirectURI:

Find this line:	OIDCRedirectURI /virtual_folder/redirect_uri
Edit as follows:	Replace "your_apache_server_url/virtual_folder" with the "vanity url" you entered as the redirect URL in Azure AD, during step 4D, above. That is, the URL to which the user will be redirected after successful authentication (e.g., the host name), followed by a virtual folder name of your choosing. The folder you specify here does not need to actually exist; however, if it does exist, it should contain no content. Keep the "redirect_uri" at the end.
Example:	OIDCRedirectURI /valid/redirect_uri

Identify the location of the virtual folder:

Find these lines:	<Location /virtual_folder> AuthType openid-connect Require valid-user </Location>
Edit as follows:	Replace /virtual with the same folder name you specified for OIDCRedirectURI.
Examples:	<Location /virtual_folder> AuthType openid-connect Require valid-user </Location>

Define the path(s) of content to which access controls are to be applied:

Find these lines:

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

Edit as follows:

Replace /path_to_protect with the location to be protected. For more examples on protecting multiple paths. Refer to here

Examples:

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

OR (to specify the root):

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

Restart Apache.

Confirm success:

Go to your website and try logging in.

If you still have questions or need additional assistance, please submit a WebSSO General Request form.

Ubuntu install notes:

Install command for OIDC :>apt-get install libapache2-mod-auth-openidc
Enable module after install :>a2enmod auth_openidc
Ubuntu auto generates the openidc.conf file and it is located under /etx/apache2/mods-enabled/auth_openidc.conf

Install Error on Redhat with PSU Satellite server: Can not resolve dependency hiredis

Resolution:
List all subscribed repos: subscription-manager repos --list
Enable the EPEL repo: subscription-manager repos --enable=UPSYSENG_Extra_Packages_for_Enterprise_Linux__EPEL__EPEL_RHEL_7_x86_64
Refresh the repolist: subscription-manager refresh
Flush yum cache: yum clean all
List all subscribed repos again to confirm EPEL has Enabled: 1: subscription-manager repos --list

Diagnostics and logs:

Enable info hook for diagnostics

Find this line:	# OIDCInfoHook iat access_token access_token_expires id_token userinfo refresh_token session
Edit as follows:	Remove the comment symbol from the beginning of the line "#", restart Apache
Example:	OIDCInfoHook iat access_token access_token_expires id_token userinfo refresh_token session

Logs are generally stored in the ssl_access_log
Example line:
198.51.100.10 - RemoteUserValue [00/Jan/2020:00:00:00 -0500] "GET /valid/redirect_uri?info=html HTTP/1.1" 200 8106

Syntax:	https://hostname/virtual_folder/redirect_uri
Example:	https://lost-puppy-dept.psu.edu/valid/redirect_uri