Configure Apache SSO using Mellon, ADFS on CentOS, RHEL 7, 8

This tutorial will show you how to configure Single-Sign-On (SSO) in Apache using Active Directory Federation Service (AD FS) as an identity provider and mod_auth_mellon as a service provider on CentOS, RHEL Linux.

 

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. 

 

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. 

 

mod_auth_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). 

 

Active Directory Federation Services (ADFS) is a software component developed by Microsoft that can be installed on Windows Server operating systems to provide users with single sign-on access to systems and applications located across organizational boundaries.

 

The following information will be used throughout this tutorial:

HOSTNAME		IP ADDRESS	SERVICES	OS
idp.techsupportpk.com	192.168.10.10	ADDS, ADFS	Windows 2012 R2
sp.techsupportpk.com	192.168.10.11	Apache, Mellon	Red Hat 7.3

 

Prerequisites

To follow this tutorial along, you will need one (physical or virtual) machine installed with CentOS or RHEL Linux. This guide assume that you already have Active Directory Federation Services (AD FS) in place.

 

For the sake of this guide, we'll use CentOS 7.3 Linux and Windows 2012 R2 for Active Directory Federation Service.

 

Disable Firewall

Log in to your Linux server and execute the following command to stop and disable built-in operating system firewall.

systemctl stop firewalld
systemctl disable firewalld

 

Disable SELinux

Edit /etc/selinux/config and change SELINUX=enforcing to SELINUX=disabled

vi /etc/selinux/config 

SELINUX=disabled

Save and close the editor when you are finished.

Type following command to set FQDN of your system:

hostnamectl set-hostname sp.techsupportpk.com

 

Synchronize system clock with your Active Directory using the below command:

ntpdate -u idp.techsupportpk.com

 

Install Required Packages

Type below command to install EPEL repository on your Linux system to make some extra packages and updates available:

rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Next, install Apache, mod_auth_mellon and other important dependencies:

yum -y install ntpdate httpd mod_ssl mod_auth_mellon php openssl wget

Once installation complete, proceed with the following steps:

mkdir -p /etc/httpd/mellon
mkdir -p /var/www/sp
mkdir -p /var/www/protected
cd /etc/httpd/mellon

Disable SSLEngine parameter by inserting # in the default /etc/httpd/conf.d/ssl.conf file like below:

vi /etc/httpd/conf.d/ssl.conf 

#SSLEngine

Save and close the editor when you are finished.

 

Configure SSL 

Create a self-generated SSL certificate using the following command:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/pki/tls/private/sp.key -out /etc/pki/tls/certs/sp.crt

Make sure you replace the following information to reflect yours:

