For those who seek help in different areas of software and hardware platform.

How To Configure Single-Sign-On (SSO) in Apache using Windows ADFS

This tutorial will walk you through the step to set up Single-Sign-On in Apache using Mellon and Windows Active Directory federation services on CentOS/RHEL 7/8.


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. 

The Apache HTTP server 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 directories 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. 

In this tutorial, you'll learn how to configure Single sign-on (SSO) for a website or web based application published in Apache web server on Red Hat or CentOS 7 server. 

We will use following information throughout this tutorial:


Prerequisites

To follow this tutorial, you will need a Red Hat or CentOS 7 server installed with minimal packages and one Windows 2012 R2 or Windows 2016 server or Windows 2019 Server with Active Directory Domain and Active Directory Federation Services (ADFS) installed. 

Note: Apache directory and file structure may vary if you are using lower or higher Red Hat release than the release we used for this guide. Directory structure and packages installation method also varies if you are on a different Linux distribution such as Debian, Ubuntu etc. 

For this guide, we'll use Red Hat 7.3 for Apache and Windows 2012 R2 for Active Directory and ADFS services. You'll need to replace red highlighted text throughout this guide to reflect yours. 

 

Configure Network 

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

systemctl stop firewalld
systemctl disable firewalld
Type the following command to set hostname:
hostnamectl set-hostname webserver.techsupportpk.com
Type the following command to edit network interface and set the IP address:
vi /etc/sysconfig/network-scripts/ifcfg-ens32
Add, update the following information to reflect yours:
TYPE="Ethernet"
BOOTPROTO="none"
DEFROUTE="yes"
IPV4_FAILURE_FATAL="no"
NAME="ens32"
UUID="d2b38d8d-6d4c-4e30-809a-58bc916a9960"
DEVICE="ens32"
ONBOOT="yes"
IPADDR="192.168.10.11"
PREFIX="24"
GATEWAY="192.168.10.1"
DNS1="192.168.10.10"
DOMAIN="techsupportpk.com"
Save and close the editor when you are finished. Restart network interface to update changes:
ifdown eth0
ifup eth0
Next, synchronize your Linux server's time with your ADFS using the below command:
ntpdate -u fs.techsupportpk.com
 

Install Required Packages

First, we will install EPEL repository on Linux server for some extra packages and updates using the following command:

rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
Next, install Apache, Mellon and their dependencies:
yum -y install ntpdate httpd mod_ssl mod_auth_mellon php openssl wget
When packages installation complete, proceed with the following steps:
mkdir -p /etc/httpd/mellon
mkdir -p /var/www/your_webdirectory
cd /etc/httpd/mellon
We need to disable SSLEngine parameter from 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 

We need to generate an SSL certificate in order to enable HTTPS in Apache web server using the following command:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/pki/tls/private/webserver.key -out /etc/pki/tls/certs/webserver.crt
You must replace 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
Next, we will configure a VirtualHost in Apache to make the web content available through https://sp.techsupportpk.com from the /var/www/sp directory using the /etc/httpd/conf.d/sp.conf parameter file:
vi /etc/httpd/conf.d/sp.conf
Add, update or replace the following highlighted information to reflect yours:
<VirtualHost 192.168.10.11:443>
DocumentRoot /var/www/sp
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/webserver.crt
SSLCertificateKeyFile /etc/pki/tls/private/webserver.key
</VirtualHost>
Save and close the editor when you are finished. Next, create a test page index.html in /var/www/sp directory to test whether VirtualHost is working:
echo Welcome! The sp.techsupportpk.com virtual host is working > /var/www/sp/index.html

 

Configure Mellon

We will generate a mellon configuration metadata and SSL certificate files:

cd /etc/httpd/mellon
/usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://sp.techsupportpk.com/ "https://sp.techsupportpk.com/mellon"
Type the following commands to rename these three files:
mv *.key mellon.key
mv *.cert mellon.cert
mv *.xml mellon_metadata.xml

The https://sp.techsupportpk.com/ is the url that we protect from unauthorized access and the https://sp.techsupportpk.com/mellon is the endpoint url. 

Optional: For instance, if you want to protect a single page instead of entire website: /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://sp.techsupportpk.com/page_name "https://sp.techsupportpk.com/mellon"

Optional: If you want to protect an entire directory: /usr/libexec/mod_auth_mellon/mellon_create_metadata.sh https://sp.techsupportpk.com/directory_name "https://sp.techsupportpk.com/mellon" 

Next, we will download FederationMetadata.xml file from the ADFS server using the following command:

wget https://fs.techsupportpk.com/FederationMetadata/2007-06/FederationMetadata.xml -O /etc/httpd/mellon/FederationMetadata.xml --no-check-certificate
Next, we will create a mellon.conf file in /etc/httpd/conf.d directory:
vi /etc/httpd/conf.d/mellon.conf
Add the following information:
<location>
MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key MellonSPCertFile /etc/httpd/mellon/mellon.cert MellonSPMetadataFile /etc/httpd/mellon/mellon_metadata.xml MellonIdPMetadataFile /etc/httpd/mellon/FederationMetadata.xml MellonEndpointPath /mellon MellonEnable "auth" </Location>

Save and close the editor when you are finished. 

Optional: For instance, if you wish to protect a single web page instead of an entire website, your mellon.conf will look similar to the following:

</Location>
    MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
    MellonSPCertFile /etc/httpd/mellon/mellon.cert
    MellonSPMetadataFile /etc/httpd/mellon/MellonMetadata.xml
    MellonIdPMetadataFile /etc/httpd/mellon/FederationMetadata.xml

    MellonEndpointPath /mellon
    MellonEnable "info"
</Location>
<Location /page_name>
    MellonEnable "auth"
</Location>
Optional: For instance, if you wish to protect an entire directory, your mellon.conf will look similar to the following:
<Location />
    MellonSPPrivateKeyFile /etc/httpd/mellon/mellon.key
    MellonSPCertFile /etc/httpd/mellon/mellon.cert
    MellonSPMetadataFile /etc/httpd/mellon/MellonMetadata.xml
    MellonIdPMetadataFile /etc/httpd/mellon/FederationMetadata.xml

    MellonEndpointPath /mellon
    MellonEnable "info"
</Location>
<Location /dir_name>
    MellonEnable "auth"
</Location> 
 

Configure Relaying Party Trust (ADFS) 

We need to transfer MellonMetadata.xml file from Linux to Windows ADFS server. For copying file on a Windows machine from a Linux server, you can use pscp or any of your favorite tool that can transfer files from Linux to Windows.

If you are using pscp then you can transfer MellonMetadata.xml file using the following command:

Log in to your Windows ADFS server, open up CommandLine or PowerShell:

pscp.exe -sftp root@192.168.10.11:/etc/httpd/mellon/MellonMetadata.xml C:\Users\%username%\Documents
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 metadata xml file you transferred from linux server 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 you are unable to access index.html page after Signing-in then you might need to resync your Linux server time with adfs:

ntpdate fs.techsupportpk.com

Share:

10 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

Comments with links will not be published.

Video Tutorials