Integrating Crowd with Apache

Crowd provides a number of modules that allow you to configure Crowd to authenticate HTTP Authentication requests made to an Apache web server.

以下の機能がサポートされています。

Authentication: Use Crowd to password-protect resources on your website.
Authorisation: Configure website locations to restrict access to specific Crowd groups or users.

Note: These instructions assume some UNIX system and Apache configuration knowledge.

On this page:

Prerequisites

Download and configure Crowd. Refer to the Crowd installation guide for detailed information on how to do this.

Step 1. Configuring Crowd to Talk to Apache

Crowd needs to be aware that Apache will be making authentication requests to Crowd. In brief, you will need to do the following:

Define Apache as a Crowd-connected application to Crowd.
Add and configure the directories visible to Apache.
Add and map the groups which are allowed to authenticate with Apache.

Step 2. Installing the Crowd Apache Connector Packages

The installation procedures for Apache and the Crowd Apache connector vary depending on the operating system you are using. Use the links below to find installation instructions for your chosen operating system. If you have not chosen an operating system yet, you will probably find one of the Linux variants easiest to set up.

Step 3. Configuring Authentication

To tell Apache to use Crowd to authenticate requests for a particular location, edit the Apache config file and 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>

コマンド	説明
Alias /crowd/ "/var/crowd/" <Directory "/var/crowd/"> . . . </Directory>	See the Apache documentation for the format of the <Directory> and Alias directives. We have used the URL path of `/crowd/` and directory path of `/var/crowd/` as the simplest examples. You may substitute your own Crowd URL and directory paths here.
`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. This must be a unique name for each crowd application
`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

For more detail about Apache configuration, please refer to the Apache documentation.

Step 4. Configuring Authorisation

If you want to restrict access to a certain Apache directory or Location, to that only a subset of Crowd users and/or groups have permissions, add the following lines to your configuration:

<Location URL_to_restrict>
  .
  .
  .
  PerlAuthzHandler Apache::CrowdAuthz

  PerlSetVar CrowdAllowedUsers johnh,kevinr
  PerlSetVar CrowdAllowedGroups developers,crowd-administrators,customers:r
  .
  .
  .
</Location>

コマンド	説明
`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. Read-write access is the default privilege if ":r" is not specified.

Step 5. Configuring Subversion (Optional)

If you are using Subversion under Apache, Crowd's Subversion connector allows you to password-protect a Subversion repository and provide fine-grained access control by group or user.

Follow the instructions on integrating Crowd with Subversion.

注意

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

トラブルシューティング

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.71 of SOAP:Lite.
`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.

Child pages