Apache HTTP Server. Implementation Guide. (Version 5.7) Copyright 2013 Deepnet Security Limited

(1)

Apache HTTP Server

Implementation Guide

(Version 5.7)

(2)

Trademarks

Deepnet Unified Authentication, MobileID, QuickID, PocketID, SafeID, GridID, FlashID, SmartID, TypeSense, VoiceSense, MobilePass, DevicePass, RemotePass and Site Stamp are trademarks of Deepnet Security Limited. All other brand names and product names are trademarks or registered trademarks of their respective owners.

Copyrights

Under the international copyright law, neither the Deepnet Security software or documentation may be copied, reproduced, translated or reduced to any electronic medium or machine readable form, in whole or in part, without the prior written consent of Deepnet Security.

Licence Conditions

Please read your licence agreement with Deepnet carefully and make sure you understand the exact terms of usage. In particular, for which projects, on which

platforms and at which sites, you are allowed to use the product. You are not allowed to make any modifications to the product. If you feel the need for any modifications, please contact Deepnet Security.

Disclaimer

This document is provided “as is” without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement.

This document could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the document. Deepnet Security may make improvements of and/or changes to the product described in this document at any time.

Contact

If you wish to obtain further information on this product or any other Deepnet Security products, you are always welcome to contact us.

Deepnet Security Limited

Comer Business Innovation Centres North London Business Park

Oakleigh Road South London N11 1GN United Kingdom Tel: +44(0)20 3668 1580 Fax: +44(0)20 8446 3182 Web: www.deepnetsecurity.com Email: support@deepnetsecurity.com

(3)

1. Introduction ... 4

2. Prerequisites ... 4

3. Install Mellon ... 5

3.1 Install Mellon Module ... 5

3.2 Create Mellon Metadata ... 6

4. Exchange Metadata ... 8

4.1 Upload Mellon SP Metadata ... 8

4.1 Download DualShield IdP Metadata ... 9

5. Configure Website ... 10

6. Test ... 11

Appendix A: Create an Apache Website ... 13

(4)

1. Introduction

Apache is an open source HTTP server that is estimated to serve over 50% of all active web sites on the Internet. Apache supports a variety of features, many implemented as compiled modules which extend the core functionality. Mellon is an apache module for protecting web resources using SAML 2.0, it enables Apache to act as a SAML Service Provide (SP) so that Apache can use an external SAML Identity Provider (IdP) as its user authentication server.

Deepnet DualShield is a fully compliant SAML IdP that provides multi-factor user authentication service. When the Mellon module is installed in an Apache server, and configured to connect to a DualShield server, all or selected resources hosted in the Apache server can be protected with multi-factor authentication.

This document describes how to install the Mellon module on to an Apache server, and how to configure the Mellon module to connect to a DualShield server.

This document is written based on Apache 12.

2. Prerequisites

You must have the DualShield Authentication Platform 5.7+ installed and operating. For the installation, configuration and administration of DualShield Authentication Platform please refer to the following documents:

 DualShield Authentication Platform – Installation Guide

 DualShield Authentication Platform – Quick Start Guide

 DualShield Authentication Platform – Administration Guide

You should also have your Apache 2 server installed and operating. For the purpose of this document, we use the following examples:

1. The Linux OS is Ubuntu 12

2. The FQDN of the DualShield server is “dualshield.deepnetlabs.com” 3. The FQDN of the Apache website is “acme.org”

If your Apache website has not been created, please refer to Appendix A for the quick instruction of how to create a website in Apache.

(5)

3. Install Mellon

Mellon is an open source Apache module. Its source codes and some pre-built binary codes can be downloaded from its website:

https://code.google.com/p/modmellon/

If the binary code for your Linux OS is not found in the Mellon website, then you will have to build it from its source code. Building the binary code of Mellon is actually a simple task. Appendix B in this document describes how to build Mellon from source code.

If your Linux OS is Ubuntu 12+, then you can download the pre-built binary code from Deepnet’s website:

http://www.deepnetsecurity.com/downloads/software/

3.1 Install Mellon Module

The Mellon module is named “mod_auth_mellon.so”. Copy it to the folder below on your Apache server:

/usr/lib/apache2/modules

You can further check its dependencies by:

ldd /usr/lib/apache2/modules/mod_auth_mellon.so

Switch to the folder

/etc/apache2/mods-available

Create a file named auth_mellon.load with the following content:

LoadModule auth_mellon_module /usr/lib/apache2/modules/mod_auth_mellon.so Enable the module by:

sudo a2enmod auth_mellon

(The above enable command copies the file auth_mellon.load into the folder

/etc/apache2/mods-enabled. On some linux OS, LoadModule appears in httpd.conf file) Restart Apache server by:

