WWPASS AUTHENTICATION MODULE FOR APACHE SERVER 2.2 INSTALL GUIDE

Transcription

1 WWPASS AUTHENTICATION MODULE FOR APACHE SERVER 2.2 INSTALL GUIDE June 2013

2 TABLE OF CONTENTS TABLE OF CONTENTS... 2 ABOUT THIS DOCUMENT... 3 DOCUMENT TEXT CONVENTIONS... 4 ABBREVIATIONS & DEFINITIONS... 5 OVERVIEW... 7 LICENSING... 8 SUPPORTED OPERATING SYSTEMS... 9 FEATURES HOW IT WORKS WWP-AMA SOFTWARE PREREQUISITES Prerequisites Installation Apache Server Installation WWP-AMA INSTALLATION ENABLE SERVICE PROVIDER Validate domain with WWPass Generate public/private encryption key pair Enable.htaccess Apache configuration What is.htaccess and How Is It Used? How to enable.htaccess Functionality htaccess Configuration Basic.htaccess Directives Cookies and Sessions User and Access Control htaccess file example Page 2

3 About This Document This document is intended for service provider application programmers, system administrators, quality assurance professionals, and support personnel. It describes how to interface with the WWPass Core System to provide end users with WWPass security services within the Apache Server application. The concepts and principles and instructions described in this document provide the necessary information to successfully implement WWPass security and authentication features into your web site or internet service. This document assumes that the reader has a working knowledge of Linux terminal and the Apache Server configuration. Page 3

4 Document Text Conventions Below is a list of type styles used throughout this document to indicate the various data input. Convention Description Monospace Description Indicates source code, code examples, input to the command line, application output, and code lines embedded in text, and variables and code elements. Example Public Class apt-get Bold Indicates most predefined programming elements, including namespaces, classes, interfaces, methods, functions, macros, structures, properties, enumerations, fields, operators, statements, data types, keywords, exceptions, and non-html attributes. Also indicates filenames with appropriate file type extension, if applicable, and directory paths. Namespace req Config.txt /var/www Bracket Indicates a placeholder for valid options within configuration files. All valid options will be listed within brackets and separated by a. <your_file_here.txt> <on off > Italic Indicates placeholders, most often method or function parameters and HTML placeholders; these placeholders represent information that must be supplied by the implementation or the user. Also used to indicate a document note. Cookie=wwpass.com Note:Text Hypertext Link Indicates a web address that can be accessed outside of the current document that contains application source code, application binaries, or supplemental reference information to the text provided. Capital Letters Indicates the names of keys and key sequences. Also indicates HTML element names. ENTER CTRL+R <A HREF= > Plus Sign Indicates a combination of keys. For example, ALT+F1 means to hold down the ALT key while pressing the F1 key. ALT+F1 Page 4

5 Abbreviations & Definitions Below is a list of commonly used terms associated with WWPass technology along with their associated abbreviation and definition. Term Abbreviation Definition Certifying Authority CA A 3 rd party entity that issues a digital certificate which validates the integrity of a Service Provider. Data Container A component of the WWPass authentication system that provides secure encrypted remote storage of user data. Hypertext Transfer Protocol HTTP A file transfer protocol primarily used to send/receive data formatted using the Hypertext Markup Language (HTML). PassKey A Universal Serial Bus (USB) compatible device that contains basic user information, as well as cryptographic certificates, in encrypted form. Privacy Enhanced Mail PEM A method for exchanging secure communications. An implementation of this requires the exchanging of public certificates between parties. These certificates are usually found with a.pem file extension. Service Provider SP Any entity that provides internet or other network-based services. Service Provider Agent SPA A combination of computer programs, computers and network links that comprise the functionality for a Service Provider. Service Provider ID SPID A unique identifier attributed to a specific Service Provider within the WWPass authentication system. User ID UID A unique identifier attributed to a user within the WWPass authentication system. Page 5

