Post on 19-Jul-2021
transcript
WWPASS AUTHENTICATION MODULE
FOR APACHE SERVER 2.2 INSTALL
GUIDE
June 2013
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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 .................................................................................................................... 10
HOW IT WORKS............................................................................................................. 11
WWP-AMA SOFTWARE PREREQUISITES ...................................................................... 12
Prerequisites Installation .................................................................................................................... 12
Apache Server Installation ................................................................................................................. 12
WWP-AMA INSTALLATION ............................................................................................ 14
ENABLE SERVICE PROVIDER ....................................................................................... 17
Validate domain with WWPass ........................................................................................................... 17
Generate public/private encryption key pair ..................................................................................... 18
Enable .htaccess Apache configuration ............................................................................................ 19
What is .htaccess and How Is It Used? .............................................................................................. 19
How to enable .htaccess Functionality .............................................................................................. 20
.htaccess Configuration...................................................................................................................... 21
Basic .htaccess Directives .............................................................................................................. 21
Cookies and Sessions ..................................................................................................................... 22
User and Access Control ................................................................................................................ 22
.htaccess file example ..................................................................................................................... 23
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 4
Document Text Conventions
Below is a list of type styles used throughout this document to indicate the various data input.
Convention Description
Description Example
Monospace
Indicates source code, code examples, input to the command line, application output, and code lines embedded in text, and variables and code elements.
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.
http://www.google.com
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
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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 3rd
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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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 http://www.apache.org/licenses/LICENSE-2.0
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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:
Apache Server Configuration
The Apache Server manual installation and configuration is not covered in this document. Please refer on the Apache Server documentation on http://httpd.apache.org. 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:
sudo apt-get install wget build-essential autoconf libtool libcurl4-gnutls-dev \
libsqlite3-dev apache2-prefork-dev
LoadModule auth_wwpass /usr/lib/apache2/modules/mod_auth_wwpass.so
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 13
Create a symbolic link to this file from the /etc/apache2/mods-enabled/auth_wwpass.load directory by typing:
Enable the generic authorization module for Apache Server by typing:
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 ln –s /etc/apache2/mods-available/auth_wwpass.load \
/etc/apache2/mods-enabled/auth_wwpass.load
sudo a2enmod auth_digest
sudo service apache2 restart
sudo apt-get libapache2-mod-php5
sudo a2enmod php5
sudo service apache2 restart
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 14
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.
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:
Unpack the file by typing and change directory into it:
Within the /mod_wwpass directory, build the WWP-AMA by executing the following commands:
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.
wget --trust-server-names https://developers.wwpass.com/downloads/mod_wwpass
tar xvzf mod_wwpass.tar.gz
cd mod_wwpass
autoconf
./configure
make
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 15
Install the WWP-AMA to Apache Server modules directory:
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):
Create a symbolic link to this file from the /etc/apache2/mods-enabled directory by typing:
Restart the Apache Server to load the WWP-AMA:
sudo make install
sudo /etc/init.d/apache2 restart
LoadModule auth_wwpass /usr/lib/apache2/modules/mod_auth_wwpass.so
sudo ln –s /etc/apache2/mods-available/auth_wwpass.load
/etc/apache2/mods-enabled/auth_wwpass.load
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 16
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 17
Enable Service Provider
Instructions in this section duplicate the procedure of creation of Service Provider on WWPass
Developer's site (http://developers.wwpass.com). 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 (http://developers.wwpass.com). You can use your WWPass PassKey to register or provide a valid email address. Once you have registered with WWPass, you will receive a validation e-mail containing a link to activate your new account.
Your web site domain (e.g. www.example.com) 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 (http://developers.wwpass.com/providers) 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.
http://www.yourwebsite.com/cc0ea038e0dc5645a0f9ed0482dc61dd.txt
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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:
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.
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
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 19
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
To acquire the WWPass CA:
With a web browser, go to the following address: http://developers.wwpass.com/downloads
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.
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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 20
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.”
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
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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> Description
AuthWWPassEnabled <On | Off>
Turns WWPass module on or off.
AuthWWPassSPFEUrl <url>
WWPass SPFE url. The default is https://spfe.wwpass.com
AuthWWPassCA <cafile>
WWPass CA certificate file in PEM format. One can be acquired at http://developers.wwpass.com/downloads/wwpass.ca
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.
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 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> Description
AuthWWPassCookiePrefix <prefix>
Cookie prefix. The default is wwpass_
AuthWWPassSessionLifetime <lifetime(sec)>
Time to keep authenticated session. 0 to authenticate
each request (this effectively makes the folder
images/css inaccesible)
AuthWWPassDBFile <path_to_db_file>
File to use as SQLite3 session database. The default is
/tmp/auth_wwpass_session_db
AuthWWPassCookieAsSession <On | Off>
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> Description
AuthWWPassUserfile <filename>
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.
AuthWWPassShowPUID <url>
Show PUID on requests to this url. URL will be relative
to the root directory. (i.e. to view www.sample.com/puid,
the given url argument should be "/puid".)
AuthWWPassAutoRegister <On | Off>
Add users that were authenticated by WWPASS and
other Apache Server authentication modules to
AuthWWPassUserfile <filename>.
AuthWWPassRequire <username1[, username2[, username3[...]]] | valid-user | any-user>
Allow only these users according to
AuthWWPassUserfile<filename> (or any WWPass
authorized user in valid-user or any user in file any-
user) to access this directory.
AuthWWPassURLFilter <filter regexp>
WWP-AMA processes only URLs matching this regular
expression (regexp).
WWPass Authentication Module for Apache Server 2.2 Install Guide Page 23
.htaccess file example
## mod_auth_wwpass .htaccess example
<IfModule mod_auth_wwpass.c>
## Basic directives:
AuthWWPassEnabled On
AuthWWPassSPFEUrl https://spfe.wwpass.com
## 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