Contact usRequest a demo

User synchronization tool

This article describes how to configure Unblu to synchronize user data from your existing user management system, such as an LDAP server, to the Unblu database with the user synchronization tool (sync tool).

The sync tool is integrated into the Unblu server and offers the following functionality:

  • Loads users, teams, and roles from your user management system.

  • Stores new users and teams in the Unblu database.

  • Updates users (or their roles) and teams in the Unblu database.

  • Deletes users and teams that no longer exist in your user management system from the Unblu database.

  • Logs sync tool operations to the standard Unblu server log.

  • Provides a scheduler mode that accepts cron-like action scheduling.

The purpose of the sync tool isn’t to sync user credentials. Its purpose is to enable the configuration of users and teams in Unblu, and make them available for forwarding for example. If, in addition, you require single sign on (SSO) functionality, see Authentication.

For multi-tenancy installations, you can configure the sync tool directly from the Account Configuration interface (using superadmin credentials). For more information, see Multitenancy support.

The sync tool only connects to LDAP-based systems. For other user management systems, such as REST-based systems, you can use the Unblu web API and a custom tool to import users, teams and set roles.

How it works

  • The sync tool connects the source directory service.

  • It runs a query based on the configuration you define to load user, role, and team data into the target Unblu database.

  • With the loaded information, it creates internal user or team representations and maps the retrieved attributes to the model’s attributes.

Users are uniquely identified by a source ID from the user management system. This source ID is used to keep the LDAP users and Unblu users in sync. It’s configured using com.unblu.addons.synctool.ldap.userIdAttributeName, typically mapped to the cn LDAP attribute. In Unblu, the source ID is stored as a metadata property attached to the user.

The synchronization process consists of the following actions:

  1. Read all users and/or teams from LDAP (including any role attributes).

  2. Read all users and teams in the Unblu database.

  3. Sync teams based on their name. (No source ID is used for teams.)

    1. Delete teams that exist in the Unblu database but no longer exist in LDAP.

    2. Leave teams that already exist as they are.

      If a team with the same name already exists in Unblu, regardless of whether it was created by sync or manually, it’s left as it is.

    3. Create any teams that don’t exist in Unblu yet.

  4. Sync users based on their source ID.

    1. Delete users that exist in the Unblu database but no longer exist in LDAP.

    2. Update users that have a matching source ID but different data in the database.

    3. Create any users that don’t exist in the Unblu database yet.

    4. Leave any manually created users in Unblu as they are. These users have no source ID in their metadata.

The process depends on the configuration settings. For example, when using SYNC_USERS, teams aren’t synced.

The sync tool is unidirectional: it only synchronizes data from your user management system to the Unblu database, not the other way.

Adding, modifying, or deleting users using the sync tool doesn’t trigger user webhook events.

Overwriting users

When syncing users, the tool checks both the username and the source ID in the metadata. How the sync tool reacts if the metadata in the target differs from that provided by the source is specified in the configuration property com.unblu.addons.synctool.overwriteExistingTargetUsers:

  • If the configuration property is true, the tool overwrites users in the target.

  • If the configuration property is false, the tool logs a warning but leaves the affected users in the target untouched.

When you synchronize users and teams with the sync tool, they’re marked in Unblu as externally managed. This means that all attributes defined for synchronization must be set in your user management system to populate the Unblu database.

If you make changes to the synced attributes of users in the Agent Desk, those changes are lost the next time the sync tool runs. However, changes to unsynced attributes persist.

Other information, such as canned responses, can be set from within the Agent Desk and persists if not bound to a user or team. If the information is bound to a user or team, and the sync tool deletes that user or team, then that information is lost.

For example, you sync a user with the following LDAP attributes:

dn: cn= Mary,ou=Users,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Mary
sn: Somerville
mail: mary.somerville@scientist.com
uid: somerville
givenName: Mary
userPassword:: <password>

In Unblu, this maps to:

