SSO Setup with ModAuthOpenIDC & AzureAD on Ubuntu 20.04

This tutorial will walk you through the steps to set up authentication, authorization and single sign-on in Apache web server using the combination of ModAuthOpenIDC and Azure Active Directory as an identity provider on Ubuntu 20.04.

  • Apache is the most widely-used web server in the world. It provides many powerful features including dynamically loadable modules, robust media support, and extensive integration with other popular software.
  • OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 framework. It allows third-party applications to verify the identity of the end-user and to obtain basic user profile information. OIDC uses JSON web tokens (JWTs), which you can obtain using flows conforming to the OAuth 2.0 specifications.
  • ModAuthOpenidc is a certified authentication and authorization module for the Apache HTTP server that implements the OpenID Connect Relying Party functionality. It relays end user authentication to an identity provider and receives user identity information from that idp. It then passes on that identity information to applications protected by the Apache and establishes an authentication session for the identified user.
  • Single sign-on (SSO) is a property of access control of multiple related, yet independent, software systems. With this property, a user logs in with a single ID and password to gain access to a connected system or systems without using different usernames or passwords, or in some configurations seamlessly sign on at each system.
  • Azure Active Directory (AzureAD) is Microsoft's enterprise cloud-based identity and access management (IAM) solution. It can sync with on-premise Active Directory and provide authentication to other cloud-based systems, and applications via authentication protocols like OAuth2, SAML, and WS-Security.

To follow this tutorial along, you will need a (physical or virtual) machine installed with Ubuntu 20.04.


Install Prerequisites

Log in to your Ubuntu using a non-root user having sudo privileges and perform the following steps.

Type following command to set correct timezone:

sudo timedatectl set-timezone Asia/Karachi

Make sure you replace the highlighted text with yours.

Type following command to install Apache, ModAuthOpenidc and other important packages on your Ubuntu:

sudo apt install -y apache2 libapache2-mod-auth-openidc php php-fpm

At this stage, you have installed all the required packages on your Ubuntu.


Register an App with Azure Active Directory

To integrate Azure Active Directory authentication in Apache,  you need to register your application with Azure and obtain required information so that you can configure your Apache web server using that information. 

Log in to your Azure Portal and navigate to Azure Active Directory as show in images below:


Click on App registrations


Click on New registration 

On the following screen:

  • Enter the name of your app in the Name box
  • Select your account type from Supported account types
  • Select Web from Redirect URI drop-down list
  • Enter the URI of your application like
  • Click on Register

From the following screen, you need to copy:

  1. Application (client) ID
  2. Directory (tenant) ID

and paste it on notepad as you need them later to configure your Apache web server.

Click on Certificates & secrets

Click on New client secret

On the following screen:

  • Enter description of your app in the Description box
  • Select an expiry period from the Expires drop-down list 
  • Click on Add

On the following screen, you must copy the Value of the client secrets and paste it on notepad as you need it for your Apache configuration later.

Remember: once you close the above screen, you will not be able to read client secrets value again, as it will be converted to asterisks for security reason, so make sure you write it down on notepad before closing the above screen.

Navigate to Token configuration then click on Add optional claim

On the following screen:

  • Select ID
  • From Claim select upn
  • Click on Add

On the following screen

  • Tick Turn on the Microsoft Graph profile 
  • Click Add

At this stage, you have successfully completed app registration process on your Azure, and you are now ready to configure your Apache web server to integrate Azure Active Directory authentication for your application.


Configure ModAuthOpenid in Apache

Log in to your Ubuntu, and perform the following steps to configure ModAuthOpenidc, and Apache web server.

Create an openidc.conf file in the Apache root configuration /etc/apache2/conf-available directory:

sudo nano /etc/apache2/conf-available/openidc.conf

Add following directives:

OIDCProviderMetadataURL Your Azure Tenant ID Here/.well-known/openid-configuration
OIDCRedirectURI Type Your Redirect URI HERE
OIDCClientID Paste Your Application (client) ID Here
OIDCClientSecret Paste Your Client Secret Here
OIDCCryptoPassphrase "exec:/bin/bash -c \"head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32\""
OIDCRemoteUserClaim upn

