Implementation Guide (Version 5.7) Copyright 2013 Deepnet Security Limited Copyright 2013, Deepnet Security. All Rights Reserved. Page 1
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 Copyright 2013, Deepnet Security. All Rights Reserved. Page 2
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 Copyright 2013, Deepnet Security. All Rights Reserved. Page 3
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. Copyright 2013, Deepnet Security. All Rights Reserved. Page 4
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 Copyright 2013, Deepnet Security. All Rights Reserved. Page 5
########################################################################### # 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: Copyright 2013, Deepnet Security. All Rights Reserved. Page 6
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. Copyright 2013, Deepnet Security. All Rights Reserved. Page 7
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. Copyright 2013, Deepnet Security. All Rights Reserved. Page 8
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. Copyright 2013, Deepnet Security. All Rights Reserved. Page 9
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> ServerAdmin webmaster@acme.org ServerName acme.org # 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. <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. # IdP metadata. This should be the metadata file you downloaded from the 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 ErrorLog /var/www/acme.org/logs/error.log CustomLog /var/www/acme.org/logs/access.log combined </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. Copyright 2013, Deepnet Security. All Rights Reserved. Page 10
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/... Copyright 2013, Deepnet Security. All Rights Reserved. Page 11
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 Copyright 2013, Deepnet Security. All Rights Reserved. Page 12
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> ServerAdmin webmaster@acme.org ServerName acme.org ServerAlias www.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> 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 Copyright 2013, Deepnet Security. All Rights Reserved. Page 13
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 Copyright 2013, Deepnet Security. All Rights Reserved. Page 14
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. Copyright 2013, Deepnet Security. All Rights Reserved. Page 15