This page last changed on May 05, 2008 by smaddox.
Crowd provides a number of modules that allow you to configure Crowd to authenticate HTTP Authentication requests made to an Apache web server.
The following features are provided:
- Use Crowd to password-protect resources on your website.
- Configure website locations to restrict access to specific Crowd groups or users.
Note: These instructions assume some Unix system and Apache configuration knowledge.
 | Using Subversion under Apache?
Crowd's Subversion connector allows you to password-protect a Subversion repository and provide fine grained access by group or user. Read more. |
Prerequisites
- Apache web server version 2.0 or above with the mod_perl module installed and configured.
- The following third-party Perl modules:
Installation and Configuration
The following instructions are for Unix systems. If you're running Apache on Windows, see the notes below.
Installing the Third-Party Perl Modules
Download the required Perl modules 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 Crowd Perl Modules
- Download the three Crowd module files attached to this page:
- Extract the Crowd-Apache-Connection archive file and install the three modules using the same procedure as for the third party modules.
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.
Configuring 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:8095/crowd/services/SecurityServer
PerlSetVar CrowdCacheEnabled on
PerlSetVar CrowdCacheLocation /tmp/CrowdAuth
PerlSetVar CrowdCacheExpiry 300
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 |
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 |
Configuring Authorisation
If you want to restrict access to a certain Directory or Location in your Apache configuration to a subset of Crowd users and/or groups, add the following lines to your configuration:
<Location>
.
.
.
PerlAuthzHandler Apache::CrowdAuthz
PerlSetVar CrowdAllowedUsers johnh,kevinr
PerlSetVar CrowdAllowedGroups developers,crowd-administrators,customers:r
.
.
.
</Location>
Command |
Explanation |
PerlAuthzHandler Apache::CrowdAuthz |
Tells Apache to use the Apache::CrowdAuthz} for authorisation |
PerlSetVar CrowdAllowedUsers johnh,kevinr |
Allow only the users johnh or kevinr to access the location |
PerlSetVar CrowdAllowedGroups developers,crowd-administrators,customers:r |
Allow only members of the developers or crowd-administrators groups to access the location.
You can indicate that a group has read-only access to the location by appending ":r" to the group name. This is mainly useful for giving a group read-only access to a Subversion repository |
Note:
- Typically, only one of the CrowdAllowedUsers or CrowdAllowedGroups would be needed for a particular location. You can define both. If you do, then access is granted if either is satisfied.
- If the CrowdCacheEnabled setting is on, then authorisation checks are cached in order to increase performance. This means that changes to group membership in Crowd may not be reflected immediately in user access.
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 Message |
Possible Cause and Next Steps |
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 successful 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 has incorrect permissions). |
failed to resolve handler `Apache::CrowdAuth': Can't locate SOAP/Lite.pm... |
The SOAP:Lite module hasn't been installed. |
Can't locate object method "call" via package "SOAP::SOM" at ... |
This message indicates a missing or old installation of SOAP::Lite. Try installing (or reinstalling) version 0.69 SOAP:Lite. On Windows, you will get this error if you haven't manually upgraded the SOAP::Lite ppm (see below) |
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. We strongly recommend running version 5.8.8 of ActivePerl rather than any newer version.
- 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
The required modules (Digest::SHA1, Error, Cache::FileCache, SOAP:Lite) are available through the Perl Package Manager utility.
CrowdAuth needs a newer version of SOAP::Lite than is supplied with ActivePerl (0.69 vs 0.55). A prebuilt ppm of the correct version can be installed from the University of Winnipeg's repository using the following command:
Installing Apache::CrowdAuth on Windows
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:
This LoadFile line points to the perl58.dll in your Perl install directory.
Related Topics
Crowd Documentation
|