Last updated May 6, 2015. Created on March 31, 2010.
Edited by rjacobs, silverwing, ebeyrent. Log in to edit this page.

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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

ben.bunk’s picture

Chris Johnson’s picture

  • "Drupal administrators must provide the base location of the Crowd server..."

    What's a "base location"? Do you mean an IP address or a resolvable fully-qualified hostname? Or do you mean the URL for the Crowd installation?

  • "...path to the WSDL file served by Crowd."

    How about a hint as the common path used? Is it the base path for the Crowd installation, or does Crowd typically add some additional path components to the URL for the WSDL file?

  • Crowd cookie domain comments.

    Does the Drupal install have to be in the same cookie domain as the Crowd and other Atlassian services? Or will this module make use of any domain, as long as it is correctly specified in the module config?

  • Crowd module URL
    When Crowd asks for the URL of the application to be added, what path should be used? The base URL for the drupal installation, e.g. http://drupal.example.com/ or is there a path component to get to the crowd module that should probably be used, e.g. http://drupal.example.com/crowd.
  • ssaccone’s picture

    When I entered my Crowd server as https://mydomain.org/crowd, port=443, path=rest/usermanagement/latest (default), it could not connect. The Crowd server log contained requests like "crowd:443/rest/...". It appears the port is in the wrong place. To get around this, I set the server to https://mydomain.org, port=443, path=crowd/rest/usermanagement/latest, and it worked.

    rjacobs’s picture

    That is correct, the "Crowd REST server" option should only include the domain, and not any base-path info (the latter should be part of the "Crowd REST API" path setting). I hope that the help text on the configuration form itself makes that clear, but I've also added a note to the documentation on this page to further clarify this.

    shams022’s picture

    I am using Crowd SSO, my seetings are:
    Crowd REST Server = https://crowd.mydomain.com
    Crowd REST Port = 8095
    Crowd REST API path = crowd/rest/usermanagement/latest
    Crowd Cookie SSO domain = mydomain.com
    its working on the above configuration but there are some bugs:

    1. Login to the website using Application credentials are ver very slow.
    2. Users are not able to login in single step.
    3. Its is not allowing users to login using theie existing account on drupal webiste.
    rjacobs’s picture

    This sounds like a support request as opposed to a comment about the documentation. Please make sure that you are using the most recent version, and if you continue to have issues open-up a support request in the issue queue (https://www.drupal.org/project/issues/crowd). I'd be happy to provide whatever help I can there.