Country Name (2 letter code) [XX]:PK
State or Province Name (full name) []:Sindh
Locality Name (eg, city) [Default City]:Karachi
Organization Name (eg, company) [Default Company Ltd]:TSPK
Organizational Unit Name (eg, section) []:Technical Support
Common Name (eg, your name or your server's hostname) []:sp.techsupportpk.com
Email Address []:support@techsupportpk.com

Create a sample index.html page like below:

echo Welcome! This is from sp directory > /var/www/sp/index.html
echo Welcome! This is from protected directory > /var/www/protected/index.html

Create a sample info.php page like below:

vi /var/www/sp/info.php

<?php
phpinfo();
phpinfo(INFO_MODULES);
?>

Save and close the editor when you are finished.

 

Configure Mellon

Create mellon metadata using the following command:

cd /etc/httpd/mellon
/usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://sp.techsupportpk.com/ "https://sp.techsupportpk.com/mellon"

The https://sp.techsupportpk.com/ is the (EntityID) in our case, and the https://sp.techsupportpk.com/mellon is the endpoint url. 

 

Type the following commands to rename these three files:

mv *.key mellon.key
mv *.cert mellon.cert
mv *.xml mellon.xml

Next, download ADFS metadata using the following command:

wget https://idp.techsupportpk.com/FederationMetadata/2007-06/FederationMetadata.xml -O /etc/httpd/mellon/FederationMetadata.xml --no-check-certificate

Create a mellon.conf file like below:

vi /etc/httpd/conf.d/mellon.conf

Add configuration directives like below:

<VirtualHost 192.168.105.71:443>
DocumentRoot /var/www/
ServerName  sp.techsupportpk.com

ServerSignature Off
ErrorLog /var/log/httpd/error_sp.log
LogLevel info
CustomLog /var/log/httpd/access_sp.log combined

SSLEngine on
SSLCertificateFile /etc/pki/tls/certs/sp.crt
SSLCertificateKeyFile /etc/pki/tls/private/sp.key
</VirtualHost>

<location />
MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
MellonSPCertFile /etc/httpd/mellon/mellon.cert
MellonSPMetadataFile /etc/httpd/mellon/mellon.xml
MellonIdPMetadataFile /etc/httpd/mellon/FederationMetadata.xml
MellonEndpointPath /mellon
MellonEnable "info"
</Location>

<Location />
    MellonEnable "auth"
</Location>

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

In the above mellon.conf file, we created a VirtualHost that will serve web contents through https://sp.techsupportpk.com. This configuration also protect an entire domain, which means you have to provide valid credentials to access this url.

Optional: If you wish to protect a web folder instead of an entire domain , your mellon.conf will look similar to the following:

<VirtualHost 192.168.105.71:443>
DocumentRoot /var/www/
ServerName  sp.techsupportpk.com

ServerSignature Off
ErrorLog /var/log/httpd/error_sp.log
LogLevel info
CustomLog /var/log/httpd/access_sp.log combined

SSLEngine on
SSLCertificateFile /etc/pki/tls/certs/sp.crt
SSLCertificateKeyFile /etc/pki/tls/private/sp.key
</VirtualHost>

<location />
MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
MellonSPCertFile /etc/httpd/mellon/mellon.cert
MellonSPMetadataFile /etc/httpd/mellon/mellon.xml
MellonIdPMetadataFile /etc/httpd/mellon/FederationMetadata.xml
MellonEndpointPath /mellon
MellonEnable "info"
</Location>

<Location /secure>
    MellonEnable "auth"
</Location>

In the above example, we only protected https://sp.techsupportpk.com/secure url.

Optional: If you wish to protect just a single web page, your mellon.conf will look similar to the following:

<VirtualHost 192.168.105.71:443>
DocumentRoot /var/www/
ServerName  sp.techsupportpk.com

ServerSignature Off
ErrorLog /var/log/httpd/error_sp.log
LogLevel info
CustomLog /var/log/httpd/access_sp.log combined

SSLEngine on
SSLCertificateFile /etc/pki/tls/certs/sp.crt
SSLCertificateKeyFile /etc/pki/tls/private/sp.key
</VirtualHost>

<location />
MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
MellonSPCertFile /etc/httpd/mellon/mellon.cert
MellonSPMetadataFile /etc/httpd/mellon/mellon.xml
MellonIdPMetadataFile /etc/httpd/mellon/FederationMetadata.xml
MellonEndpointPath /mellon
MellonEnable "info"
</Location>

<Location /sp/info.php>
    MellonEnable "auth"
</Location>

In the above example, if you access https://sp.techsupportpk.com/sp/info.php page, it will ask you to provide valid credentials. All other contents within sp directory will remain accessible without authentication.

Type below command to print  mellon.xml file contents on the terminal:

cat /etc/httpd/mellon/mellon.xml

Copy the entire contents of your mellon.xml from the terminal, paste it in notepad on your ADFS server, and save as MellonMetadata.xml file in any of your preferred location on your Windows ADFS server.

 

Configure Relaying Party Trust (ADFS)

Now you are ready to proceed with Relaying Party Trust configuration on ADFS server as shown in images below.

Right Click on "Relying Party Trusts" Click "Add Relying Party Trust..."

Click Start 

Click "Import data about the relying party from a file" > Browse

Select mellon.xml file you saved earlier > Click Open

Click Next 

Click OK 

Provide "Display Name" Click Next

Keep the default and click Next

Keep the default and click Next 

Click Next 

Keep the default and click Close 

Click Add Rule

Select "Transform an Incoming Claim" from drop down list and click Next

Choose the below information accordingly and click Finish

Click Apply > OK

Right Click on Relying Party Trusts you created > Click Properties

From the Advanced tab select SHA-1 > Apply > OK

Now open Active Directory Users and Computers console > Right Click on domain > Click New > Organizational Unit

Provide OU Name > Click OK

Right Click on OU > New > Users

Provide the username info and click Next

Enter Password and Confirm Password for a user you are creating and click Next

Click Finish

Open up web browser and type your web url to test Single sign-on

Provide the username@domain and password you created earlier and click Sign in

If you see index.html page like below, this means you are done with Single sign-on configuration.

If index.html content not loading after signing-in, then you might need to resync your Linux server time with adfs with " ntpdate idp.techsupportpk.com" command.

Conclusion

We hope this guide was helpful to configure SSO in Apache using mod_auth_mellon and Windows ADFS as an identity provider in your environment.