6 WWPass Authentication Module for Apache WWP-AMA Describes the WWPass Authentication Module for Apache Server. In this document, Apache will refer to the specific version designated as Apache Server 2.2. WWPass Authentication Service WWP-AS The combination of a Service Provider s front end user interface and the backend applications/services it interacts with using the WWPass APIs. WWPass Distributed Secure Storage WWP-DSS The principle storage for all WWPass data objects which includes all Data Containers and any other required data. This data is parceled out among multiple, off-site storage units and encrypted so as to be useless should one or more storage location become compromised. WWPass Security Plugin WWP-SPI A component of the WWP-AS that resides on a user s computer as a browser plugin and provides an interface between the user and the Authentication Service. WWPass Service Provider WWP-SP The designation for any entity that provides services to third parties while utilizing the WWPass Authentication Service. WWPass Service Provider Front End WWP-SPFE A component of the WWP-AS that is responsible for communication with Service Providers. WWPass User Front End WWP-UFE A component of the WWP-AS that is responsible for communication between a user and WWP-SPI. Page 6

7 Overview This document is intended for application developers who wish to use the WWPass Authentication Module for Apache 2.2 (WWP-AMA) to authenticate users on an Apache Server. By adding the WWPass infrastructure, the result will turn the Apache Server into a WWPass Service Provider (WWP-SP) with full authentication capabilities. When configured with a second authentication method, WWPass authentication allows the ability to use login/password pairs to provide seamless binding of WWPass PassKeys to existing user accounts. Page 7

8 Licensing The WWPass Authentication Module for Apache Server 2.2 is licensed under the Apache 2.0 license. You can modify and re-distribute the code with the appropriate attribution. You may obtain a copy of the License at Page 8

9 Supported Operating Systems Currently only POSIX operating systems supported, Windows support may be added to future releases. The module should work in all POSIX-compliant operating systems but additional configuration steps may be required on some distributions. This module was tested on Ubuntu and CentOS Linux distributions. Page 9

10 Features Current version WWP-AMA allows the following: Authenticate user with a PassKey via WWP-SPI using WWPass JavaScript library and WWP-SPI; Store user s authenticated session in sqlite3 database for a set period of time after authentication; Pass user s authentication data as "virtual" (module generated) cookies to server-side scripts; Pass authentication to other modules in case of any authentication failure; Automatically assign user names based on authentication by other modules. Page 10

11 How It Works The WWP-AMA is a module that can be incorporated into Apache Server to extend the infrastructure to support WWPass PassKey technology. The module is enacted when Apache Server first receives a request to access a site or specific folder that the administrator wishes to protect from unauthorized access. Upon receiving an HTTP request, Apache Server accesses the WWPass module which then initiates a WWPass authentication transaction. As a result of the transaction, WWPass generates a unique Personal User ID (PUID) number. The module finds a username which corresponds to the PUID from AuthWWPassUserfile that contains PUID:login pairs. The module returns the login name to Apache Server as a result of the authentication. From here, only valid names will be allowed access. The least convenient way to bind PUID to user name is to manually edit AuthWWPassUserfile. A more advanced procedure implies fallback to login/password authentication for finding user name. This way WWP-AMA makes changes to AuthWWPassUserfile automatically. An example of fallback configuration is shown in the.htaccess file example at the end of this document. Page 11

12 WWP-AMA Software Prerequisites The following software packages must be installed prior to compiling WWP-AMA, and allow for proper integration and post-install testing: autoconf libtool libcurl with SSL support libsqlite3 Apache Server ver. 2.2 Apache Server development headers and tools PHP (Optional) Prerequisites Installation The installation of prerequisites differs depending on the OS. The instructions below are for the Debian/Ubuntu family of Linux OS. To install the prerequisites open the terminal and type: sudo apt-get install wget build-essential autoconf libtool libcurl4-gnutls-dev \ libsqlite3-dev apache2-prefork-dev Apache Server Configuration The Apache Server manual installation and configuration is not covered in this document. Please refer on the Apache Server documentation on Once the server is successfully installed, complete the following steps: Create a new file in directory /etc/apache2/mods-available called auth_wwpass.load that contains the following directive on one line: LoadModule auth_wwpass /usr/lib/apache2/modules/mod_auth_wwpass.so Page 12

