This documentation relates to an earlier version of Crowd.
View this page in the current documentation or visit the current documentation home.
Skip to end of metadata
Comment: Corrected links that should have been relative instead of absolute.
Go to start of metadata
IN DEVELOPMENT

The attached Perl module is in beta, use the module with caution.

If you find any problems with the module please comment on the following ticket:

Introduction

This documentation describes how to configure Crowd to authenticate HTTP Authentication requests made to an Apache webserver.

  • These instructions assume some Unix system and Apache configuration knowledge.

Prerequisites

Installation and Configuration

The following instructions are for Unix systems. If you're running Apache on Windows, see the notes below.

Installing required Perl Modules

The easiest way to install the required Perl modules is to download them from CPAN (using the links above) and install them as follows:

tar xvzf  Cache-Cache-1.05.tar.gz
cd Cache-Cache-1.05
perl Makefile.PL
make
make install

See http://search.cpan.org/~jhi/perl-5.8.0/pod/perlmodinstall.pod for a detailed description of the various ways of installing Perl modules on your system.

Installing the Apache::CrowdAuth Perl Module

Download the Apache-CrowdAuth-0.06.zip file and extract and install it as follows:

unzip Apache-CrowdAuth-0.06.zip
cd Apache-CrowdAuth-0.06
perl Makefile.PL
make
make install

Configuring Apache

Ensure that mod_perl is enabled.

Your Apache config file should contain a line like the following:

Many common distributions of Apache come with mod_perl preconfigured.

Configure Authentication

To tell Apache to use Crowd to authenticate requests for a particular location, edit the Apache config file to add the following commands to a <Location> or <Directory> section.

Command

Explanation

AuthName crowd

Defines the realm of the authentication. This information is typically provided to the user in the dialog box popped up by their browser

AuthType Basic

Tells apache to use basic authentication

PerlAuthenHandler Apache::CrowdAuth

Tells Apache to delegate authentication to the CrowdAuth module

PerlSetVar CrowdAppName

Set the Application Apache should authenticate as

PerlSetVar CrowdAppPassword

Set the password for the Application

PerlSetVar CrowdSOAPURL

The URL of the Crowd SOAP service

PerlSetVar CrowdCacheEnabled

[optional] Controls whether CrowdAuth caches authentications locally to improve performance. Set to "on" or "off". Caching is "on" by default

PerlSetVar CrowdCacheLocation

[optional] The directory in which CrowdAuth's local cache is stored. Defaults to /tmp/FileCache if not set.

PerlSetVar CrowdCacheExpiry

[optional] The time (in seconds) before cached authentications in CrowdAuth's local cache expire. Defaults to 300 seconds (5 minutes)

require valid-user

Tells Apache that clients must provide a valid username/password to access the location

Subversion Integration

If you are using Apache to manage access to a subversion repository (instructions), you can use the same configuration method to delegate user authentication to Crowd.

Example:

Note that Apache will have to be restarted before any changes to its config files will take effect.

Troubleshooting

  • The CrowdAuth module logs detailed output if the Apache LogLevel parameter is set to info or debug. This can be useful in diagnosing problems.

Apache Log Error Messages

CrowdAppName or CrowdAppPassword is not defined

One or both of the CrowdAppName or CrowdAppPassword parameters is missing from the Apache config file

Failed to authenticate application

The attempt to authenticate the application with crowd failed. Check the values of the CrowdAppName or CrowdAppPassword parameters

Failed to authenticate principal

Failed to authenticate a username/password pair provided by the client. This may just mean that the username or password supplied is incorrect. Note that CrowdAuth won't log successfull authentications unless the LogLevel is info or above.

User token not found in SOAP response for user <user>

Internal SOAP protocol error

error 500...at CrowdAuth.pm..

Indicates that Apache can't connect to the Crowd SOAP service

error 404...at CrowdAuth.pm...

Indicates that the URL used to connect to the Crowd SOAP service is incorrect. Check the value of the CrowdSOAPURL parameter

failed to resolve handler `Apache::CrowdAuth': Can't locate Apache/CrowdAuth.pm ...

The CrowdAuth.pm file isn't located on the Perl include path (or it is permissioned incorrectly)

failed to resolve handler `Apache::CrowdAuth': Can't locate SOAP/Lite.pm...

The SOAP:Lite module hasn't been installed

Installing Perl, mod_perl and Perl Modules on Windows


Setting up CrowdAuth on an Apache instance running on Windows requires that some things be done differently.

(The following instructions assume you are using ActivePerl as your Perl environment).

  • If you don't already have a Perl interpreter installed, you'll need one. The following instructions assume an install of ActiveState's ActivePerl.
  • Windows installations of Apache are less likely to come with mod_perl pre-installed. A Win32 version of mod_perl in PPM format is available here.
  • The .tar.gz format used to distribute CrowdAuth (and other modules) is supported by most modern Windows archiving utilities (WinZip, for example).
  • The make utility used to build the Perl modules is not part of a Windows. nmake, Microsoft's equivalent, is available (as a self-extracting archive) here.

Installing Perl Modules on Windows

All the required modules (Digest::SHA1, Error, Cache::FileCache, SOAP:Lite) are available through the Perl Package Manager utility.

Installing Apache::CrowdAuth on Windows

Extract Apache-CrowdAuth-0.06.zip using Winzip or equivalent...
cd Apache-CrowdAuth-0.06
perl Makefile.PL
nmake
nmake install

When editing the httpd.conf file and adding the mod_perl.so module to Apache, you may need to add the following line above the LoadModule line

LoadFile "C:/Perl/bin/perl58.dll"
LoadModule perl_module modules/mod_perl.so

This LoadFile line points to the perl58.dll in your Perl install directory.

Related Topics  

Crowd 1.1 Documentation