{
"$_type": "User",
"id": "Qs4BHK06TpGSgwcmaNqfHQ",
"creationTimestamp": 1654005318291,
"modificationTimestamp": 1654005318291,
"version": 1,
"accountId": "wZvcAnbBSpOps9oteH-Oxw",
"avatar": null, (1)
"username": "Mary",
"email": "mary.somerville@scientist.com",
"phone": null,
"teamId": "JZh4ADRnEeasYZ5xEoyudw",
"authorizationRole": "REGISTERED_USER",
"displayName": "Mary Somerville",
"firstName": "Mary",
"lastName": "Somerville", (2)
"externallyManaged": true,
"virtualUser": false,
"configuration": null,
"metadata": {
    "synctool.user.sourceid": "somerville",
    "$_version": "dd11ca189567a04ac339c0fa33586198"
            }
}
1 If you add a profile photo to this user in the Agent Desk, the profile photo persists even after you sync. This is because no avatar attribute is present in the source user management system.
2 If you change the user’s last name to Fairfax in the Agent Desk, the change doesn’t persist after you sync. This is because the sn attribute is present in the source user management system. When you sync, the user’s last name is updated in Unblu to match the source.

Deleting users and teams

To delete synced users or teams from the Unblu database, set the configuration property com.unblu.addons.synctool.allowAutoDeletion to true. That way, entities created by the sync tool are removed from the Unblu database if they’ve been deleted from your user management system.

Other users and teams aren’t deleted.

Synced users aren’t deleted from Unblu if the propagateDeletes property is set to the default false.

To avoid disassociating existing conversations from user IDs, deleting should be done with caution and only after making a backup of the database.

Deciding what you want to synchronize

You must decide what data you want to retrieve from your user management system and what data you want to manage in Unblu.

There are different approaches:

  1. Sync both users and teams.

    If the existing data structure in your system fits how you want to structure your visitor engagement teams, sync both teams and users.

    The sync tool doesn’t reproduce nested team structures. They must be recreated manually in the Account Configuration interface before the first sync runs. The team names must match exactly.

  2. Sync only users.

    If your data structure doesn’t fit how you want to use Unblu, you can sync only users and disregard teams. Synced users are added to a default team.

  3. Sync teams first, restructure them in Unblu, and then sync users and teams.

    If you want to use the sync tool to create teams but you need to restructure them to reproduce nesting, you can sync in two phases. First, just sync teams to create them. Restructure the teams in Unblu. Then sync both users and teams once you have restructured.

Authentication

Synchronizing user data from your user management system doesn’t automatically allow agents to log in to Unblu with their organization-wide credentials. With additional configuration, however, you can put single sign-on (SSO) in place. Use a system that does authentication in front of Unblu and match the username provided by that system with the one synced from LDAP.

Similarly, Unblu can’t synchronize the passwords and directly authenticate against the LDAP server.

The most common solution for this is to implement ID propagation, with a web application firewall (WAF) or proxy handling the authentication and then providing Unblu with the user ID. For more information, see Authentication source PROPAGATED.

Another option for agents is to configure OpenID connect (OIDC) and provide the token in an Authorization: Bearer HTTP header. For more information, see Opaque access tokens.

Configuration

The sync tool is integrated into the Unblu server but doesn’t run by default. To use it, you must configure it in the unblu.properties file or as a superadmin in the Agent Desk:

  • Connect Unblu to your LDAP server.

  • Specify the search scopes and filters.

  • Map the Unblu user and team attributes to entity attributes in the source.

  • Map authorization roles.

  • Configure scheduling.

LDAP server connection

Set the following properties to connect to your user management system:

When using LDAPS or STARTTLS, you may be required to provide a Java keystore or truststore containing either a client certificate or the Certificate Authority that signed the SSL certificates:

Filters and scopes

Set the following properties to specify the search filters and scopes used to query the directory service and retrieve user information:

User and team attribute mapping

Every user can belong to exactly one team only.