13 Create a symbolic link to this file from the /etc/apache2/mods-enabled/auth_wwpass.load directory by typing: sudo ln s /etc/apache2/mods-available/auth_wwpass.load \ /etc/apache2/mods-enabled/auth_wwpass.load Enable the generic authorization module for Apache Server by typing: sudo a2enmod auth_digest sudo service apache2 restart PHP (Optional) This is not required and only necessary on clean Apache installs, but since many of the developer tools rely on php, enabling it on the Apache Server could be considered vital. From the terminal the following commands will successfully install PHP 5: sudo apt-get libapache2-mod-php5 sudo a2enmod php5 sudo service apache2 restart Page 13

14 WWP-AMA Installation This section will describe how to download and build the WWP-AMA to prepare it for inclusion in the Apache Server 2.2. Open the terminal, change directory to where you would like to build the WWP-AMA and download it by typing: wget --trust-server-names Unpack the file by typing and change directory into it: tar xvzf mod_wwpass.tar.gz cd mod_wwpass Within the /mod_wwpass directory, build the WWP-AMA by executing the following commands: autoconf./configure make Note that there are two possible option flags to the configure script command line above: --with-apache=<path> Sets the path for the Apache Server development tools, the default is /usr/share/apache2. --with-random=<randpath> Sets the path to the source of entropy for generating session IDs, the default is /dev/urandom. Note: There is a /dev/random that generate more cryptographically strong random data than /dev/urandom, but it s not advised to use it at it may block the execution of the module if it doesn t have enough entropy. Page 14

15 Install the WWP-AMA to Apache Server modules directory: sudo make install Create a new file in directory /etc/apache2/mods-available called auth_wwpass.load that contains the following directive on one line (the exact paths may differ on different installation of Apache Server): LoadModule auth_wwpass /usr/lib/apache2/modules/mod_auth_wwpass.so Create a symbolic link to this file from the /etc/apache2/mods-enabled directory by typing: sudo ln s /etc/apache2/mods-available/auth_wwpass.load /etc/apache2/mods-enabled/auth_wwpass.load Restart the Apache Server to load the WWP-AMA: sudo /etc/init.d/apache2 restart Page 15

16 Page 16