sudo service apache2 restart

Now, switch to the folder

/etc/apache2/mods-enabled

Create a file named auth_mellon.conf with following content, or download the latest from

(6)

########################################################################### # Global configuration for mod_auth_mellon. This configuration is shared by # every virtual server and location in this instance of apache.

########################################################################### # MellonCacheSize sets the maximum number of sessions which can be active # at once. When mod_auth_mellon reaches this limit, it will begin removing # the least recently used sessions. The server must be restarted before any # changes to this option takes effect.

# Default: MellonCacheSize 100 MellonCacheSize 100

# MellonLockFile is the full path to a file used for synchronizing access # to the session data. The path should only be used by one instance of # apache at a time. The server must be restarted before any changes to this # option takes effect.

# Default: MellonLockFile "/var/run/mod_auth_mellon.lock" MellonLockFile "/var/run/mod_auth_mellon.lock"

# MellonPostDirectory is the full path of a directory where POST requests # are saved during authentication. This directory must writeable by the # Apache user. It should not be writeable (or readable) by other users. # Default: None

# Example: MellonPostDirectory "/var/cache/mod_auth_mellon_postdata" # MellonPostTTL is the delay in seconds before a saved POST request can # be flushed.

# Default: MellonPostTTL 900 (15 mn) MellonPostTTL 900

# MellonPostSize is the maximum size for saved POST requests # Default: MellonPostSize 1073741824 (1 MB)

MellonPostSize 1073741824

# MellonPostCount is the maximum amount of saved POST requests # Default: MellonPostCount 100

MellonPostCount 100

########################################################################### # End of global configuration for mod_auth_mellon.

###########################################################################

3.2 Create Mellon Metadata

Every SAML SP and IdP has its own configuration data called Metadata. The SAML protocol requires that the SP and IdP must exchange their Metadata.

You need to create the SAML SP Metadata for the Mellon module. To create this metadata, you can use a script:

mellon_create_metadata.sh

This script takes in two options:

 The Entity ID, which identifies your service.

 The base URL to the endpoints for mod_mellon. Example:

mellon_create_metadata.sh http://example.org/myEntityID http://example.org/mellon This will create three files:

(7)

 A .key-file, which contains the private key in PEM format. This file should be set in the MellonSPPrivateKeyFile option in your website configuration file.

 A .cert-file, which contains the certificate in PEM format. This file should be set in the MellonSPCertFile option in your website configuration file.

 A .xml-file, which contains the metadata file for the SP. This file should be set in the MellonSPMetadataFile option in your website configuration file.

Download the script from:

https://modmellon.googlecode.com/svn/trunk/mod_mellon2/mellon_create_metadata.sh

and save it to the folder:

/etc/apache2/mellon

You might have to make it executable using the chmod command:

sudo chmod a+x mellon_create_metadata.sh

Switch to the folder:

/etc/apache2/mellon

And execute the following command:

./mellon_create_metadata.sh http://acme.org/apache http://acme.org/mellon

We use “apache” as the EntityID and “mellon” as the endpoint. “acme.org” is the FQDN of the example website. Replace “acme.org” with the FQDN of your website.

This will create three files in the folder:

 Private key: http_acme.org_apache.key

 Certificate: http_acme.org_apache.cert

 Metadata: http_acme.org_apache.xml

Now, the Mellon module is installed and configured to work as a SAML Service Provider. Next, you will need to register the Mellon SP in your DualShield Server, and exchange the Metadata between the Mellon SP and DualShield IdP.

(8)

4. Exchange Metadata

4.1 Upload Mellon SP Metadata

In DualShield Console, select “SAML | Service Provider”, then click the “Create” button on the toolbar.

Select “SSO Server” in the SSO Server drop down list, and select “SAML 2.0” in the Type drop down list:

Now, copy the content of the “http_acme.org_apache.xml” file and paste it into the “Metadata” field:

(9)

4.1 Download DualShield IdP Metadata

Prior to downloading the IdP Metadata, you need to create an application in DualShield for your Apache website. You can use the Application Wizard in DualShield to create a new application. See “DualShield Platform – Quick Start Guide” for the instructions. During the process of creating the application, make sure the following fields are correctly set:

 Application Type: Web SSO

 Agent: SSO Server

 Logon Procedure Type: Web SSO

Once the application is successfully created, select “SSO | Servers”. In the server list, click the context menu of the SSO server, select “Download IdP Metadata”:

Select the application you’ve just created, e.g. Website ACME.ORG Click “Save” to download and save the IdP Metadata.

Copy the IdP Metadata file to the folder below: /etc/apache2/mellon