If your users belong to more than one team in your user management system, a warning appears in the Unblu log when the sync tool runs: Trying to assign user to another team: User:{}, new team would have been {}. Upon syncing, the user is only assigned to the first team found by the tool.

Which team is found first by the tool is unpredictable. Make sure your users only belong to a single team in your user management system before syncing.

Newly-created users that have no team applied belong to the default team. This is also the case when syncing only users and not teams.

The sync tool can insert and delete teams but it can’t update them. If you rename a team in your user management system, Unblu deletes the team and creates a new team, so any previous team settings are lost.

User synchronization configuration properties

  • com.unblu.addons.synctool.ldap.userIdAttributeName: The attribute name for a field/string that uniquely identifies a user (for example, Employee Number). This attribute is used as the synctool.user.sourceid in the metadata added to the user. It’s a unique identifier that lets you reliably sync between your user management system and Unblu.

  • com.unblu.addons.synctool.ldap.userNameAttributeName: The name of the attribute whose value is the user’s username.

    The userName is the identifier that needs to be passed to Unblu for authentication. It must be identical to the JEE Principal or Trusted Header UserId and must also be specified in the user management system.

    Note that userName has an unknown structure and format. The only thing that can be assumed is that it’s a string. In single sign-on (SSO) implementations, the userName is what the corresponding system delivers as output from the authentication process. That can be a technical ID like "i12345", a name like "John Doe", or anything else that can be represented by a string.

  • com.unblu.addons.synctool.ldap.userEmailAttributeName: (Optional) property containing the user’s email.

  • com.unblu.addons.synctool.ldap.userLastNameAttributeName: (Optional) property containing the user’s last name.

  • com.unblu.addons.synctool.ldap.userFirstNameAttributeName: (Optional) property containing the user’s first name.

See below for an example of how the configuration properties affect synchronization.

Team synchronization configuration properties

See below for an example of how the configuration properties affect synchronization.

Authorization role mapping

Authorization roles are purely technical roles. The Unblu role hierarchy bears no relationship to any internal roles in your organization.

The authorization role identifier is an attribute of a user, not of a team.

The current authorization roles in hierarchical order are:

  • SUPER_ADMIN

  • TECHNICAL_ADMIN

  • ADMIN

  • SUPERVISOR

  • REGISTERED_USER

In the context of the sync tool, SUPER_ADMIN, ADMIN, SUPERVISOR and REGISTERED_USER are relevant.

  • SUPER_ADMIN has the same rights as the ADMIN role, and also has access to the Global Server Configuration interface, enabling users to create and manage accounts on the Unblu server.

  • ADMIN has rights related to the account and all teams and users in the account.

  • SUPERVISOR has rights related to their team and the users who are member of their team.

  • REGISTERED_USER only has rights regarding themselves.

Unblu only allows a user to have a single role assigned to them. If a user has multiple roles assigned in LDAP, the highest corresponding role in the Unblu role hierarchy is assigned in Unblu. For example, if a user has both the ADMIN and REGISTERED_USER role in LDAP, they’re assigned the ADMIN role in Unblu.

Authorization role configuration properties

Grant roles according to how you intend to use the Agent Desk.

See below for an example of how the configuration properties affect synchronization.

Configuring role filters

If you want all users to have the same role, provide a dummy roleFilter and leave the role identifiers undefined; all users then get the defaultRole. The roleFilter is only executed for RoleIdentifiers that are explicitly defined and, by default, RoleIdentifiers aren’t defined.

The roleFilter should be an LDAP query with a %role% placeholder like in this example:

com.unblu.addons.synctool.ldap.roleFilter=(&(objectClass=groupOfNames)(cn=%role%))

The role filter is called by replacing the %role% with the values defined by:

The role filter should have one result with a member attribute containing all user IDs with that particular role.

The attribute containing the members (default: member) is defined with com.unblu.addons.synctool.ldap.roleMemberAttributeName.

The userFilter should return all users that should be processed by the sync tool.

