Provisioning - role and queue configuration

Provided there already exists an attributes mapping for provisioning we can define a role for identity provisioning and configure a provisioning queue.

Provisioning for an identity can be executed only if a user has assigned a role which assigns accounts in the system and uses some of the system attribute mapping. To configure a role, go to the Role tab and choose the role that will assign the account in the system, e.g. the role "LDAP" or create a new one. Click on the role detail (magnifying glass next to the role name) and switch to the Systems tab.

This tab contains a list of provisioning mappings. The list is usually empty or contains one item. Roles usually don't assign multiple systems to avoid complexity, but it can be done. For adding new system's mapping click on the Add button.

Set up the following fields:

• Role – ReadOnly field containing the name of the processed role
• System – The name of the managed system that will be assigned by the role to make provisioning. E.g. "LDAP".
• Mapping – The provisioning mapping which was defined earlier for the system.

After the configuration is saved - Save button - new options section appears:

The next section "Attributes mapped within a role" can be used to override the selected mapping from the above. Overriding an attribute is used for setting a value which is different from the value in the system mapping. For example, if the role should assign a specific permission on the system, this specific permission can't be in any way set in the general attribute mapping for the system. E.g. this would be used for the attribute __MEMBER_OF__ of the MS Active Directory and roles that assign specific AD groups.

When a user has at least one role, which contains this configuration of attribute mapping for the provisioning, the user is automatically provisioned to the given system. The provisioning takes place after every change of some of the mapped attributes.

Propagation of data in CzechIdM is performed by the queue containing requests for the managed systems. When some attribute of an identity changes and the identity has account on some managed system, a new operation CREATE/UPDATE/DELETE is written to the provisioning queue as an active operation. The same principle holds for all objects that support provisioning:

• Identity
• Role
• Organization (TreeNode)
• Role catalogue

The audit of provisioning can be accessed in the following manner:

• Audit → Provisioning
• Systems → Detail (magnifying glass) → Provisioning – this way is actually only a shortcut to the previous location, the shortcut which automatically fills the filter "System" by the value of the selected system. Note that when you leave this form, switching to another tab in the menu, to return back later through the Audit → Provisioning, the filter stays filled with the original values of the system. As a result, you won't see the whole provisioning audit, only the filtered parts. To cancel the filter, click on the Filter button and then Cancel filter.

Either way you get to a form containing two tabs:

• Active operations – the tab displays the queue of pending requests for provisioning
• Archive – the tab displays already processed requests for provisioning

The logic behind the provisioning queue is as follows: If there is a waiting operation for an object, say the user "j.doe", then any other operation for this object is added to the queue. So we can have a queue containing a list of pending operations for the user "j.doe": CREATE, UPDATE, UPDATE, DELETE.

The most common reasons a provisioning operation does not run include these: unavailability of the system, wrong configuration of the system's connection, setting the system read-only. The operation will then result in an error and it will wait in the queue for further processing. We can repeat the action manually in CzechIdM - select this operation and choose the desired action from the select box Operation with selected record. There are two available actions:

• Retry operation
• Cancel operation

In both cases, we will be asked just before the actual processing, if we want to retry/cancel the full batch, or only the selected records.

If we choose retrying the full batch, all operations for this specific object in the queue (not only the selected operations!) are retried/cancelled in the same order as they are organized in the queue. E.g. when you select CREATE operation on the user "j.doe" and choose "Retry full batch", then all operations for the user "j.doe" will be retried in the respective order CREATE - UPDATE - UPDATE - DELETE.

If we choose the option Retry selected, the selected operations are retried/cancelled in the same order as they are organized in the queue. All the other not selected operations stay waiting in the queue. E.g. when you select CREATE and UPDATE for the user "j.doe" and choose "Retry selected", the CREATE and then the UPDATE operation will be retried and second UPDATE and DELETE will remain in the queue without any change.

Retrying selected operations requires knowledge about connecting the system. If an administrator chose some operations that don't make sense - e.g. choosing DELETE without choosing CREATE first - the processing would result in an error.