And rename it to: DualShield-Metadata.xml

(10)

5. Configure Website

Switch to the folder:

/etc/apache2/sites-available

Open your website’s configuration file, e.g. acme.org <VirtualHost *:80>

ServerAdmin webmaster@acme.org ServerName acme.org

# Indexes + Directory Root. DirectoryIndex index.html

DocumentRoot /var/www/acme.org # Logfiles

ErrorLog /var/www/acme.org/logs/error.log

CustomLog /var/www/acme.org/logs/access.log combined </VirtualHost>

Insert the following directives: <VirtualHost *:80>

# Indexes + Directory Root. DirectoryIndex index.html DocumentRoot /var/www/acme.org

# This is a server-wide configuration that will add information from the Mellon session to all requests.

# Add information from the auth_mellon session to the request. MellonEnable "info"

# Configure the SP metadata

# These should be the 3 files which were created when creating SP metadata. MellonSPPrivateKeyFile /etc/apache2/mellon/http_acme.org_apache.key

MellonSPCertFile /etc/apache2/mellon/http_acme.org_apache.cert MellonSPMetadataFile /etc/apache2/mellon/http_acme.org_apache.xml

# IdP metadata. This should be the metadata file you downloaded from the

IdP.

MellonIdPMetadataFile /etc/apache2/mellon/DualShield-Metadata.xml # The location all endpoints should be located under.

# It is the URL to this location that is used as the second parameter to the metadata generation script.

# This path is relative to the root of the web server. MellonEndpointPath /mellon

</Location>

# This is a location that will trigger authentication when requested. <Location /mfa>

# This location will trigger an authentication request to the IdP. MellonEnable "auth"

</Location> # Logfiles

We assume that the access to resources in the folder “mfa” requires user authentication. Restart the Apache server: sudo service apache2 restart

(11)

6. Test

Now, your Apache server is enabled with two-factor authentication, and the access to the web resources “http://acme.org/mfa” requires two-factor authentication.

Clicking the link “click to access protected page”, you’ll be redirected to the DualShield SSO server to be authenticated with TFA:

(12)

Once you have been successfully authenticated, you’ll be redirected back to your web site and granted access to the protected page, /mfa/index.html

(13)

Appendix A: Create an Apache Website

Quick steps to create a new Apache web site. The FQDN of the web site is “acme.org” 1. Create a virtual host file for the new site

/etc/apache2/sites-available/acme.org <VirtualHost *:80>

ServerAlias www.acme.org # Indexes + Directory Root. DirectoryIndex index.html DocumentRoot /var/www/acme.org # Logfiles

2. Create necessary folders & files /var/www/acme.org

/var/www/acme.org/index.html /var/www/acme.org/mfa

/var/www/acme.org/mfa/index.html /var/www/acme.org/logs

3. Enable the new web site

sudo a2ensite acme.org

4. Restart Apache server

sudo /etc/init.d/apache2 restart

(14)

Appendix B: Build Mellon Module

This chapter describes how to build Mellon module in Ubuntu 12. 1. Install Apache Sever

If you have not got Apache server installed, use the command below to install it

sudo apt-get install apache2

2. Install Build Package

The Mellon source code is written in C++. To compile C/C++ programs using gcc you must have the build-essential package installed. The build-essential package contains gcc and all the headers that C/C++ need. To install build-essential, use the following command:

sudo apt-get install build-essential

3. Install Mellon Dependencies

Lasso: sudo apt-get install liblasso-dev

Apxs2: sudo apt-get install apache2-dev

Libcurl: sudo apt-get install libcurl4-openssl-dev

4. Download Mellon Source Code The Mellon project is hosted at:

https://code.google.com/p/modmellon/ Use the command below to download it:

wget https://modmellon.googlecode.com/files/mod_auth_mellon-0.7.0.tar.gz Unpack it to a project folder:

tar -xzvf mod_auth_mellon-0.7.0.tar.gz

5. Compile Mellon Module

Type the command below to create the make file

./configure

Check the result. If there is any error then it is normally caused by the lack of it dependencies. Make sure that all of its dependencies have been installed. If succeeded, then run make to compile the module

(15)

Make

Check the result and make sure that it has been successful. Finally, install the module to the Apache server:

sudo make install

Libraries have been installed in: /usr/lib/apache2/modules

-rw-r--r-- 1 root root 267299 Oct 17 14:54 mod_auth_mellon.so

The file name of the module is mod_auth_mellon.so and it is installed in the folder /usr/lib/apache2/modules

Apache HTTP Server. Implementation Guide. (Version 5.7) Copyright 2013 Deepnet Security Limited