The sync tool retrieves both the list of users and the list of users with a given role.

It then works through the users and determines which role a given user is assigned:

  • The highest role wins and is assigned to the user.

  • If the user isn’t assigned any of the roles:

    • If defaultRole is defined, the user is assigned that role.

    • if defaultRole isn’t defined, the user is ignored in the LDAP system by the tool and isn’t added to the Unblu database. If you can’t find a user in Unblu that you know exists in LDAP, check the log file for errors.

See below for an example of how the configuration properties affect synchronization.

Scheduling

You can configure the sync tool to run according to a synchronization schedule.

To run the sync tool according to a schedule, use the configuration property com.unblu.addons.synctool.runAtCronExpressions. The value of the property is list of strings, each consisting of a valid cron expression and an action.

The action must be one of SYNC_TEAM, SYNC_USER, and SYNC_ALL. The names of the actions aren’t case sensitive.

The default behavior of the tool is to sync everything, but you can sync only user or only team data if required. For example, if the user information hasn’t changed but team structure has. When you sync all, teams are synced first then users.

For quartz cron expressions, see the quartz documentation. In addition to quartz cron expressions, you can use @reboot to indicate that the action should be executed once when the Unblu server starts.

In cluster setups, @reboot checks if the whole cluster was restarted. If just one node restarts, it logs a message such as Reboot command has already been executed at one of the cluster nodes.

In the example below, everything is synchronized (SYNC_ALL= teams and users) when the Unblu server starts (@reboot) and every 15 minutes after that.

com.unblu.addons.synctool.runAtCronExpressions=["@reboot SYNC_ALL","0 */15 * * * ? SYNC_ALL"]

Sample configuration

## Scheduling
com.unblu.addons.synctool.runAtCronExpressions=["@reboot SYNC_ALL","0 */15 * * * ? sync_all"]

## Connection
com.unblu.addons.synctool.ldap.serverHostname=<LDAP server hostname or IP address>
com.unblu.addons.synctool.ldap.serverPort=<LDAP server port>
com.unblu.addons.synctool.ldap.connectionSecurity=LDAPS
com.unblu.addons.synctool.ldap.serverUsername=CN=*****,OU=AdminAccounts,OU=AdminRoles,DC=corp,DC=ch
com.unblu.addons.synctool.ldap.serverPassword=*****
com.unblu.addons.synctool.ldap.pathToTrustedCertsKeyStoreFile=<path to keystore file>
com.unblu.addons.synctool.ldap.trustedCertsKeyStorePassword=<password to read the keystore file>

## Filters & Scopes
com.unblu.addons.synctool.ldap.baseDN=DC=corp,DC=ch
com.unblu.addons.synctool.ldap.userFilter=(&(objectClass=person)(memberOf=CN=%team%,OU=Prd_DG-OE,OU=Prd_SecGlobal,OU=Prd_Group,OU=Prd_Org,OU=Prd,DC=corp,DC=ch))
com.unblu.addons.synctool.ldap.userSearchScope=SUBTREE
com.unblu.addons.synctool.ldap.roleFilter=(&(objectClass=group)(CN=%role%))
com.unblu.addons.synctool.ldap.roleSearchScope=SUBTREE
com.unblu.addons.synctool.ldap.teamFilter=(&(objectClass=group)(|(CN=Unblu_Chat)(CN=Unblu_User)))
com.unblu.addons.synctool.ldap.teamSearchScope=SUBTREE

## Attribute Mapping
com.unblu.addons.synctool.ldap.userIdAttributeName=cn
com.unblu.addons.synctool.ldap.userNameAttributeName=displayName
com.unblu.addons.synctool.ldap.userEmailAttributeName=mail
com.unblu.addons.synctool.ldap.userLastNameAttributeName=sn
com.unblu.addons.synctool.ldap.userFirstNameAttributeName=givenName
com.unblu.addons.synctool.ldap.teamIdAttributeName=cn