The long-running task (LRT) named RetryProvisioningTaskExecutor exists in CzechIdM for the sake of automatic retry of provisioning operations. This LRT executes the provisioning queue in defined intervals. If you want CzechIdM to periodically retry failed provisioning operations from the queue, enable and set this task.

If there is a planned unavailability of a managed system, we recommend that you turn off this task temporarily for performance reasons.

The detail of a provisioning operation can be accessed by clicking on the magnifying glass next to the record in the provisioning queue. There are the following fields:

• Created - the date of requesting the operation
• Operation - the type of operation (Create/Update/Delete)
• Entity type - e.g. Identity, TreeNode, …
• IdM entity - the name of the provisioned entity in CzechIdM
• System name - the system which is provisioned into
• Identifier in system - the name of the provisioned entity in the managed system
• Result - in the case of an error, there is additional information about the error, such as:
  • error code - e.g. PROVISIONING_ATTRIBUTE_VALUE_WRONG_TYPE
  • error description - e.g. "Provisioning - attribute value is not in correct type"
  • stacktrace - Java stacktrace of the exception, e.g. eu.bcvsolutions.idm.acc.exception.ProvisioningException: Schema attribute __ENABLE__ defines type java.lang.String. But value type is java.lang.Boolean!

This information can be used to determine the reason for the error. In the example above, the reason is evidently the wrong configuration of a provisioning schema; namely, it's necessary to set the attribute __ENABLE__ to acquire Boolean, or use a transformation script to transform Boolean to String.

The detail of the operation displays two tables:

• Attributes in IdM - the left table displays all attributes that are set in the system mapping for the given entity. E.g. the system "LDAP" maps the attributes name, firstname, lastname, titlebefore for the entity "Identity". The table contains these attributes and their corresponding values, e.g. j.doe, John, Doe, Dr.. We call this table as the wish, i.e. the desired values to send. The value of every attribute is final, meaning that if their mapping required a transformation or a computation, the transformation had been already applied.
  E.g. if the mapping contains the attribute Manager, its value could be "CN=John Doe, O = My Company", which doesn't need to be saved anywhere in IdM, because it is computed by the transformation script during provisioning.
• Attributes for provisioning – the right table displays selected attributes and their values, which are really propagated to the managed system. Not all attributes have to be sent to the system. Namely the attributes whose actual value on the system doesn't differ from the wish (the left table). The exception to this rule is, of course, the attributes that were marked required in the provisioning mapping.

The right-hand table may be empty, namely in these two cases:

• The provisioning queue already contains an older operation for the same entity. In such case, IdM doesn't compute the difference between the wished and the actual state of the system account for performance reasons. That would require unnecessary network communication. Also, the actual state of the system account may have been changed during the period of waiting of the operation in the queue. E.g. the administrator may have changed the value in the end system. The information in the queue could be misleading in such case.
• There is no difference between the attributes that would be sent (the wish) and the values in the managed system. This could happen only if no attribute in the provisioning mapping is marked as required.

A new feature is available that will come in handy in configuring provisioning. When a provisioning queue has many operations and even cancel operation (Operation with selected record) is not very efficient, there is now the Cancel all operations button. This button uses a provisioning queue filter and cancels the batches of all found operations. So even if an operation is not found with this filter, but another operation in the same batch is found, both of them are cancelled. Cancelled operations are moved to the archive. This feature is only accessible to a user with admin authorization.

The provisioning brake is a tool to monitor how many times the specific provisioning operation (create, update, delete) is done. It is also possible to set warning or disable limit for each operation, which is very useful for business critical systems. After the limit is exceeded (either warning or disable), a notification will be sent to all recipients for specific provisioning break configuration. After the disable limit is exceeded for the operation, the operation won't be executed any more, until administrators manually check the current situation.

It's also possible to configure a global provisioning brake, which will be applied to all systems without the need to configure the brake separately for every managed system.

In the following example, we want CzechIdM to monitor all Delete operations on the managed system. We don't expect that the accounts on the system would be deleted too often. On the contrary, we want to be notified whenever CzechIdM deletes more than 2 accounts in the period of 60 minutes, because the system is business critical. If CzechIdM deletes more than 5 accounts in one hour, it's probably some kind of error in HR system or in the configuration. In such case, we want CzechIdM to cancel all following delete operations and we will resolve the situation manually.

The provisioning brake for the specific system can be configured in Systems → Detail (magnifying glass) → Provisioning brake. To add a new configuration, click on the button Add.

Select the type of operation, which will be monitored by the provisioning brake. The possible values are Create, Update, or Delete. In our example, choose Delete. Then set the period for evaluating limits (in our example 60 minutes), the warning limit for the number of operations after which the warning notification is sent (in our example 2), and the disable limit - the maximum number of operations processed by CzechIdM in the configured period (in our example 5). Then click on the button Save and continue.

All possible settings of the provisioning brake:

Example configuration for delete operation:

The example configuration means: If the system processed more than 2 operations during last 60 minutes, the warning notification would be sent. If more than 5 delete operations are processed, the system would be immediately blocked for delete operations (so the 6th operation wouldn't be processed) and also the notification with information about disabling the system would be sent. Both this limits are evaluated for 60 minutes.

After saving the new configuration, add the recipients which will receive the notifications. It's not possible to add recipients before you create the provisioning brake configuration. Of course, it's possible to edit the recipients for an existing provisioning brake.

The recipient can be an identity or a role. If you choose a role as the recipient, the notification will be sent to all identities that have this role assigned.

The recipient is added from the Recipients table (button )

For both types (identity or role), the detail of recipient looks similar, see pictures:

Identity recipient detail:

Role recipient detail:

Data integrity is checked before you delete identity or role that is set as the provisioning brake recipient.

When the disable limit of the provisioning brake configuration is exceeded, the system is marked by one of these flags: Block create operation, Block update operation, Block delete operation. The flag can be also set manually in the system's configuration, the result is the same as when the provisioning brake takes effect: the corresponding operation (create, update or delete) is blocked.

If you want to enable the operation again, set the corresponding flag from true to false and save the system's configuration. This will also reset the provisioning brake counter (Number of processed operations) to 0.

On the contrary, if one of these flag is set to true, the provisioning brake counter isn't reset.

When one of the flags is set true, warning information about blocked operation is displayed on the system detail. Similar information is also displayed in the system table.

After blocking the operation, this operation is put into the provisioning queue with the result BLOCKED. All the following provisioning requests of the same operation type are also put into the queue, but with the result NOT EXECUTED; see the queue example:

After you unblock operation for the system, the operation counter is reset (see above), but operations in queue aren't retried automatically. You can decide for every provisioning request whether to retry or cancel it - see Manual retry of provisioning operations.

If you or some process tries to retry an operation on the blocked system, this operation's result is changed from NOT EXECUTED to BLOCKED, see the picture.

By application properties it's possible to set the global provisioning brake. Global provisioning brake can be defined for these types: create, update and delete. Two global provisioning brake configurations for one type are not allowed! Global provisioning brake has lower priority than provisioning brake configuration for specific systems. Global provisioning brake is also displayed in the provisioning brake agenda with the label Global configuration.

Every global provisioning brake has these attributes:

Note that the global configuration defines recipients as ID or code (there is used lookup service).

Example configuration of a global delete provisioning brake:

idm.sec.acc.provisioning.break.delete.warningLimit=2
idm.sec.acc.provisioning.break.delete.disableLimit=5
idm.sec.acc.provisioning.break.delete.period=20
idm.sec.acc.provisioning.break.delete.templateWarning=warningTemplateForProvisioningBreak
idm.sec.acc.provisioning.break.delete.templateDisable=disableTemplateForProvisioningBreak
idm.sec.acc.provisioning.break.delete.identityRecipients=admin,owner
idm.sec.acc.provisioning.break.delete.roleRecipients=exampleRole,systemAdministrators
idm.sec.acc.provisioning.break.delete.disabled=false