How To Set Up SSO in Apache using Mellon and Azure AD on Ubuntu

This guide will show you how to integrate Azure Active Directory authentication in Apache and enable single sign-on (SSO) for your cloud-based system, software and applications.

 

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. 

 

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. 

 

Mellon is an authentication module for Apache. It authenticates the user against a SAML 2.0 IdP, and grants access to resources depending on attributes received from the identity provider (IdP). 

 

Azure AD 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. 

 

Prerequisites

To follow this tutorial along, you will need one (physical or virtual) machine installed with Ubuntu or Debian. This guide also assume that your Azure Active Directory has already been properly configured.

 

Install Required Packages

Login to your Linux system with a non-root sudo user privileges and install these important packages:

sudo apt -y install openssl apache2 libapache2-mod-auth-mellon ntpdate php php-fpm

 

Configure Mellon

Create a directory under /etc/apache2/ location to store your mellon metadata files:

sudo mkdir -p /etc/apache2/mellon
cd /etc/apache2/mellon

Execute below script to generate mellon metadata files:

sudo /usr/sbin/mellon_create_metadata https://mywebserver.example.com/ "https://mywebserver.example.com/mellon"

You should rename these three files like below:

sudo mv *.key mellon.key
sudo mv *.cert mellon.cert
sudo mv *.xml mellon_metadata.xml

If the "mellon_create_metadata" fails to generate the XML metadata file, you should edit it and comment out the "set -e" line:

sudo nano /usr/sbin/mellon_create_metadata

Comment out the set -e line:

# set -e

Save and close the editor when you are finished.

Execute the "mellon_create_metadata" script again as described above to generate XML metadata file.

 

Create a mellon configuration file like below:

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

Enter configuration directives like below:

<location />
MellonSPPrivateKeyFile /etc/apache2/mellon/mellon.key
MellonSPCertFile /etc/apache2/mellon/mellon.cert
MellonSPMetadataFile /etc/apache2/mellon/mellon_metadata.xml
MellonIdPMetadataFile /etc/apache2/mellon/AzureAD_metadata.xml
MellonEndpointPath /mellon
MellonEnable "info"
</Location>

Save and close the editor when you are finished.

 

Type below command to generate a self-signed SSL certificate: 

sudo openssl req -newkey rsa:3072 -new -x509 -days 3652 -nodes -out /etc/ssl/certs/mywebserver.pem -keyout /etc/ssl/private/mywebserver.key

Enter appropriate information on the following prompts:

Country Name (2 letter code) [AU]:Your_Country
State or Province Name (full name) [Some-State]:Your_Province
Locality Name (eg, city) []:Your_City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your_Organization
Organizational Unit Name (eg, section) []:Your Department
Common Name (e.g. server FQDN or YOUR name) []:mywebserver.example.com
Email Address []:your_email_address

 

Create a Apache configuration file:

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

Enter configuration directives like below:

<IfModule mod_ssl.c>
<VirtualHost _default_:443>
DocumentRoot /var/www/html
ServerSignature Off
ErrorLog /var/log/apache2/error.log
CustomLog /var/log/apache2/access.log combined
LogLevel info ssl:warn

SSLEngine on
SSLCertificateFile /etc/ssl/certs/mywebserver.pem
SSLCertificateKeyFile /etc/ssl/private/mywebserver.key
</VirtualHost>

<Location /protected>
Require valid-user
AuthType "Mellon"
MellonEnable "auth"
MellonDecoder "none"
MellonVariable "cookie"
MellonSecureCookie On
MellonUser "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
</Location>
</IfModule>

Save and close the editor when you are finished.

With this configuration, we secures everything under /protected on mywebserver.example.com, providing access to all valid IdP users.

 

Create a directory under your Apache document root folder like below:

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

 

Create a simple index page like below:

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

 

Enter a simple html code like below:

<html>
 <head>
  <title>Index Page</title>
 </head>
 <body>
<h2>This simple index page will only be accessible once your users successfully sign-in via Azure AD with their valid credentials!</h2>
</body>
</html>

Save and close the editor when you are finished.

Test your Apache configuration with below command:

sudo apache2ctl configtest

If everything set up correctly, you will see Syntax OK in the output. If it returns any configuration error, fix them first then proceed to next step.

Activate your Apache configuration with below command:

sudo a2enmod ssl
sudo a2enconf mellon.conf
sudo a2ensite mywebserver.conf
sudo systemctl restart apache2

 

Configure Azure AD

Login to your Azure portal and perform the following steps accordingly:

Navigate to Azure Active Directory > Enterprise application

Click New application

 

Click Create your own application

 

Give a name to your application, or simply enter URL of your application in the box. Select Integrate any other application you don’t find in the gallery (Non-gallery) from the option.
 

Click Create 

 

 

Click Set up single sign on

 

Click SAML

 

Click Upload metadata file 

Click Browse

 

Select your mellon_metadata.xml file. If you remember, this file is created and stored on your Linux system under /etc/apache2/mellon/ directory.

 

Click Add

 

Click Save, then click × sign to close Basic SAML Configuration screen.

 

Click No. I’ll test later

 

Scroll down to Download Federation Metadata XML file from the SAML Signing Certificate section. 

 

Save this federation metadata xml file and rename it as AzureAD_metadata.xml

 

Next, navigate to Properties

 

Change User assignment required from Yes to No, click Save 

 

Next, copy AzureAD_metadata.xml file to your Linux system's /etc/apache2/mellon/ directory.

 

Restart Apache service to take changes into effect:

sudo systemctl restart apache2

 

Open up a web browser and enter the your url like https://mywebserver.example.com/ in the address bar.

 

If everything was set up correctly, you will be redirected to your Azure login page. 

 

When you sign-in with your valid credentials, you will be bounced back to your simple index.html page.

At this stage, your Azure AD integration in Apache on your Linux system successfully completed.

Conclusion

I hope this guide was helpful to integrate your Azure AD authentication in Apache on your Ubuntu or Debian system.