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. 


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 ""
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"
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) []
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

<Location /protected>
Require valid-user
AuthType "Mellon"
MellonEnable "auth"
MellonDecoder "none"
MellonVariable "cookie"
MellonSecureCookie On
MellonUser ""
Save and close the editor when you are finished.

With this configuration, we secures everything under /protected on, 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:
<title>Index Page</title>
<h2>This simple index page will only be accessible once your users successfully sign-in via Azure AD with their valid credentials!</h2>
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 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.


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


  1. Thank you for sharing this information and it did help. Is it possible to restrict external ip address to authenticate only and bypass local ip address?

    1. This might help you:

  2. Is there a way in the index.html to know who is connected?

    1. Yes, there is a php code that you can use in your idex.html to see logged in user, search google for php code.

    2. Here is the workaround:

  3. AnonymousMay 17, 2022

    Didn't find the attribute "Name" in the attributes which were received from the IdP

    1. AnonymousMay 17, 2022

      Change value of the below parameter:

      MellonUser “Name”


      MellonUser “”

  4. AnonymousJune 01, 2022

    Hello, when I try to use the "mellon_create_metadata" I can't, because it's not found

    1. AnonymousJune 01, 2022

      You can find the exact path of the script with:

      sudo find / -name mellon_create_metadata

  5. AnonymousMay 09, 2023

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

    1. Missing XML metadata file only happens if you are working on Ubuntu 22.04, and thank you for suggesting workaround. This fixes the issue and I have updated the tutorial as well.


Powered by Blogger.