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.

12 comments:

  1. Thanks, very straightforward tutorial.
    This solved my problem with shibboleth, now I switched to mellon and I'm glad i found this.

    ReplyDelete
  2. Replies
    1. I don't understand the point using Apache for Windows when Windows it self has IIS services.

      Delete
  3. Big Thanks ! You're a genius in computering Apache/Auth_Mellon ! I was stuck while many weeks with a problem authentification ADFS !
    Really, thanks you very much ;)

    ReplyDelete
  4. Thks so much. Another question, how to do if i want users just need to login only 1 time when they login pc in domain and dont need to login on web ???

    ReplyDelete
    Replies
    1. This can be achieved with Microsoft provided web browser i.e. internet explorer, edge.

      Delete
  5. Really nice blog, explains well how to use the mellon

    ReplyDelete
  6. Hi guys and thank you Muhammad for this tutorial. I'm struggling with this SSO through AF DS using Mellon. I'm probably missing something. I have 2 apps hosted on the same server. I built my trust with the AD FS for the server, for both URL but one is working and the other one is giving me a 404 ...

    If you have ani insight I'd love to hear/read it ;)
    Thanks
    Cheers !

    ReplyDelete
    Replies
    1. There must be something miss-configured at Apache or Mellon. If you can share me steps you are performing in pdf or doc format on my email, to understand the issue and help you out. Also if you would like, I can assist you remotely via Team-viewer, Anydesk or whatever medium suits you.

      Delete
  7. So the new user should be added one by one? Like you added webuser1? Or will it take all users of a particular domain ? Thanks in advance

    ReplyDelete
    Replies
    1. It was just an example of creating user in Active Directory and signing in with same user just show Apache SSO working or not. You do not need to add users one by one, it will take all domain users whether old or new.

      Delete

Powered by Blogger.