Collaborator provides a simple web UI for creating and managing groups, but when groups are used to represent organizational hierarchy for large companies the web UI becomes unmanageable. Such groups are usually already stored in an external system such as LDAP or Active Directory, Single Sign-On server, or repository hosting server, so Collaborator provides the ability to synchronize its users and groups with external system.

Collaborator offers two ways to perform synchronization: you can setup user and group mapping from the web interface using the administrator account, or run the special command of the command-line client. Once established, user and group mapping operates constantly (upon every login), however it supports just several most frequently used systems: LDAP and Active Directory, Crowd single sign-on servers and GitLab servers. Synchronizing through command-line interface accepts group data in XML format and thus is suitable for any system. However it requires more efforts to create the input XML file and the command should be executed periodically to keep the data synchronized.

Synchronize Users and Groups in Web Interface

Syncing with LDAP or Active Directory

You may configure user and group synchronization between Collaborator and the LDAP directory or Active Directory. In this case, Collaborator will retrieve user properties (name, phone, email, and so forth) and their membership in groups from the LDAP directory or Active Directory when the users login. If the user or group does not exist on server, Collaborator will create it automatically.

To enable synchronization on Active Directory systems, you will need to open the LDAP Settings tab of General settings, enable the respective properties and possibly adjust the attribute mapping configuration.

To perform synchronization on LDAP systems, you will need to configure the LDAP Settings and also modify the ROOT.xml file. You will need to add the following fields: the connectionName and connectionPassword. These define a user account the Collaborator will use to connect to LDAP to find the group membership user records, and the roleBase and roleSearch fields, which define the base entry for the role search and the search filter for selecting role entries.

Technical details

For mapping user membership in groups Collaborator uses the fully qualified domain name (FQDN) of the group, that is retrieved from LDAP or AD. It checks if some of existing user groups has matching FQDN and adds the user to this group on success. Otherwise, it creates a new group and adds the user to the new group.

To name the new group, Collaborator uses the first entry of the fully qualified domain name (FQDN) of the group. For example, a group with the following attributes – ccusers, dc = example, dc=com – FQDN will have the ccusers title. If some other group already has the same title, Collaborator will append the ordinal number to the group title: ccusers1, ccusers2, and so on.

On every login Collaborator checks existing groups created via LDAP or Active Directory synchronization and actualizes user membership in those groups. Such algorithm allows to keep a consistency between Collaborator and LDAP or Active Directory.

Syncing with Crowd single-sign-on server

You may configure user and group synchronization between Collaborator and the Atlassian Crowd server. In this case, Collaborator will retrieve user properties (name, phone, email, and so forth) and their membership in groups from the Crowd server when the users login.

To enable group synchronization with Crowd server:

Open the Admin > Single Sigh-On page.
Locate your Crowd SSO configuration in the SSO Configurations list and click Edit.
Set the Enable Crowd group sync setting to True.
Optionally, use the Automatic group creation filter to specify what exactly groups should be created automatically.
Press Save to apply changes and enable synchronization.

Technical details

Collaborator retrieves user membership from the Crowd server and checks if some of existing user groups has matching name. Once such group is found, it adds the user to this group. Otherwise, it checks if the group name matches Automatic group creation filter, creates new group on success and adds the user to the new group.

On every login Collaborator actualizes user membership in groups. Such algorithm allows to keep a consistency between Collaborator and Crowd server.

When Crowd integration is disabled or deleted, synchronized groups will become disabled.

Syncing with GitLab server

You may configure user and group synchronization between Collaborator and the GitLab server. In this case, Collaborator will retrieve user properties (name, phone, email, and so forth) and their membership in groups from the GitLab server when the users login.

To enable group synchronization with GitLab server:

Open the Admin > Repository Hosting Services page.
Locate your GitLab configuration in the Remote Systems Configurations list and click Edit.
Set the Sync Groups setting to True.
Press Save to apply changes and enable synchronization.

Technical details

Collaborator retrieves user membership from the GitLab server and checks if some of existing user groups has matching name. Once such group is found, it adds the user to this group. Otherwise, it creates new group and adds the user to the new group.

On every login Collaborator actualizes user membership in groups. Such algorithm allows to keep a consistency between Collaborator and GitLab server.

When GitLab integration is disabled or deleted, synchronized groups will become disabled.

Synchronize Users and Groups in Command-Line Interface

The ccollab admin group sync command takes as input an XML file describing all the groups being synced, their relationships, and their member users. The XML format is simple and a full schema is provided: group-sync-xml.xsd (CTRL + click, or CMD + click to open in new window). For an example, see Use Groups for Organizational Hierarchy. The Collaborator administrator should write a script that queries the external system (that is, LDAP) and creates this XML. For an example of this script, see the description of the ccollab admin group sync command.

The Collaborator administrator should run the synchronization script periodically. Collaborator will examine the group synchronization XML file and make the appropriate changes in the system. Processing the synchronization is not very resource intensive, so you probably do not need to worry about load on the Collaborator server.

Add users

The group synchronization XML file describes which users are admins and/or members of which groups. There are two options if the XML describes users who do not yet have accounts in Collaborator, controlled by the --create-user option of the ccollab admin group sync command:

Create the member user – If the --create-user option is specified, a user account is created for the user.

Note: The user does not consume a license until they log in.
Ignore the member-user – If the --create-user option is not specified (default behavior), the member-user is ignored and a user account is not created. This is useful if you have a large organization but only a small subset of the employees are using Collaborator.

Remove groups

Groups may be removed from the external system. There are two options if the XML no longer describes a group which was created in an earlier synchronization, controlled by the --delete-groups option of the ccollab admin group sync command:

Delete the group – If the --delete-groups option is specified, the group is deleted. However, if the group cannot be deleted because it has associated reviews, an error is returned and the synchronization is canceled.
Disable the group – If the --delete-groups option is not specified (default behavior), the group is marked disabled. This always works, regardless of whether there are reviews associated with the group.

Rename groups

Groups are uniquely identified by a GUID which is specified in the group synchronization XML file. To rename the group, simply specify a group with the same GUID but a different title.

Manually created groups

Sometimes it is useful to synchronize groups with an external system but also manually specify some groups using the web client or the ccollab admin group create command. For an example, see Using Groups for Organizational Hierarchy and Projects. Collaborator keeps track of which groups were created using synchronization and which groups were created manually. Manually created groups are not deleted or disabled on subsequent syncs just because they are not in the group XML. The web UI displays a warning when manually editing a group that was created by the synchronization. Manually created groups can contain synchronized groups as children, but not vice-versa.

Synchronize Groups and Members