## Role Mapping
com.unblu.addons.synctool.ldap.superadminRoleIdentifier=Unblu-Role_Super_Admin
com.unblu.addons.synctool.ldap.adminRoleIdentifier=Unblu-Role_Admin
com.unblu.addons.synctool.ldap.supervisorRoleIdentifier=Unblu-Role_Supervisor
com.unblu.addons.synctool.ldap.registeredUserRoleIdentifier=Unblu-Role_Registered_User
com.unblu.addons.synctool.ldap.defaultRole=REGISTERED_USER

Examples

The examples below are intended to give you a better idea of how properties in a user management system are matched to Unblu entity properties. They also show how you must configure Unblu to achieve a particular mapping.

Teams

Consider the following excerpt of an LDIF file describing an organization:

Listing 1. LDIF extract describing the helpdesk team and its members 
dn: ou=teams,ou=groups,dc=bank,dc=com
objectClass: organizationalUnit
objectClass: top
ou: teams

dn: cn=helpdesk,ou=teams,ou=groups,dc=bank,dc=com
objectClass: groupOfNames
objectClass: top
cn: helpdesk
member: uid=adele.goldberg@bank.com,ou=people,dc=bank,dc=com
member: uid=grace.hopper@bank.com,ou=people,dc=bank,dc=com
member: uid=morris.kline@bank.com,ou=people,dc=bank,dc=com

To create the helpdesk team in Unblu with the same members, set the following configuration properties:

Listing 2. Configuration properties for synchronizing teams and team membership 
config:com.unblu.addons.synctool.ldap.teamFilterBaseDN[PROPERTIES,ou=teams,ou=groups,dc=bank,dc=com]
config:com.unblu.addons.synctool.ldap.teamFilter[PROPERTIES,(objectClass=groupOfNames)]
config:com.unblu.addons.synctool.ldap.teamIdAttributeName[PROPERTIES,cn] (1)
config:com.unblu.addons.synctool.ldap.teamMemberAttributeName[PROPERTIES,member] (2)
1 The value of the cn node of each result matching the team filter is used as the team name in Unblu. The ID of the team in Unblu is generated by Unblu
2 This configuration property isn’t strictly necessary, because its default value is member. each member node of a result matching the team filter is added to the Unblu team as an Unblu user.

On the basis of this LDIF excerpt and Unblu configuration, synchronization creates the following Unblu team:

Listing 3. Helpdesk team after synchronization 
{
    "$_type": "Team",
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": null,
    "configuration": null,
    "creationTimestamp": 1688969822247,
    "description": null,
    "externallyManaged": true,
    "id": "QwBSjy5bQUm-X0J-qKzF3A",
    "metadata": null,
    "modificationTimestamp": 1688969822247,
    "name": "helpdesk",
    "parentId": "JZh4ADRnEeasYZ5xEoyudw",
    "translations": {},
    "version": 1
}

In both cases, the value of the cn node has been added as the team’s name.

Users

In the previous section, the helpdesk team was said to have three members, a manager and two helpdesk agents. The LDIF file excerpt below shows how they’re defined:

Listing 4. LDIF excerpt describing the members of the helpdesk team 
dn: uid=grace.hopper@bank.com,ou=people,dc=bank,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Grace Hopper
sn: Hopper
givenName: Grace
uid: grace.hopper@bank.com
userPassword:: <password>

dn: uid=adele.goldberg@bank.com,ou=people,dc=bank,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Adele Goldberg
sn: Goldberg
givenName: Adele
manager: uid=grace.hopper@bank.com,ou=people,dc=bank,dc=com
uid: adele.goldberg@bank.com
userPassword:: <password>

dn: uid=morris.kline@bank.com,ou=people,dc=bank,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: Morris Kline
sn: Kline
givenName: Morris
manager: uid=grace.hopper@bank.com,ou=people,dc=bank,dc=com
uid: morris.kline@bank.com
userPassword:: <password>

