|
This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version. The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu. |
User management synchronization tool (optional)
Given the presence of an LDAP (or similar) server, any enterprise that wants to use their current staff information, held in their identity management system, can map that information into the Collaboration Server on a one-to-one basis. This means that, after the initial setup, existing organizational structures can be mapped to the collaboration server. The tool can then be run according to a schedule in order to ensure that current staff data properly populates the database.
| If you intend to run Unblu in a cluster then you need only define one server as the Leader Activator. |
| Employing the synchronization tool is not a purely technical decision. For example, the way you configure the synchronization tool can have a significant impact on how you use the Agent Desk (as different syncing strategies directly affect how you interact with the Agent desk). In short: You can sync everything; which will give your identity management system precedence, and thus the Agent Desk will reflect the team design already held within your system. Or, if you want to retain flexibility, then you can tell the sync tool not to synchronize teams. This will allow you to sync everything except teams, which you can then build and manipulate from within the Agent Desk interface. |
You may also want to read about Identity Propagation or Authentication in general.
Set up the user management synchronization tool (optional)
Use the topics below first to decide if you want to implement the User Management Synchronization tool, then to implement it.
Overview
In on-premises installations, customers often have an existing central user identity management system where all modifications are applied using the enterprise’s own processes.
| We have used LDAP here in order to highlight the concepts of the user management synchronization tool, but it is possible to use other identity management access technologies. If you prefer to use something else (for example, a REST-based identity management system) then talk to us about it. |
The tool syncs from your own identity management system to the database. This is a one-way synchronization. That means that if you decide to use the synchronization tool you must choose which attributes/entities should be driven by the synchronization tool accessing your identity management system and which attributes/entities are to be handled from within the Agent Desk, or from within the unblu.properties file.
It is important to put some serious thought into choosing the right synchronization strategy as there are consequences. For example, it makes sense, in a large complex organization, not to have many systems carrying duplicate user data. You already have the data ordered within your own identity management system so syncing should be a perfect solution. However, if you decide, for example, to sync all (teams and users) then this would require you to have confidence that current team structures are entirely appropriate for how you want to use the Unblu product(s). This is because when you ascribe precedence to your own identity management system you will not then be able to manage teams from within the Agent Desk.
| You may be able to enjoy the best of both worlds by syncing users but not teams. In this way you could still use the Agent Desk to create (team) structures on-the-fly that will persist through synchronizations. Syncing users but not teams can be an ideal strategy for a large organization who may be unsure as to exactly how they want to structure their visitor-engagement teams. When you are sure you have defined exactly the right structure (by experimenting inside the Agent Desk), you can then define the teams structure on your identity management system. In this way you can use the flexibility of the Agent Desk in combination with the efficiency of drawing data and data structures from your own identity management system. A caveat here is that handling teams from within the Agent Desk means that you would have to assign users manually, which can be time consuming and prone to error. Also note that the synchronization tool cannot reproduce nested team structures; nesting must be defined from within the Agent Desk. |
The user management synchronization tool can insert or delete teams but it cannot update them. Team is not a standalone entity; if there are no users are assigned to a team then that team, as far as the Unblu Server is concerned, does not exist. If you try to rename a team from within the LDAP directory Unblu will drop/delete that team and create a new team, so your previous team settings would be lost.
The user management synchronization tool is integrated into the Collaboration Server but it will not start by default. In order to use the tool you must first configure it in the unblu.properties file. See Synchronization tool configuration for more on how to get up and running with the user management synchronization tool. |
| You can also configure the synchronization tool from directly within the Agent Desk at the Account level. Note that while configuring the synchronization tool via the Agent Desk is possible it is probably only useful for multi-tenancy installations; as it requires superadmin credentials. See Per-account configuration. |
When the user management synchronization tool starts it queries the identity management system using LDAP for users. Users are (uniquely) identified by a source ID supplied by the identity management system. This source ID is used to keep the LDAP users and Unblu users in sync.
If you decide to synchronize from your identity management system using LDAP, synchronization tool precedence means that all attributes defined for synchronization must be set on the LDAP server in order to populate the Collaboration Server database. If you make changes from within the Agent Desk those changes will be lost the next time the synchronization tool runs (if you have defined that attribute to be synced).
The first time the tool runs it will sync all users and associated attributes. After this initial run the database will remain relatively unchanged with only the differences being synchronized.
As an example, if you currently have a team of 100 generalists dealing with incoming requests and a second team populated by specialists, this same structure will exist within the Collaboration Server after the synchronization tool is run. In this example the first team would deal with the initial visitor engagement then forward those visitors accordingly to the second team, or members within the second team.
The identity management system using LDAP should also contain the authorization role (Admin, Supervisor, Registered User, etc.) that the Collaboration Server requires to grant users the appropriate permissions.
Other information, such as languages or canned responses, can be set from within the Agent Desk and will persist if not bound to a user or team. If they are bound to a user or team and the synchronization tool deletes that user or team then that information will be lost. You can, for example, define these settings at the Account or Global level. But if you, for example, add a new user or team from within the Agent Desk, the next time the synchronization tool runs those users or teams will be lost.
| The default behavior of the tool is to sync everything but user and team parameters can be synced separately. This means you can either sync users or, if the team structure has changed but not user information, you can sync just teams. |
| The Authorization Role identifier is an attribute of the user, not an attribute of the team. Technically, one could create teams populated with many supervisors, if one wished. This means that the rule of one supervisor per team, for example, must be enforced by you, and written from your LDAP system to the Unblu Server. These design options allow you to, for example, create a whole team of supervisors in order that they can see everything downstream. This would mean a team of supervisors at the top level that can see all users and child teams below them. |
Other information, such as First Name/Last Name, email address, etc., are handled as soft identifiers. This means that the information is not a technical requirement and that the synchronization tool will accept any information with the correct data type (i.e., string). |
General functionality
The tool has the following base functionality:
-
Is integrated into the collaboration server.
-
Provides a scheduler mode that accepts a cron-like action scheduling.
-
Loads entities (users, teams) from a central User Management System.
-
Stores new retrieved entities (users, teams) in Unblu.
-
Deletes entities (users, teams) from Unblu that no longer exist in the central User Management System.
-
Synchronizes changes from users in the central User Management System to Unblu.
-
Only separate syncing of users or teams is allowed. (When syncing all: teams are synced first then users.)
-
Is configurable (mostly for the entity reader/writer parts, which can require a larger number of options that do not make sense as command-line arguments).
-
Logs to the standard Unblu server log.
| Simply synchronizing user data will not allow Agents to log in to Unblu with their organization-wide credentials. For this, you must ensure authentication by another system and configure some form of Identity propagation. |
User model
The User Model describes how to create the implementation (internally to your organization) in order that data can be transferred from the source (your identity management system using LDAP) to the target (the Collaboration Server).
A user entity model consists of the following parts:
-
SourceId: A unique identifier which allows you to reliably sync between the central User Management System and Unblu (such as employee #)
-
UserName: UserName is the identifier within the Unblu system. 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 is a string (which does include it being a number). In SSO implementations, the UserName is what the corresponding system delivers as output from the authentication process. In reality, that can be technical IDs like i12345, names like John Doe or anything else that can be represented by a string.
-
Authorization role
-
TeamName
-
Email (optional)
-
FirstName (optional)
-
LastName (optional)
Authorization roles
Note: Authorization Roles are purely technical roles; in that the Unblu role hierarchy bears no relationship to any internal roles in your organization. The roles should be granted according to how you intend to use the Agent Desk.
Current Authorization Roles are: SUPER_ADMIN, ADMIN, SUPERVISOR, REGISTERED_USER.
Authorization Roles are hierarchical (SUPER_ADMIN is the highest / root node, REGISTERED_USER the lowest role).
In the context of the synchronization tool, only ADMIN, SUPERVISOR and REGISTERED_USER are relevant. ADMIN has rights related to the account, all teams and all users. SUPERVISOR has rights related to their team and contained users and REGISTERED_USER only has rights regarding themselves.
Unblu only allows a user to have exactly one role assigned. If a user has multiple roles assigned in LDAP, the highest role in the Unblu role hierarchy will be assigned in Unblu. If a user has both the ADMIN and REGISTERED_USER role in LDAP, they will be assigned the ADMIN role in Unblu.) |
For more on Authorization Roles see: The Hierarchical Nature of the Model
Team
A team is a grouping entity for users:
Any user can only belong to exactly one team.
A newly-created user that has no particular team applied belongs to a default team.
Teams can be nested. (But the synchronization tool cannot reproduce nested teams.)
Teams are relevant for applying Unblu configurations (it is a configuration scope).
A configuration applied for team A automatically also applies to nested child teams A1 and A2 and all users belonging to A, A1 or A2.
Tool actions
The synchronization tool supports the following actions:
-
Synchronization of team information.
-
Synchronization of user information.
-
Synchronization of everything (that is: includes 1. and 2. in that order)
-
Scheduled mode.
The tool allows you to specify a list of synchronization schedules. Each synchronization schedule consists of a cron-like expression describing when to execute an action (syncteam, syncuser, syncall).
Entity source (internal identity management system)
The tool has the functionality to load entities from an entity source. Entities to load are team or user entities. The design of the tool is done in such a way that loading the entities can be implemented using various technologies (i.e., there is an interface for an EntitySource part with an initial implementation using LDAP to load entities).
LDAP access
LDAP is the initial protocol to use to retrieve users from a central user management system.
The tool supports access to the identity management system using normal LDAP or with startTLS.
The tool first binds and then executes searches with the given configuration (see LDAP-Based Entity Reader Configuration) in order to load team or user information.
With the loaded information it creates internal user or team representations and maps the retrieved attributes to the model’s attributes.
Entity target (Unblu database)
The tool has the ability to store entities in an entity target (in our case; the Database). Entities to store are team or user entities.
The writing process consists of the following actions per entity type (team or user):
-
Retrieve all entity IDs that currently exist in the entity writing target (i.e., the database)
-
For each entity read from the source (e.g. LDAP):
-
Check if an entity for the given entity ID already exists
-
If it does exist, update it
-
If it does not exist, create it
-
From entityIDsBeforeWrite remove the given entity ID
-
-
Delete all entities that are still in entityIDsBeforeWrite (they no longer appear to exist in the entity source / LDAP).
Scheduling configuration
If the tool is running in scheduling mode it must be configured using the following configuration keys: com.unblu.addons.synctool.runAtCronExpressions: A list of cron expressions strings. Each string must contain a valid cron (time) expression and an action. The action is one of syncteam, syncuser, syncall.
For quartz cron expressions see the quartz documentation. Additionally to the quartz cron expressions the expression @reboot may be used to indicate that the action should be executed once when the Collaboration Server starts.
Example:
To enable the sync tool add (and adapt) the code below to your unblu.properties file
com.unblu.addons.synctool.runAtCronExpressions=["@reboot syncall","0 */15 * * * ? syncall"]
The setting above will synchronize everything (syncall=teams and users) every 15 minutes. All other configuration options (server, teams, roles) are listed below. |
LDAP-based entity reader configuration
The following parts of the LDAP reader are configurable:
com.unblu.addons.synctool.ldap.connectionSecurity: Indicate whether the connection to the identity management system using LDAP should be done using LDAPS, STARTTLS, NONE.
com.unblu.addons.synctool.ldap.serverUsername: User to use to bind; may need the "cn="-Prefix.
com.unblu.addons.synctool.ldap.serverPassword: Password to use to bind.
com.unblu.addons.synctool.ldap.baseDN: The root DN for all records.
com.unblu.addons.synctool.ldap.userFilter: The filter to use when retrieving user entities.
com.unblu.addons.synctool.ldap.userSearchScope: LDAP Search Scope: OBJECT, ONELEVEL, SUBTREE.
com.unblu.addons.synctool.ldap.roleFilter: LDAP filter to retrieve all Unblu roles (if they are a groupOfNames); must contain %role% as a wildcard for all roleIdentifiers.
com.unblu.addons.synctool.ldap.roleSearchScope: LDAP Search Scope: OBJECT, ONELEVEL, SUBTREE.
com.unblu.addons.synctool.ldap.teamFilter: The filter to use when retrieving team entities.
com.unblu.addons.synctool.ldap.teamSearchScope: LDAP Search Scope: OBJECT, ONELEVEL, SUBTREE.
LDAP attribute mapping
The following configuration is required to map LDAP attributes to entity model attributes.
User attribute mapping
com.unblu.addons.synctool.ldap.userIdAttributeName: The attribute name for a field/string that uniquely identifies a user (for instance; Employee Number).
com.unblu.addons.synctool.ldap.userNameAttributeName: The name of the attribute whose value is the user’s username.
| This is the identifier that needs to be passed to Unblu for authentication (JEE Principal/ Trusted Headers UserID). |
com.unblu.addons.synctool.ldap.userEmailAttributeName: (Optional) property which contains user’s email.
com.unblu.addons.synctool.ldap.userLastNameAttributeName: (Optional) property which contains user’s last name.
com.unblu.addons.synctool.ldap.userFirstNameAttributeName: (Optional) property which contains user’s first name.
Team attribute mapping
com.unblu.addons.synctool.ldap.teamIdAttributeName: The name of the attribute which contains the team name.
com.unblu.addons.synctool.ldap.teamMemberAttributeName : (default member) the name of the attribute(s) which contains users within that team.
Authorization role
com.unblu.addons.synctool.ldap.roleMemberAttributeName : (Default member) the name of the attribute(s) which contains users that have that role.
com.unblu.addons.synctool.ldap.superadminRoleIdentifier: The name of the group that contains super admins. Will be substituted for %role% in the roleFilter.
com.unblu.addons.synctool.ldap.adminRoleIdentifier: The name of the group that contains admins. Will be substituted for %role% in the roleFilter.
com.unblu.addons.synctool.ldap.supervisorRoleIdentifier: The name of the group that contains supervisors. Will be substituted for %role% in the roleFilter.
com.unblu.addons.synctool.ldap.registeredUserRoleIdentifier: The name of the group that contains agents. Will be substituted for %role% in the roleFilter.
com.unblu.addons.synctool.ldap.defaultRole: (Optional) The default role for users that otherwise are not assigned a role (One of: SUPER_ADMIN, ADMIN, SUPERVISOR, REGISTERED_USER).
Multitenancy support
| Normally, all Collaboration Server users are associated with a single account but multitenancy allows users to be assigned to multiple accounts. |
The synchronization tool supports multitenancy usage. That is, syncing different Unblu accounts, each with (potentially) different configurations. For instance, each account could connect to a different LDAP system.
There are two minor limitations:
-
The sync schedule can only be set globally.
-
Usernames must be globally unique (no two customers may use the username 'bob', for instance).
Global configuration
| Configuring at the account level means configuring from within the Agent Desk using Superadmin credentials. |
To enable multitenancy support, most of the configurations from above should likely be made at the account level (and not globally in the server configuration file), with the following exceptions:
com.unblu.addons.server.synctool.SyncTool.multitenancySyncMode should be set to true to enable the multitenant sync
`(com.unblu.addons.server.synctool.SyncTool.multitenancySyncMode=true)`
com.unblu.addons.synctool.runAtCronExpressions must be set globally as it cannot be set on a per account level.
Any configurations from the Entity Source Configuration section can be set globally, with the exception of com.unblu.addons.synctool.ldap.baseDN. This configuration must be set at the account level and it indicates that this account indeed should be synced by LDAP. If an account does not have this property set, it is assumed that the account should not sync from any LDAP system but is configured entirely within the collaboration server.
Per-account configuration
To enable the LDAP sync at the account level the property com.unblu.addons.synctool.ldap.baseDN must be configured at the account level.
All the other settings from the Entity Source Configuration section may be configured globally or individually on a per account basis. For instance, if only one LDAP server is used to sync all accounts, it might make sense to configure the identity management system using LDAP hostname, port and other server-specific settings globally and to set the LDAP structure individually, per account.
Edit settings at the account level
-
Log into the Agent Desk as Superadmin.
-
Click on Manage Accounts below your account name.
-
In the Account list, click the impersonate button for the account you want to configure. The website will reload and you should now be logged in as a Superadmin of that account.
-
Select Settings, then Account. The Account window opens.
-
From the Account window menu select Settings then, in the filter search box, enter ldap and click the Advanced button. You now have all of the LDAP settings available for configuration.
-
When you are done with entering configuration settings, click Save.
The account should now be configured and will initiate an ldap sync the next time the sync process runs, according to the globally-configured schedule.
| You should monitor the server log for potential sync errors due to misconfiguration. |
Multitenancy syncing limitations
Multitenancy Syncing has two limitations compared to syncing a single account:
-
The sync schedule (defined in com.unblu.addons.synctool.runAtCronExpressions) must be configured globally and cannot be set on an individual account basis. All accounts are synced according to this schedule. Syncing is performed sequentially, i.e., one account is synced after another.
-
Usernames must be globally unique, i.e., no two accounts may use the same username. If the name is not unique the existing user will be preserved and syncing of the account containing the new user will fail (due to the username already existing).