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, SAML single sign-on servers, 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.
connectionName="cn=read-only-admin,dc=example,dc=com"
connectionPassword="xxxx"
connectionURL="ldap://xxxx.com:389"
userPattern="uid={0},dc=example,dc=com"
roleBase="dc=example,dc=com"
roleSearch="(&(objectClass=groupOfUniqueNames)(uniqueMember={0}))"
allRolesMode="strictAuthOnly"
/>
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.
If users have multiple emails specified on the LDAP or Active Directory side, Collaborator will retrieve them and use the first of the emails for notifications. Email addresses should be separated by comma.
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 SAML single sign-on server
You may configure user and group synchronization between Collaborator and your SAML single sign-on server. In this case, Collaborator will retrieve user properties (email, first and last name) and their membership in groups from the single sign-on server when the users login.
To enable group synchronization with SAML SSO server:
- Open the Admin > Single Sign-On page.
- Locate your SAML SSO configuration in the SSO Configurations list and click Edit.
- In the MemberOf parameter field specify the name of SAML parameter which stores information about user membership in groups.
- Set the Enable SAML group sync setting to True.
- Optionally, enable the Allow new group creation to create new groups automatically.
- Optionally, use the Automatic group creation filter to specify what exactly groups should be created automatically.
- Press Save to apply changes and enable synchronization.
Collaborator retrieves user membership from the SAML single sign-on 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 Allow new group creation setting is enabled and if the group name matches the Automatic group creation filter, creates new group on success and adds the user to the new group.
Along with membership information, Collaborator is able to sync user permissions with SAML SSO server. If the User Role sync option is enabled, it will synchronize user roles between SAML and Collaborator servers. SSO accounts having admin privileges (Role = admin) will automatically become administrators on Collaborator server. SSO accounts having empty or any other value of the Role parameter will become regular users on Collaborator server.
Collaborator actualizes user properties, their membership in groups and permissions on every login. Such algorithm allows to keep a consistency between Collaborator and SSO server.
When SAML SSO integration is disabled or deleted, synchronized groups will become disabled.
Alternatively, you may configure user membership synchronization between Collaborator, SAML single sign-on server and LDAP directory or Active Directory. In this case, Collaborator will use single sign-on server to manage users, but will query user membership from the LDAP directory or Active Directory. See Configuring Single Sign-On via SAML for instructions on enabling this variant of sync.
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 and their membership in groups from the Crowd server when the users login.
To enable group synchronization with Crowd server:
- Open the Admin > Single Sign-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.
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.
Collaborator actualizes user membership in groups on every login. 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 and their membership in groups from the GitLab server.
To enable group synchronization with GitLab server:
- Open the Admin > Repository Hosting Services page.
- Set the global Enable Group Sync setting to Yes and press Save.
- 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.
To perform synchronization, your GitLab project should either belong to a group or be shared with a group of users.
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.
To match users, Collaborator compares their full names, usernames and email addresses.
Collaborator actualizes user membership in groups each time when it receives webhook data from a GitLab configuration having the Sync Groups setting enabled, as well as when you create or update GitLab configuration having the Sync Groups setting enabled. 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.
See Also
Licensing
Use Groups for Organizational Hierarchy and Projects
Groups