Provisioning identity provisioning

Provisioning is implemented for:

• IdmIdentityDto - identities
• IdmRoleDto - roles
• IdmRoleCatalogueDto - role catalogue items
• IdmTreeNodeDto - tree nodes (structures)

• When dto (e.g. identity, see above) is changed, then update (create, delete) event on this dto is fired.
• in acc module are event processors, which processes update event on supported dto types and calls provisioning for updated dto - see above ProvisioningService.doProvisioning(dto).
• ProvisioningService resolves concrete provisioning executor implementation (ProvisioningEntityExecutor<DTO>) for given dto and calls ProvisioningEntityExecutor<DTO>.doProvisioning ⇒ provisioning can be implemented different way for each supported dto type. Standard implementation is in AbstractProvisioningEntityExecutor - use this class, when provisioning for new dto type will be needed (contains some boring parts etc.).
• ProvisioningEntityExecutor<DTO> finds all dto's accounts and starts provisioning for them - fires ProvisioningEvent START with account as content. This is one place, when some module specific processor can extend provisioning functionality - see ProvisioningStartProcessor. As you can see - accounts has to be prepared before. Accounts are created by account management. Account contains identifier only in this step - account management executes transformation for identifiers and creates / prepares accounts with them.
• ProvisioningStartProcessor is default processor (order 0), which processes ProvisioningEvent START and calls ProvisioningEntityExecutor<DTO>.doInternalProvisioning(account, dto). In this step is SysSystemEntityDto found (by account identifier) or created (as "wish") for given account. SysSystemEntityDto is entity on the target system - we need to know real identifier on target system, which could be different with account identifier, etc.. Account attributes are evaluated for given account (create "wish" - what IdM want's to be provisioned to target system. Attributes transformation to the target system are called here). At last, provisioning operation (SysProvisioningOperationDto) is constructed with account attributes ("wish") and system entity (SysSystemEntityDto). Created provisioning operation is given to the provisioning executor (ProvisioningEntityExecutor), which operates above provisioning queue. He is responsible for assigning SysProvisioningBatch for given provisioning operation (read more bellow) and then he puts operation into the queue for processing ⇒ persists given SysProvisioningOperationDto with state CREATED. All provisioning operations are stored in the queue. Operations in the queue can be processed two ways:
  • synchronously - ProvisioningEntityExecutor fires UPDATE (CREATE, DELETE) event with SysProvisioningOperationDtocontent immediately, when provisioning operation is persisted. This is the default way. Then the queue is used as provisioning log, if everything is processed successfully. If some ProvisioningException occurs, then operation remains in the queue with state EXCEPTION and can be canceled or executed again (e.g. when target system was unavailable). Look out, make sure you handle all exceptions, which could be thrown in your custom provisioning processor and throw ProvisioningException descendants only (used @Transactional mechanism can handle ProvisioningException only and doesn't do rollback for them - this is needed to persist exception reason and operation state in the queue).
  • asynchronously - target system can be switched to use asynchronous provisioning, then ProvisioningEntityExecutor doesn't fire an event immediately. Long running task ProvisioningQueueTaskExecutor works above queue and fires event periodically for created operations placed in the queue. The same rule for ProvisioningException applies here.
• When UPDATE (CREATE, DELETE) event with SysProvisioningOperationDto content is fired ⇒ there is the place, where provisioning to target system really starts. Respectively - this is the place, when provisioning operation processing begins. All processors registered for SysProvisioningOperationDto content (see package eu.bcvsolutions.idm.acc.event.processor.provisioning) are executed in defined order (default):
  • -5000: DisabledSystemProcessor - checks disabled system before provisioning is called. If system is disabled, then operation remains in the queue as NOT_EXECUTED and event processing ends.
  • -1000: PrepareConnectorObjectProcessor - actually changed attributes (connector attributes) are evaluated by given account attributes ("wish") and their strategies. Target system is contacted - processor reads attributes on target system, creates diff (by attribute strategy etc.) and results are stored in provisioning operation context as connector attributes (actually changed attributes). This attributes can be found in provisioning operation detail - left side is the "wish" (IdM account attributes after transformations), right side is connector attributes (actually changed attributes).
  • -500: ReadonlySystemProcessor - checks readonly system before provisioning is called. If system is readonly, then operation remains in the queue as NOT_EXECUTED and event processing ends. This mode can be used for debugging, if target system is online and we need to know, which attributes will be really provisioned.
  • 0: ProvisioningCreateProcessor, ProvisioningUpdateProcessor, ProvisioningDeleteProcessor - execute provisioning to target system.
  • 5000: RemoveProcessedOperationProcessor - successfully processed (or canceled) provisioning operation is moved from the queue to the archive. Archive is used as log. Archive can be truncated, but last provisioning operation per system entity should be preserved - it's used as "last processed operation" for merging attribute values.

All provisioning operations are processed through provisioning queue. The individual provisioning operations (create, update, delete) are serialized, saved in the queue, and then processed. If provisioning operation is completed, then archive provisioning operation record is created ⇒ active provisioning operation is executed and is moved into archive.

Three entities was created to persist provisioning operations and their state:

• SysProvisioningOperation - active (unresolved) provisioning operations. Contains operation type, state and provisioning context with transformed attributes ("wish" from IdM account), which have to be provisioned and really provisioned attributes (connector attributes), read more below.
• SysProvisioningBatch - container for active provisioning operations for one system entity on one system. Aggregates active operations for single dto (e.g. identity, role), respectivelly for their system entity. When provisioning fails or is stopped (e.q. when system is switched to be read only, disabled, asynchronous), then all provisioning operations for single system entity are grouped in one batch. Operations can be executed in the same order, as they was inserted into queue ⇒ preserve system entity state on target system. Operations from queue are processed by their batch ⇒ respectively batches are processed from queue.
• SysProvisioningArchive - archived (processed) provisioning operations - logged operations. Last archived provisioning operation can be used for getting provisioned context with contains really provisioned attributes.

Supported provisioning operation states:

• CREATED - newly created, not processed operation
• EXECUTED - the operation was successfully executed
• EXCEPTION - there was an exception during execution
• NOT_EXECUTED - the operation was not executed because of some reason - operation for the same entity is already in the queue, readonly system etc.
• CANCELED - canceled by some reason (administrator etc.)

To extend or reconfigure the provisioning mechanism, the processing has been moved to the events on the dto SysProvisioningOperationDto and to the individual processors treating this dto (the list of the registered processors has been extracted to the application on the module page). Calling the provisioning then takes places through publishing the events with the SysProvisioningOperationDto content through ProvisioningExecutor. The individual operations are serialized, persisted in the queue, and transmitted to the processors. If a ProvisioningException occurs or some of the processors stops working, then it is possible to find what happened in the agenda placed above the queue (error code, return state etc.). The GuardedStrings (e.g. passwords) are not saved in the serialized state - the values are replaced and saved in a confidential storage from which they are only read when needed (account re-calculation, provisioning implementation).

The operation content in SysProvisioningOperationDto is called ProvisioningContext and is divided into two logical units:

• accountObject - counted account attributes according to the set-up mapping on the IdM page ⇒ wish.
• connectorObject - real attributes sent to provisioning counted after contacting the target system (reading of the existent object and changes comparison).

First the accountObject ("wish"), then the connectorObject which is the real provisioning input is calculated. When repeating the operation, a new connectorObject from an accountObject is always calculated so that the possible changes which could occur right on the target system are taken into consideration.

Once the object (defined by the identifier on the system and the idm entity) is in the queue, all the other requests for the provisioning of the same objects are persisted and remains in the queue - consistent sequence of operations on one object in the target system.

Provisioning queue functions:

• Start provisioning - provisioning is started by publishing START event on IdM account, then provisioning operation for this account is created and inserted into queue for processing.
• Disabled system - requests for provisioning stays in the queue with state NOT_EXECUTED. The target system is not contacted at all.
• Read only system - requests for provisioning are prepared, the actually changed attributes on the target system are counted, the request is persisted and stays in the queue as NOT_EXECUTED. The check and reading of the original existing object on the target system take place - this is how the real operation UPDATE vs. CREATE is specified, if the object exists / does not exist on the target system. An active operation for provisioning does not take place.
• Retry mechanism - the requests ending with an error are persisted in the queue and new running time is scheduled to them = another attempt will be executed by long running task RetryProvisioningTaskExecutor.
• Possibility of asynchronous processing - target system can be switched to use asynchronous provisioning.
• Break configuration

Provisioning operations ending with an error are persisted in the queue and new running time is scheduled to them = another attempt will be executed by long running task periodically - long running task RetryProvisioningTaskExecutor configuration is needed. Only failed operations are processed from queue by retry mechanism.

Target system can be switched to use asynchronous provisioning - flag on the system detail. Then requests for active provisioning operations (create, update, delete) are persisted in the queue as CREATED and their processing is delayed. Operations in queue are processed by long running task ProvisioningQueueTaskExecutor, which operates above the queue periodically and starts CREATED provisioning operation processing. Make sure you have ProvisioningQueueTaskExecutor configured, if you have some target system switched to use asynchronous provisioning.