Implementation Guide Apache HTTP Server - Deepnet Security · 2013-11-04 · Apache is an open source HTTP server that is estimated to serve over 50% of all active web sites on the

Implementation Guide Apache HTTP Server

Copyright © 2013, Deepnet Security. All Rights Reserved. Page 1

Apache HTTP Server Implementation Guide

(Version 5.7)

Copyright 2013

Deepnet Security Limited



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: [email protected]

http://www.deepnetsecurity.com/

mailto:[email protected]



Table of Contents

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

Appendix B: Build Mellon Module ...................................................... 14



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.



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

https://modmellon.googlecode.com/svn/trunk/mod_mellon2/README


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

https://modmellon.googlecode.com/svn/trunk/mod_mellon2/README



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

# 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:

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



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:


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.




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:

Click “Save” to save it.



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

The final step is to insert Mellon directives into the configuration file of your website.



5. Configure Website

Switch to the folder:

/etc/apache2/sites-available

Open your website’s configuration file, e.g. acme.org

<VirtualHost *:80>

ServerAdmin [email protected]

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>


ServerName acme.org




# This is a server-wide configuration that will add information from the Mellon

session to all requests.

<Location />

# 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



</VirtualHost>

We assume that the access to resources in the folder “mfa” requires user authentication.

Restart the Apache server: sudo service apache2 restart

Now, your website is protected by multi-factor authentication.



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:

http://dualshield.deepnetlabs.com/...

http://dualshield.deepnetlabs.com/



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



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>


ServerName acme.org

ServerAlias www.acme.org




# Logfiles



</VirtualHost>

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

5. Test it



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:


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




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

You can copy the module to a production machine in the same folder.

Documents

Implementation Guide Apache HTTP Server - Deepnet Security · 2013-11-04 · Apache is an open source HTTP server that is estimated to serve over 50% of all active web sites on the