Make sure you replace the highlighted text with yours as you have all these information saved on your notepad during azure app registration process:

  • OIDCProviderMetadataURL should have your azure tenant ID
  • OIDCRedirectURI should be the same URI you configured in Azure app registration step.
  • OIDCClientID should have your Application (client) ID.
  • OIDCClientSecret  should have your app client secret.
  • OIDCCryptoPassphrase either you can type a strong password or use the command to generate random password as it is not good idea to keep password in clear text format.
  • OIDCRemoteUserClaim should have upn as you selected it in claim type in azure app registration.


Create a self-signed SSL certificate

You can obtain digital certificate from your certificate provider i.e. VeriSign, DigiCert, etc. Since this is our test environment, we will create a self-signed SSL certificate to be used with url:

sudo nano /etc/apache2/ssl.cnf

Add following directives:

default_bits = 2048
default_keyfile = private.key
distinguished_name = req_distinguished_name
prompt = no
commonName =

Make sure you replace the highlighted text with yours. Save and close the editor when you are finished.

Execute following command to create a self-signed SSL certificate:

cd /etc/apache2

sudo openssl req -utf8 -batch -config "ssl.cnf" -new -x509 -days 3652 -nodes -out "myapp.crt" -keyout "myapp.key"


Create Apache VirtualHost

We will create myapp.conf file in Apache /etc/apache2/sites-available directory to declare URL:

sudo nano /etc/apache2/sites-available/myapp.conf

Add following directives:

<VirtualHost *:443>
DocumentRoot /var/www/html

ErrorLog /var/log/apache2/oidc/error.log
CustomLog /var/log/apache2/oidc/access.log combined

SSLEngine on
SSLCertificateFile /etc/apache2/myapp.crt
SSLCertificateKeyFile /etc/apache2/myapp.key

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

Make sure you replace the highlighted text with yours. Save and close the editor when you are finished.

Create a protected directory in /var/www/html to host your app contents:

sudo mkdir -p /var/www/html/protected

We do not have any application to host but for demonstration purpose we will create a sample index page in /var/www/html/protected directory:

sudo nano /var/www/html/protected/index.html

Add sample html code:

<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Index Page</title>
<h2>Welcome to sample index page!</h2>
<h3>This is to confirm that your ModAuthOpenIDC and AzureAD authentication working perfectly fine.</h3>

Save and close the editor when you are finished.

Create a sample info.php page as well:

sudo nano /var/www/html/protected/info.php

Add sample php code:

<?php session_start(); ?>
<h2>Remote User Claim</h2>
<div class="row">
<table class="table" style="width:80%;" border="1">
<?php foreach ($_SERVER as $key=>$value): ?>
<?php if ( preg_match("/OIDC_/i", $key) ): ?>
<td data-toggle="tooltip" title=<?php echo $key; ?>><?php echo $key; ?></td>
<td data-toggle="tooltip" title=<?php echo $value; ?>><?php echo $value; ?></td>
<?php endif; ?>
<?php endforeach; ?>

Save and close the editor when you are finished.

Create a directory in /var/log/apache2 to store your Apache VirtualHost logs:

sudo mkdir -p /var/log/apache2/oidc

Type following command to verify Apache configuration:

sudo apache2ctl configtest

You will see Syntax OK in the output if everything goes well. If there is any error, fix them first, then proceed to next step.

Type following command to activate Apache configuration:

sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php*-fpm
sudo a2enmod ssl
sudo a2enconf openidc
sudo a2ensite myapp.conf

Restart Apache to take the changes effect:

sudo systemctl restart apache2

At this stage your Apache, and ModAuthOpenidc configuration is completed.


Test Apache, ModAuthOpenidc and Azure AD Authentication

Open a web browser and enter your application URL for example, in the address bar:

This will take you to your Azure AD login page where you can log in using valid credentials:

Upon successful authentication, you will be redirected to your sample index page as you can see in the screenshot below:

You can see your logged in user detail by accessing in the browser address bar.

The info.php is just for testing purpose, you should remove it from your Apache when you are finished testing your authentication configuration.



I hope this guide was helpful to configure authentication, authorization and single sign-on in Apache web server using ModAuthOpenIDC and Azure Active Directory to secure your browser based application. 

We highly appreciate if you take a moment and tell us about this tutorial in the comment section below.

No comments:

Powered by Blogger.