Documentation for Crowd 1.6. Documentation for other versions of Crowd is available too.

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.

SSO not supported

Currently, the Crowd-Apache integration does not support user single sign-on (SSO). Please refer to issue CWD-1440 for more details. If you like, you can add yourself as a watcher of the issue and vote for it to register your interest in this feature request.

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

  1. Download the three Crowd module files attached to this page:

    Attached file

    Description

    Crowd-Apache-Connector-1.2.3.zip

    Crowd authentication, authorisation and perl module for Apache 2


  2. Extract the Crowd-Apache-Connection archive file and install the three modules using the same procedure as for the third party modules. 

    unzip Crowd-Apache-Connector-1.2.3.zip
cd Atlassian-Crowd-1.2.3/
perl Makefile.PL
make
make install
cd ../Apache-CrowdAuth-1.2.3/
perl Makefile.PL
make
make install
cd ../Apache-CrowdAuthz-1.2.3/
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.

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 dialogue box popped up by their browser

AuthType Basic

Tells Apache to use basic authentication. Digest authentication is not currently supported.

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.
  • If you're using the CrowdAllowedGroups setting and your group names contain spaces, then surround the group names with quotes, for example: 
    PerlSetVar CrowdAllowedGroups "Admin Staff,developers"
  • Although the Apache Connector does not support Digest Authentication, the connection with Crowd can still be secured by using https to make the SOAP connections. 
    PerlSetVar CrowdSOAPURL https://localhost:8095/crowd/services/SecurityServer
    For information on how to secure Crowd connections, refer to the documentation on configuring Crowd to work with SSL.

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)

Can't use string ("1") as an ARRAY ref while "strict refs" in use at (re_eval 116) line 1...

This message is a result of using Perl 5.10 with SOAP::Lite 0.69. Upgrading SOAP::Lite to version 0.71 or greater should correct the problem.

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 (codename 8XX) 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:

C:\>ppm install http://theoryx5.uwinnipeg.ca/ppms/SOAP-Lite.ppd

Installing Apache::CrowdAuth on Windows

unzip Crowd-Apache-Connector-1.2.3.zip using Winzip or equivalent...
cd Atlassian-Crowd-1.2.3/
perl Makefile.PL
nmake
nmake install
cd ../Apache-CrowdAuth-1.2.3/
perl Makefile.PL
nmake
nmake install
cd ../Apache-CrowdAuthz-1.2.3/
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 Documentation





Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.