Note that this organization decided to create the entries don’t have a mail node, since they use a person’s email address as their UID. In Unblu, they want users to be able to log in with their name. They also want users' email addresses to be available as such in Unblu.

The employees' roles are defined in groups:

Listing 5. LDIF excerpt assigning users a role 
dn: ou=roles,ou=groups,dc=bank,dc=com
objectClass: organizationalUnit
objectClass: top
ou: roles

dn: cn=managers,ou=roles,ou=groups,dc=bank,dc=com
objectClass: groupOfNames
objectClass: top
cn: managers
member: uid=grace.hopper@bank.com,ou=people,dc=bank,dc=com

dn: cn=helpdesk agents,ou=roles,ou=groups,dc=bank,dc=com
objectClass: groupOfNames
objectClass: top
cn: helpdesk agents
member: uid=adele.goldberg@bank.com,ou=people,dc=bank,dc=com
member: uid=morris.kline@bank.com,ou=people,dc=bank,dc=com

The organization wants to assign managers the SUPERVISOR user role. All other users should have the REGISTERED_USER user role.

The following Unblu configuration accomplishes what the organization wants:

Listing 6. Configuration properties for synchronizing users 
config:com.unblu.addons.synctool.ldap.userFilter[PROPERTIES,(objectClass=inetOrgPerson)]
config:com.unblu.addons.synctool.ldap.userIdAttributeName[PROPERTIES,uid]
config:com.unblu.addons.synctool.ldap.userNameAttributeName[PROPERTIES,cn]
config:com.unblu.addons.synctool.ldap.userEmailAttributeName[PROPERTIES,uid]
config:com.unblu.addons.synctool.ldap.userLastNameAttributeName[PROPERTIES,sn]
config:com.unblu.addons.synctool.ldap.userFirstNameAttributeName[PROPERTIES,givenName]

# Role matching
config:com.unblu.addons.synctool.ldap.defaultRole[PROPERTIES,REGISTERED_USER]
config:com.unblu.addons.synctool.ldap.roleFilter[PROPERTIES,(&(objectClass=groupOfNames)(cn=%role%))]
config:com.unblu.addons.synctool.ldap.roleFilterBaseDN[PROPERTIES,ou=roles,ou=groups,dc=bank,dc=com]
config:com.unblu.addons.synctool.ldap.supervisorRoleIdentifier[PROPERTIES,managers]

After synchronization based on the LDIF excerpts and the Unblu configuration above, Unblu contains the following users:

