This page last changed on Mar 06, 2007 by justen.stepka@atlassian.com.
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

  • Apache web server version 2.0 or above with the mod_perl module installed and configured.
  • SOAP::Lite perl module (v0.69 or greater recommended).

Installation and Configuration

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

Installing the SOAP::Lite Perl Module

SOAP::Lite is a Perl library for managing SOAP calls. It is used by the CrowdAuth module to talk to the Crowd server.

The easiest way to install SOAP::Lite is via CPAN, by running the following command.

perl -MCPAN -e 'install SOAP::Lite'

Alternatively, you can download and install the package manually.

Installing the Apache::CrowdAuth Perl Module

Download the Apache-CrowdAuth-0.03.tar.gz file and extract and install it as follows:

tar xvzf Apache-CrowdAuth-0.03.tar.gz
cd Apache-CrowdAuth-0.03
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:

LoadModule perl_module modules/mod_perl.so

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.

Alias /crowd/ "/var/crowd/"
<Directory "/var/crowd/">
.
.
.
  AuthName crowd
  AuthType Basic

  PerlAuthenHandler Apache::CrowdAuth
  PerlSetVar CrowdAppName appname
  PerlSetVar CrowdAppPassword apppassword
  PerlSetVar CrowdSOAPURL http://localhost:8080/crowd/services/SecurityServer

  require valid-user
.
.
.
</Directory>
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
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:

<Location /svn>

 # Uncomment this to enable the repository,
 DAV svn

 # Set this to the path to your repository
 SVNPath /var/lib/svn

 AuthName crowd
 AuthType Basic

 PerlAuthenHandler Apache::CrowdAuth
 PerlSetVar CrowdAppName subversion
 PerlSetVar CrowdAppPassword svn
 PerlSetVar CrowdSOAPURL http://localhost:8080/crowd/services/SecurityServer

 require valid-user

 # The following three lines allow anonymous read, but make
 # committers authenticate themselves.
 <LimitExcept GET PROPFIND OPTIONS REPORT>
 Require valid-user
 </LimitExcept>

</Location>

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 (WARNING: passwords are logged in plaintext to the Apache log file when LogLevel is set to debug).

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 SOAP::Lite on Windows

Use the cpan shell

C:\ cpan
cpan> install SOAP::Lite

Installing Apache::CrowdAuth on Windows

Extract Apache-CrowdAuth-0.03.tar.gz using Winzip or equivalent...
cd Apache-CrowdAuth-0.03
perl Makefile.PL
nmake
nmake install

CrowdAuthP2.pm (text/plain)
CrowdAuthP1.pm (text/plain)
Apache-CrowdAuth-0.03.tar.gz (application/x-gzip)
Apache-CrowdAuth-0.03.tar.gz (application/x-gzip)
Apache-CrowdAuth-0.03.tar.gz (application/x-gzip)
Apache-CrowdAuth-0.03.tar.gz (application/x-gzip)
Apache-CrowdAuth-0.03.zip (application/zip)
Apache-CrowdAuth-0.03.zip (application/zip)

Apache2::CrowdAuth is not included in the crowd 0.4.3 distribution.

Posted by thomasvdv at Feb 02, 2007 00:02

Until the code is folded into the release archive, I have attached the module to this page as an attachment.

Posted by justen.stepka@atlassian.com at Feb 05, 2007 00:06
Document generated by Confluence on Mar 08, 2007 18:50