Integrating Crowd with Apache

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

The following features are supported:

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

This version of the connector is supported under Linux. Please see Choosing the Correct Apache Connector for your Operating System for details and alternatives.

Note: These instructions apply to Crowd 2.1 and later. We 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. Disabling any Previous Version of the Crowd Apache Connector

If you are upgrading from a previous version of the Connector, you must disable it by following these instructions before proceeding.

Step 2. Configuring Crowd to Talk to Apache

If you are upgrading from an earlier version of the Apache Connector, you will have already completed this step and you can skip it.

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

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

Step 3. Choosing the Correct Apache Connector for your Operating System

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.

The 2.x version of the Crowd-Apache connector supports advanced features such as nested groups and single sign-on but is currently only supported for certain operating systems.

Note about Crowd-Apache 1.4 Connector

This document is for the 2.x version of Crowd-Apache Connector, if you can't find a compatible version of the 2.x Subversion Connector for your O/S in the table below then refer to the 1.4 version of the Crowd-Apache Connector.

Previous version of Crowd-Apache connectors don't support the SVNParentPath directive. Crowd 2.9.1 is not compatible with version 1.4 of the Crowd-Apache connector.

Operating System

Crowd-Apache Connector 2.0

Crowd-Apache Connector 1.4

Red Hat Enterprise Linux

(tick) 6.0 (tick) 5.5 Installation guide

(info) Installation guide for other OS versions

CentOS Linux

(tick) 5.5 Installation guide

(info) Installation guide for other OS versions

Ubuntu Linux

(tick) 11.04 (tick) 10.10 (tick) 10.04 Installation guide

(info) Installation guide for other OS versions

Debian

(tick) 6.0 Installation guide

(info) Installation guide for other OS versions

Other UNIX-Like Systems

Not supported*

(tick) Installation guide

Windows

Not supported*

(tick) Installation guide

*The Crowd-Apache Connector 2.0 source code is available with instructions to build from source. If you have the expertise to compile the C library and get it working for an environment that is currently not supported then feel free to contribute by adding a comment to this page. We will try to incorporate your fix in the next release of the Crowd-Apache Connector.

Step 4. Configuring Authentication

In this section, you will 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.

<Directory "/var/mysite/">
.
.
.
  AuthName "Atlassian Crowd"
  AuthType Basic
  AuthBasicProvider crowd

  CrowdAppName myappname
  CrowdAppPassword mypassword
  CrowdURL http://localhost:8095/crowd/

  Require valid-user
.
.
.
</Directory>

This is the minimum configuration required to password-protect a location with Crowd.

These commands must be added to the Apache config. It does not work with .htaccess.

Command

Explanation

<Directory "/var/mysite/">
.
.
.
</Directory>

See the Apache documentation for the format of the <Directory> and <Location> directives. We have used the directory path of /var/mysite/ as the simplest example. You may substitute your own directory path here.

AuthName "Atlassian Crowd"

Defines the realm of the authentication. This information is typically provided to the user in the dialog box popped up by their browser. This must be a unique name for each Crowd application

AuthType Basic

Tells Apache to use HTTP Basic authentication. HTTP Digest authentication is not currently supported.

AuthBasicProvider crowd

Tells Apache to delegate authentication to the Apache Crowd connector.

CrowdAppName myappname

Set 'myappname' to the application Apache should authenticate as.

CrowdAppPassword mypassword

Set 'mypassword' to the password for the application.

CrowdURL http://localhost:8095/crowd/

The URL of the Crowd server.

Require valid-user

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

The following configuration commands are optional, and can be used to customize your configuration further:

Command

Explanation

Default

CrowdAcceptSSO Off

When set to 'On', the Apache Crowd connector will attempt to validate single sign-on (SSO) tokens provided in requests, avoiding the need for the user to log in if they have already logged in to another application.

On

CrowdCreateSSO Off

When set to 'On', the Apache Crowd connector will create a single sign-on (SSO) token whenever a user successfully authenticates, avoiding the need for the user to log in to other applications.

On

CrowdBasicAuthEncoding ISO-8859-1 UTF-8

Sets the list of character encoding schemes that the Apache Crowd connector will use to decode usernames and passwords. Each is tried in turn, until authentication succeeds. This setting may need to be changed if you have users with non-ASCII characters in their usernames or passwords, as browsers differ in the encoding schemes they use. Note that when an authentication attempt fails with one or more encodings before succeeding with another, the failures may still be counted and logged as failures by the directory.

ISO-8859-1

CrowdTimeout 5

The maximum number of seconds that the Apache Crowd connector should wait for a response from Crowd. If set to 0, the connector will wait indefinitely.

0

CrowdCacheMaxAge 120

The maximum number of seconds that a response from Crowd will be cached by the Apache Crowd connector.

60

CrowdCacheMaxEntries 1000

The maximum number of entries cached at any time by the Apache Crowd connector. If set to 0, caching is disabled.

500

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

Step 5. Configuring Authorization

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

<Location URL_to_restrict>
  .
  .
  .
  Require user johnh kevinr
  Require group developers crowd-administrators
  AuthzUserAuthoritative Off
  .
  .
  .
</Location>

Note that you must also remove any Require valid-user command from this <Directory> or <Location> for the new restrictions to take effect.

Command

Explanation

Require user johnh kevinr

Allow the users johnh or kevinr to access the location.

Require group developers crowd-administrators

Allow members of the developers or crowd-administrators groups to access the location.

If both 'Require user' and 'Require group' are used, these are combined using OR rather than AND, so any user that authenticates successfully will be able to access the resource.

If you are using "Require user" and "Require group" directives together, you will need to add the following setting:

Command

Explanation

Default

AuthzUserAuthoritative Off

When set to 'On', authorization decisions made by mod_authz_user on the basis of "Require user" directives are final. When set to 'Off', they may be overruled by other Apache authorization providers.

On

If you have configured authorization providers in addition to the Crowd Apache connector, you may need to add the following optional setting:

Command

Explanation

Default

AuthzCrowdAuthoritative Off

When set to 'On', authorization decisions made by Crowd are final. When set to 'Off', they may be overruled by other Apache authorization providers.

On

Step 6. 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.

Notes

  • Typically, only one of the Require user or Require group commands is needed for a particular location. You can define both. If you do, then access is granted if either is satisfied.
  • If the CrowdCacheMaxEntries setting is missing or set to a non-zero value, then requests to Crowd are cached in order to increase performance. This means that changes to passwords, group membership and session expiry in Crowd may not be reflected immediately in user access.
  • Although the Apache Connector does not support Digest Authentication, the connection with Crowd can still be secured by using httpsto make the SOAP connections.

    CrowdURL https://localhost:8095/crowd/

    For information on how to secure Crowd connections, refer to the documentation on configuring Crowd to work with SSL.

  • If you are using Crowd 2.0 or earlier, you need to follow the instructions for Crowd 2.0.
RELATED TOPICS

Crowd Documentation

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport