Externally managed users and teams

Introduction

The Agent Desk and Account Configuration interface provide various means to add, modify, and remove users and teams from Unblu. If you are synchronizing user and/or team details with an external directory service or some other "source of truth," your account’s users and/or teams are considered externally managed entities.

This article describes how you can control which changes to externally managed entities are possible within Unblu. It doesn’t discuss how to configure Unblu to synchronize user data with a directory service. For more information, refer to article User synchronization tool.

Externally vs internally managed entities

Each user and each team has an attribute that specifies whether they’re managed internally (that is, within Unblu) or externally. In the Account Configuration interface, the attribute appears as a toggle at the top of the entity’s General tab if you are in override mode and as simple text otherwise.

The team Call center in the picture below is managed internally:

Figure 1. An internally managed team in the Account Configuration interface; note the toggle at the top of the General tab

If the team were managed externally, the toggle would look like in the following picture:

Figure 2. The toggle of an externally managed entity

In JSON—when used with the web API or the utransfer tool, for example—the corresponding attribute is called externallyManaged.

If the attribute is false, the entity is internally managed.
If the attribute is true, the entity is externally managed.

The JSON code below contains the attributes of the same team, Call center, as the picture above. The team is internally managed, so its attribute externallyManaged is false:

Listing 1. JSON representation of an internally managed entity. The attribute externallyManaged is false

{
  "$_type": "TeamResult",
  "hasMoreItems": false,
  "nextOffset": null,
  "items": [
    {
      "$_type": "Team",
      "id": "IqW1UbAOQhuI3qzGt8Eg8A",
      "creationTimestamp": 1607695711635,
      "modificationTimestamp": 1607695711635,
      "version": 1,
      "accountId": "wZvcAnbBSpOps9oteH-Oxw",
      "avatar": null,
      "name": "Call center",
      "parentId": "JZh4ADRnEeasYZ5xEoyudw",
      "description": "Team for 'Call center'",
      "externallyManaged": false,
      "configuration": null,
      "metadata": null
    }
  ]
}

If you don’t provide a value for externallyManaged, its value is set to false. The externallyManaged attribute is always true for entities created or updated via LDAP and for users with the WEBUSER role created with a JWT.

Configuration

Superadmins can specify whether entities can be managed internally with the following configuration properties:

If a property above is true, it’s possible to manage that entity (user or team, respectively) in Unblu. This affects user management both in the Account Configuration interface and via the Unblu web API.

In the Account Configuration interface, you can:
- Create new entities. The new entity’s attribute externallyManaged is automatically set to false.
- Update and delete existing entities whose attribute externallyManaged is false.
  
  Conversely, this means that you can’t update or delete entities whose externallyManaged attribute is true.
With the Unblu web API, you can:
- Create new entities. When you do so, the entity’s attribute externallyManaged may be true or false.
- Update and delete existing entities irrespective of the value of their externallyManaged attribute.

If a property above is false, it isn’t possible to manage that entity (user or team) in Unblu. This means that:

You can’t create new entities with the externallyManaged attribute set to false.
You can’t update or delete existing entities whose externallyManaged attribute is false.
Using the web API, you can create, update, and delete entities whose externallyManaged attribute is true.

Scope of external entity management

The configuration properties mentioned in the previous section don’t affect every aspect of user and team management:

It’s always possible to edit teams' and users' configuration and text properties.
The minimum role required to create, update, and delete entities remains the same as before.
Reading entities isn’t affected in any way.

Updating entities via the web API

You will not be able to update an entity’s configuration properties, text properties, or metadata if all of the following conditions are met:

The entity’s externallyManaged attribute is false.
It isn’t possible to manage the entity internally, that is, the relevant configuration property internal<ENTITY>ManagementEnabled is false.
The authorization of the web API call is carried out with a user who isn’t in override mode (described in the section below).

Overriding the external entity management configuration

There may be circumstances where you want the ability to make changes to entities in the Account Configuration interface even though the entities are externally managed. To this end, you can authorize specific roles to override external entity management. The configuration properties to do so are:

By default, all roles are allowed to override the external entity management settings. This is intended to ensure backwards compatibility.

The example below shows what this looks like in the Global Server Configuration interface:

Default setting to override the external team management configuration

Figure 3. The default setting to override the external team management setting

If a user’s highest role is listed in an entity’s override setting, that user is said to be in override mode. Users in override mode can:

Set the value of an entity’s externallyManaged attribute in the Account Configuration interface or Agent Desk.
Change the value of an entity’s externallyManaged attribute in an update.
Create new entities, and update or delete existing ones, even if the relevant configuration property that enables internal entity management—com.unblu.storage.management.internalTeamManagementEnabled and com.unblu.storage.management.internalUserManagementEnabled for teams and users, respectively—is false.

How overriding external entity management configuration works: an example

Normally, roles higher up in the role hierarchy can perform any actions that a role further down in the hierarchy can perform. The way overriding external entity management settings works runs counter to this general rule.

Consider the following configuration:

Listing 2. An example configuration where admins and supervisors can override the settings of externally managed teams

com.unblu.storage.management.internalTeamManagementEnabled=false
com.unblu.permission.roleAllowed.overrideTeamManagement=ADMIN,SUPERVISOR

With this configuration, admins and supervisors are in override mode:

Admins and supervisors are both able to update teams in the Account Configuration interface, regardless of the teams' externallyManaged attribute.

The changes they can make include changing the entity’s externallyManaged attribute.
Admins may create with externallyManaged set to false.

Since the supervisor role doesn’t have the authority to create new teams, it can’t do so in override mode, either.
Admins may also delete teams regardless of the teams' externallyManaged attribute.

For technical admins and superadmins, on the other hand, the restrictions of the configuration property com.unblu.storage.management.internalTeamManagementEnabled apply in full, even though their roles figure higher up in the Unblu role hierarchy.

Importing entities with `utransfer` and at server startup

Since utransfer uses the Unblu web API to transfer entities between Unblu accounts, the same restrictions apply to entities when using utransfer as when using the web API:

externallyManaged attributes may be set directly in the JSON transferred.
If no value is provided, the attribute is set to false.

You should consider using utransfer with a user in override mode to ensure that the update doesn’t fail.

If the JSON used for importing entities at startup contains definitions for teams and/or users, we recommend that you grant the SUPER_ADMIN role the possibility to override external entity management for the entities in questions.