Creating a Custom Directory Connector

Custom directory connectors allow you to connect Crowd to custom user-stores, such as existing databases or legacy systems. Crowd comes with a number of supplied directory connectors. If your directory is not listed in Supported Applications and Directories then you will need to create your own custom directory connector.

You may be interested in the connectors, plugins and other extensions created by the Crowd community. See the Atlassian Marketplace.

The directory connectors that come with Crowd implement the Java interface RemoteDirectory. The RemoteDirectory interface defines generic methods for authentication, searching and entity create, remove and update operations. To connect Crowd to a custom directory server, you will need to write a Java class file that implements the RemoteDirectory interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package com.example;

import java.util.List;
import java.util.Map;
import java.util.Set;
import javax.annotation.Nullable;
import com.atlassian.crowd.directory.RemoteDirectory;
import com.atlassian.crowd.embedded.api.PasswordCredential;
import com.atlassian.crowd.exception.*;
import com.atlassian.crowd.model.group.Group;
import com.atlassian.crowd.model.group.GroupTemplate;
import com.atlassian.crowd.model.group.GroupWithAttributes;
import com.atlassian.crowd.model.group.Membership;
import com.atlassian.crowd.model.user.User;
import com.atlassian.crowd.model.user.UserTemplate;
import com.atlassian.crowd.model.user.UserWithAttributes;
import com.atlassian.crowd.search.query.entity.EntityQuery;
import com.atlassian.crowd.search.query.membership.MembershipQuery;
 
public class MyCustomDirectory implements RemoteDirectory
{
    @Override
    public User authenticate(String name, PasswordCredential passwordCredential)
       throws UserNotFoundException, InactiveAccountException, InvalidAuthenticationException, ExpiredCredentialException, OperationFailedException
    {
        throw new RuntimeException("Not implemented"); // replace with your own implementation
    }
 
    // Other RemoteDirectory interface methods will also need to be implemented ...
}

To compile your class, add a dependency on the com.atlassian.crowd:crowd-api Maven artifact. Using Maven is recommended because that artifact will pull all the transitive dependencies, like crowd-integration-api and others.

Once you have finished implementing all of the methods defined by the RemoteDirectory interface, you will then need to:

  1. Create a JAR of the MyCustomDirectory and any supporting class files.
  2. Shut down Crowd.
  3. Place the newly-created JAR from step one in the CROWD/crowd-webapp/WEB-INF/lib folder.
  4. Start Crowd.
  5. Follow the instructions on configuring a custom directory connector through the Crowd Administration Console.

Full Javadoc for the RemoteDirectory interface can be found here: http://docs.atlassian.com/atlassian-crowd/current/com/atlassian/crowd/directory/RemoteDirectory.html.

A ‘principal’ is a ‘user’

In Crowd, the term ‘principal’ is equivalent to the term ‘user’. The Crowd Administration Console refers to ‘users’. Earlier versions of Crowd and certain API libraries refer to ‘principals’.

Next Steps

After creating your directory connector, please see Configuring a Custom Directory Connector.

Crowd Documentation