17 Enable Service Provider Instructions in this section duplicate the procedure of creation of Service Provider on WWPass Developer's site ( You may prefer to use online wizard there. To allow WWP-AMA to integrate with the WWP-AS, the administrator will need to do the following: Validate domain name with WWPass Generate public/private encryption key pair Obtain a valid certificate from a Certifying Authority (CA) in.crt format. Enable.htaccess Apache Server configuration Enable PUID access table Validate domain with WWPass To validate your web site domain, begin by registering at the WWPass Developer's site ( You can use your WWPass PassKey to register or provide a valid address. Once you have registered with WWPass, you will receive a validation containing a link to activate your new account. Your web site domain (e.g. will be known to WWPass as a Service Provider. After logging into the developers section of the WWPass web site, click on the Service Providers link ( at the top of the screen. Under the Service Providers heading, click on the Add New Service Provider button. You should be transferred to the 4-step guide to authenticating your web site. The following steps are short descriptions of what is found on the WWPass web site. Step 1: Define Domain Name Enter the domain name for your web site and click on the Add Domain. Step 2: Validate Your Domain A text file with a unique text will be shown, this file needs to be placed in the root directory of your web site. You can download the file or copy the text to a file with the name specified. The file name and content should not be changed. This file should be accessible through a URL such as: Download the validation file provided (.txt file) and place this at the document root of your web site (e.g. /var/www). Next, click on the Validate button to initiate web site validation. If the text file is properly placed, the Service Provider listed on your account page will indicate Validated and a Service Provider ID will be assigned. This is the ID that identifies your web service to WWPass. Page 17

18 Your site is now validated; delete the text file from your website. Generate public/private encryption key pair Step 3: Generate Keys The next step is to create public/private encryption keys. These keys will allow for secure communications between the Service Provider and WWPass. Open a terminal window and use the OpenSSL utility to generate the public/private keys required. To create the keys, type: openssl req -new -newkey rsa:4096 -nodes -subj \ "/O=<Your Service Provider name>/cn=<your Service Provider ID>" \ -keyout <Your Service Provider name>.key \ -out <Your Service Provider name>.req The output from this operation will be two names files <Service_Provider_Name>.key and <Service_Provider_Name>.req. The.req file will be needed to request a certificate from WWPass. At the bottom of the Generate Keys page, click on the Browse button and go to the location that contains the.req file and input the path. Click the Submit button to send the certificate request to WWPass. Step 4: Get Certificate WWPass will respond to the certificate request from the previous step with a certificate file (YourDomainName.com.crt). If you were using OpenSSL just put the certificate and private key (<ServiceProviderName>.key) on the web server. Put them in a folder that is not accessible from web. (i.e. /etc/ssl/certs) It is important that the web server should not serve out the private key in response to any request. Set access rights so that the process of you web server has the read rights on your private key and certificate. No other user should have any rights to access the file with your private key. Should the private key become compromised, simply generate a new private key, then return to the WWPass web site and manage your domain by submitting the new key. When your web service connects to WWPass, the WWPass server will present an SSL certificate signed by WWPass. For your web service to verify the validity of the WWP-SPFE it will need the WWPass CA certificate. Download it and put it in the same location as your certificate. Later you will provide the path to this CA certificate in the Apache Server configuration file that will be used to authenticate connections to WWPass as part of the authorization process. Page 18

19 To acquire the WWPass CA: With a web browser, go to the following address: Under the Resources for Developers section, across from the WWPass CA Certificate listing, lick on the Download button. The web browser should begin to download a WWPass CA certificate. Create a folder (i.e. /var/certs) and place this certificate in a folder that only the Apache Server can access with specific folder permissions. Make note of this folder as it will be used in the.htaccess file. Do not put this folder in the Apache Server web root (/var/www) directory. Enable.htaccess Apache Server configuration To complete web access within the Apache Server, the user needs to create and modify an.htaccess file. This file is read by Apache Server upon every web page request. The file will reside at the root of the folder that the Service Provider wishes to protect. An example of this would be a web site at the location: /var/www/serviceproviderroot/.htaccess What is.htaccess and How Is It Used?.htaccess is a file that provides a way to make access changes on a per-directory basis. This file, containing one or more access and configuration directives, can be placed in a document directory, and those directives will apply to that directory, as well as all subdirectories. Note: If you want to call your.htaccess file something else, you can change the name of the file using the AccessFileName directive in the /usr/local/apache2/conf/httpd.conf file. For example, if you would rather call the access file.config then you can put the following in your server configuration file: AccessFileName.config In general,.htaccess files use the same syntax as the main configuration files. What you can put in these files is determined by the AllowOverride directive. This directive specifies, in categories, what directives will be honored if they are found in an.htaccess file. If a directive is permitted in the file, the documentation for that directive will contain an override section, specifying what values must be in AllowOverride in order for that directive to be permitted. Page 19

20 How to enable.htaccess Functionality To allow for.htaccess files to be used within Apache Server, you must modify the file /etc/apache2/sites-available/default Under the section DocumentRoot /var/www, go to the line that reads AllowOverides None. Change None to All ; this will force Apache Server to use.htaccess files for per-directory configuration. Upon completing the file edit, force Apache Server to reload the configuration files by typing: sudo /etc/init.d/apache2 reload Note: use of the.htaccess file capability will incur a performance hit as the directive will force Apache to look in the current directory as well as any directory above it in the directory tree to check for parent.htaccess files. From Apache.org: The first of these is performance. When AllowOverride is set to allow the use of.htaccess files, httpd will look in every directory for.htaccess files. Thus, permitting.htaccess files causes a performance hit, whether or not you actually even use them! Also, the.htaccess file is loaded every time a document is requested. Also note that Apache must look for.htaccess files in all higher-level directories, in order to have a complete list of directives that it must apply. (See section on how directives are applied.) Thus, if a file is requested out of a directory /www/htdocs/example, httpd must look for the following files: /.htaccess /www/.htaccess /www/htdocs/.htaccess /www/htdocs/example/.htaccess And so, for each file access out of that directory, there are 4 additional file-system accesses, even if none of those files are present. Note that this would only be the case if.htaccess files were enabled for /, which is not usually the case. Page 20

21 .htaccess Configuration At the end of this section a sample.htaccess file is provided to show the use of the directives listed below. Basic.htaccess Directives Directive <options> AuthWWPassEnabled <On Off> Description Turns WWPass module on or off. AuthWWPassSPFEUrl <url> WWPass SPFE url. The default is AuthWWPassCA <cafile> WWPass CA certificate file in PEM format. One can be acquired at AuthWWPassSPCert <crtfile> Service Provider certificate file in PEM format. AuthWWPassSPKey <keyfile> Service Provider private key file in PEM format. AuthWWPassSPName <spname> Service Provider name (URL-encoded) AuthWWPassRequestPassword <On Off> Add second factor: request password for PassKey. Default is off. AuthWWPassAuthPage <path_to_auth_page_template> Template for authentication page. If this is an empty string, the default page will be used. Page 21

22 Cookies and Sessions Within the.htaccess file there are a several settings that can be enabled to turn on/off cookies and related functionality. Directive <options> AuthWWPassCookiePrefix <prefix> Description Cookie prefix. The default is wwpass_ AuthWWPassSessionLifetime <lifetime(sec)> AuthWWPassDBFile <path_to_db_file> AuthWWPassCookieAsSession <On Off> Time to keep authenticated session. 0 to authenticate each request (this effectively makes the folder images/css inaccesible) File to use as SQLite3 session database. The default is /tmp/auth_wwpass_session_db Set cookie lifetime to that of session. If not set, this will persist until browser restart. User and Access Control Within the.htaccess file there are a series of settings that can be entered for specific user and access control. Directive <options> AuthWWPassUserfile <filename> AuthWWPassShowPUID <url> AuthWWPassAutoRegister <On Off> AuthWWPassRequire <username1[, username2[, username3[...]]] validuser any-user> AuthWWPassURLFilter <filter regexp> Description File containing PUID:username pairs each line has a semicolon used as a field separator. Otherwise, spaces may be used to separate PUID and username. The file should be accessible to the Apache Server account. Show PUID on requests to this url. URL will be relative to the root directory. (i.e. to view the given url argument should be "/puid".) Add users that were authenticated by WWPASS and other Apache Server authentication modules to AuthWWPassUserfile <filename>. Allow only these users according to AuthWWPassUserfile<filename> (or any WWPass authorized user in valid-user or any user in file anyuser) to access this directory. WWP-AMA processes only URLs matching this regular expression (regexp). Page 22

23 .htaccess file example ## mod_auth_wwpass.htaccess example <IfModule mod_auth_wwpass.c> ## Basic directives: AuthWWPassEnabled On AuthWWPassSPFEUrl ## Path to WWPass CA certificate. Recommend /etc/ssl/certs AuthWWPassCA "/path/to/certs/wwpass_sp_ca.crt" ## Path to Service Provider certificate. Recommend /etc/ssl/certs AuthWWPassSPCert "/path/to/certs/<yourdomainhere>.com.crt" ## Path to private key. Recommend /etc/ssl/private (make sure that the Apache process will be able to access the file) AuthWWPassSPKey "/path/to/keys/< yourdomainhere >.key" AuthWWPassSPName "<yournamehere>.com" AuthWWPassRequestPassword On AuthWWPassAuthPage "/var/www/login.php" ## Cookies and sessions: AuthWWPassCookiePrefix "_wwpass" AuthWWPassSessionLifetime 3600 AuthWWPassDBFile "/tmp/auth_wwpass_session_db" AuthWWPassCookieAsSession Off ## User and access control AuthWWPassUserfile "/var/www/" AuthWWPassShowPUID /maw/uid (<-Note Is this correct?) AuthWWPassAutoRegister On AuthWWPassRequire valid-user </IfModule> ## Fallback to basic AuthType Basic AuthName "Restricted Files" AuthDigestDomain / AuthDigestProvider file AuthUserFile /var/www/.htpasswd Require valid-user Page 23