Listing 7. Users after synchronization 
{
    "$_type": "User",
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "authorizationRole": "REGISTERED_USER", (1)
    "avatar": null,
    "configuration": null,
    "creationTimestamp": 1688969822537,
    "displayName": "Morris Kline", (2)
    "email": "morris.kline@bank.com", (3)
    "externallyManaged": true,
    "firstName": "Morris",
    "id": "wYrYsRJ5RluD-nQ5fd_vDg", (4)
    "lastName": "Kline",
    "metadata": {
        "$_version": "30ae5558911489332b836cdeff840344",
        "synctool.user.sourceid": "morris.kline@bank.com" (4)
    },
    "modificationTimestamp": 1688969822581,
    "phone": null,
    "teamId": "QwBSjy5bQUm-X0J-qKzF3A", (5)
    "username": "Morris Kline", (6)
    "version": 3,
    "virtualUser": false
},
{
    "$_type": "User",
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "authorizationRole": "SUPERVISOR", (1)
    "avatar": null,
    "configuration": null,
    "creationTimestamp": 1688969822275,
    "displayName": "Grace Hopper",
    "email": "grace.hopper@bank.com",
    "externallyManaged": true,
    "firstName": "Grace",
    "id": "z3OlTkoVTGOSeXzTJTB5WQ",
    "lastName": "Hopper",
    "metadata": {
        "$_version": "a466dee8687a093fab4e1d81f99d169a",
        "synctool.user.sourceid": "grace.hopper@bank.com"
    },
    "modificationTimestamp": 1688997800037,
    "phone": null,
    "teamId": "QwBSjy5bQUm-X0J-qKzF3A", (5)
    "username": "Grace Hopper",
    "version": 6,
    "virtualUser": false
},
{
    "$_type": "User",
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "authorizationRole": "REGISTERED_USER", (1)
    "avatar": null,
    "configuration": null,
    "creationTimestamp": 1688969822469,
    "displayName": "Adele Goldberg",
    "email": "adele.goldberg@bank.com",
    "externallyManaged": true,
    "firstName": "Adele",
    "id": "R0HcYSw5SYOON6awbpYdMg",
    "lastName": "Goldberg",
    "metadata": {
        "$_version": "53d2aa12b7545a13ccc06249a7d110de",
        "synctool.user.sourceid": "adele.goldberg@bank.com"
    },
    "modificationTimestamp": 1688969822500,
    "phone": null,
    "teamId": "QwBSjy5bQUm-X0J-qKzF3A", (5)
    "username": "Adele Goldberg",
    "version": 3,
    "virtualUser": false
}
1 The users with the role helpdesk agent were assigned the Unblu user role REGISTERED_USER. The teams’s manager has been assigned the user role SUPERVISOR.
2 The display name isn’t synchronized directly. Instead, it’s determined by the synchronized values and other configuration properties. For more information, refer to User name display configuration.
3 The email address was taken from the uid node.
4 As described above, the Unblu user ID isn’t controlled by the uid node specified in com.unblu.addons.synctool.ldap.userIdAttributeName. Unblu generates the value when it creates the user.

The uid node is added to the user’s metadata as the sourceId.
5 The teamId refers to the id of the team created in the previous section.
6 The username is the value of cn node.

Multitenancy support

The sync tool supports multitenancy usage. Multitenancy is an architecture in which you run multiple Unblu accounts on a single Unblu server.

Each account on the server may connect to the same user management system but have different configurations.

Typically, some configuration properties could be shared and therefore be defined globally. For example, if only one user management system is used as the source to sync all accounts, it may make sense to configure the user management system using the LDAP hostname, port and other server-specific settings globally.

Then, for each account, you could define different configurations for the filters and scopes.

Multitenancy syncing limitations

Multitenancy syncing has some limitations compared to syncing a single account:

  1. Usernames must be globally unique. You can’t have two users with the username 'johndoe' in different accounts, for example. If the username isn’t unique, the existing user is preserved. Syncing any additional new users with the same username fails because the username already exists.

  2. The sync schedule can’t be configured per account. All accounts are synced sequentially according to the globally configured schedule.

Global-level configuration for multitenancy

To enable multitenancy support, the following properties must always be configured globally:

Account-level configuration for multitenancy

The com.unblu.addons.synctool.ldap.baseDN property must be set at the account level.

All the other properties from the Configuration section may be set in the GLOBAL or ACCOUNT scope.

You can configure the sync tool at the account level with the Account Configuration interface using superadmin credentials:

  1. Log in to the Account Configuration interface with superadmin credentials and click Settings in the sidebar menu.

  2. Click Advanced to open the filter options.

  3. Tick the options Key and Show internal.

  4. In the filter text field, enter LDAP. This displays all the configuration properties you need to adapt.

  5. Edit the settings and click Save.

The account is now configured to synchronize users with your user management system. The synchronization process runs according to the globally configured schedule.

Monitor the Unblu server log for potential sync errors.

Syncing users in Unblu cluster installations

No matter how many Collaboration Server pods are running in your cluster, Unblu makes sure that each user synchronization is only run on one of those pods.

You need only define one server as the Leader Activator.

See also

  • For more information about how you can control which changes to externally managed entities are possible within Unblu, see Externally managed users and teams. Entities created and updated by LDAP have the attribute externallyManaged set to TRUE.

  • For more information about authentication, see Authentication, and Identity propagation in particular.