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.
Thanks, very straightforward tutorial.
ReplyDeleteThis solved my problem with shibboleth, now I switched to mellon and I'm glad i found this.
And if my apache is on Windows?
ReplyDeleteI don't understand the point using Apache for Windows when Windows it self has IIS services.
DeleteBig Thanks ! You're a genius in computering Apache/Auth_Mellon ! I was stuck while many weeks with a problem authentification ADFS !
ReplyDeleteReally, thanks you very much ;)
Happy to help.
DeleteThks 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 ???
ReplyDeleteThis can be achieved with Microsoft provided web browser i.e. internet explorer, edge.
DeleteReally nice blog, explains well how to use the mellon
ReplyDeleteHi 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 ...
ReplyDeleteIf you have ani insight I'd love to hear/read it ;)
Thanks
Cheers !
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.
DeleteSo 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
ReplyDeleteIt 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