Atlassian Crowd SSO Integration

Overview and Setup

The Crowd SSO module provides single sign-on (SSO) functionality in Drupal for users authenticated against Atlassian Crowd. When a user has authenticated against Crowd, an authentication token is set via browser cookie. When a user with that cookie visits the Drupal website, the authentication token is extracted from the cookie and is validated against Crowd. Upon successful validation, the user is automatically logged into Drupal, and a user account is created in Drupal if the account did not already exist.

If the visiting user does not have the Crowd authentication token, he or she can also authenticate against Crowd with the standard Drupal login form. Upon submission of the login form, the user's credentials are passed to Crowd for authentication. Successful authentication results in Crowd setting an SSO cookie that other Crowd applications should recognize.

Crowd Configuration

In order for Drupal to authenticate against Crowd, it must be added as a new application in Crowd. Please refer to the Atlassian Crowd documentation for instructions regarding adding applications.

Crowd administrators must also correctly configure the SSO cookie domain, to ensure that all applications on the domain will be able to read the authentication cookie. Please refer to the Atlassian Crowd documentation for instructions regarding how to configure this.

Drupal Configuration

Install the Crowd module as normal at admin/build/modules. It is recommend, though not required, that you also install the Dynamic Cache module if you have page caching active for anonymous users. Dynamic cache provides an improved way to bypass Drupal caching during SSO activities and may help avoid conflicts with other modules that manipulate the Drupal bootstrap. SSO will still work for anonymous users without Dynamic Cache installed, but it may not be as reliable in certain situations.

Once installed you must also configure the module to connect to your Crowd server via the options at admin/settings/crowd. At a minimum you must configure all fields within the "Crowd Server Settings" fieldset to tell Drupal how to connect to the Crowd server. Note that the "Crowd REST server" option should define only the server domain (including the http/s protocol but excluding any path or base-path information).

It is also highly recommended that you set a "Crowd cookie SSO domain" value that matches the domain configured with your Crowd server. This will help ensure the sessions started within Drupal will be recognized by your other Crowd applications.

Several other optional configuration controls are also available that let you utilize special features (e.g., Crowd group to Drupal role mappings, self-service account management redirects, etc.) and fine-tune the way Crowd sessions are managed within Drupal.

Using the API

This module also offers a very basic API that lets you extend your Drupal-to-Crowd integration in custom ways.

API Hooks

Several hooks are invoked within the module's normal operational logic which allow you to trigger custom processes in a procedural way. These hooks are further documented in crowd.api.php. There is even a hook available (hook_crowd_client_connect_class_alter()) that allows you to extend/overwrite the base connection methods that are used to communicate with the Crowd server. These methods are explained in more detail below.

API Connection Class and Interface

All communication between Drupal and Crowd is implemented through methods in the CrowdRestClient class. Once your Crowd server connection is setup in the global module configuration, this same class can also be leveraged within your own custom logic (or module) to further extend the connection. One module that does this is Crowd Provisioning.

Example class usage may look something like the following:

// Most methods used to communicate with Crowd will throw a CrowdException
// if something goes wrong, such as a broken server connection. As a result
// it's best to incorporate appropriate exception handling.
try {
  // The preferred way to get a connection object is always through the
  // global factory. An object confirming to the CrowdServiceInterface will be
  // returned, such as a CrowdRestClient object.
  $crowd = crowd_client_connect();
  // Use some methods from the interface.
  global $user;
  $crowd_user = $crowd->getUserFromName($user->name);
  $user_groups = $crowd->getUserGroups($user->name);
  // More stuff...
}
catch (CrowdException $e) {
  // Custom response logger on exceptions.
  $e->logResponse();
  // At a minimum, logging the exception is useful, but other actions may
  // of course be needed depending on the context of the exception.
  return;
}

For a look at all the methods that are available, see the CrowdServiceInterface. Also, as noted above, you can further override existing methods, or implement your own methods, via hook_crowd_client_connect_class_alter() which is invoked as part of the global crowd_client_connect() factory when selecting the appropriate connection class.