WWPASS AUTHENTICATION MODULE FOR APACHE SERVER 2.2 …€¦ · for Apache 2.2 (WWP-AMA) to...

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


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.


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

http://www.google.com/


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

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.


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.


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

http://www.apache.org/licenses/LICENSE-2.0


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.


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.


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.


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

http://httpd.apache.org/


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


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


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



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

http://developers.wwpass.com/

http://developers.wwpass.com/

http://www.example.com/

http://developers.wwpass.com/providers


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

https://developers.wwpass.com/downloads/wwpass.ca

https://developers.wwpass.com/downloads/wwpass.ca


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.

http://httpd.apache.org/docs/2.2/mod/core.html#accessfilename

http://developers.wwpass.com/downloads

http://httpd.apache.org/docs/2.2/mod/core.html#allowoverride



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


http://httpd.apache.org/docs/2.2/howto/htaccess.html#how

http://httpd.apache.org/docs/2.2/howto/htaccess.html#how


.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.

https://spfe.wwpass.com/

http://developers.wwpass.com/downloads/wwpass.ca


Cookies and Sessions

Within the .htaccess file there are a several settings that can be enabled to turn on/off cookies and

related functionality.


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.


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).

http://www.sample.com/puid


.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

https://spfe.wwpass.com/

Date post:	19-Jul-2021
Category:	Documents
Upload:	others
View:	6 times
Download:	0 times

WWPASS AUTHENTICATION MODULE FOR APACHE SERVER 2.2 …€¦ · for Apache 2.2 (WWP-AMA) to...

Documents