Table of Contents

Connector configuration and attribute mapping

Connector configuration

Creation of a newly connected system will be demonstrated on a database connector (ConnIdDBBundle). Firstly, we will create a new system named Table and choose the database connector. All settings for this connector are available in the Configuration tab. In the picture below is an example of the configuration:

The configuration below is only an example.The system in its default state doesn't contain the mapped table "system-users"

Connector pool configuration

The connector pool is a very useful feature that avoids unnecessarily creating a new connector instance each time a connector is called. Typically, each connector instance also creates a connection to that target system. It is effective to maintain these connections for longer periods and for multiple calls.

Another advantageous pool, besides maintaining a link to the target system, is avoiding the need to re-create / initialize the connector. For example, a JDBC scripted connector compiles all Groovy scripts from the connector configuration during a connector instance initialization. Only this operation can take seconds. Using the pool will allow you to create and maintain only one instance of the connector, ie. the compilation will be performed only once.

The last advantage is the ability to use multiple connections to one target system, which is especially advantageous during parallel processing.

Pool configurations:

By default is pool disabled!
Pool configuration is persisted in EAV attributes and use form definition with code "pooling-connector-configuration".

System scheme

When the connector is configured correctly, we can move on to the System scheme tab. There, we will create the scheme either manually or we will use the scheme which will be returned by the connector itself (according to the filled-in configuration).

The scheme will be automatically created by pressing Generate scheme.

After a successful generation, there should be a new entry (object class) __ACCOUNT__ in the object types table. This entry will contain available attributes in the system (for object ACCOUNT). In our case, it will contain an attribute for each column in the mapped table and the semantic attributes:

Attribute mapping

When the system scheme is created, we can move on to attribute mapping in the Attribute mapping tab. Mapping serves two basic purposes:

  1. Making the scheme attributes accessible in the IdM system. Only mapped attributes can be used in IdM for active operations (provisioning/synchronization). Mapping is always tied to the operation type and entity type (identity, group).
  2. It defines which value will the attribute be mapped into in the IdM system. (identity, group, extended attribute, hidden attribute).

Firstly, we will create a group (operation type and entity type) which we would like to map. We will select Provisioning and Identity. Then we will start creating the individual mappings. It is very important to create a mapping for the account identifier in the system and connect it correctly to the IdM identity. This is done by adding a new attribute.

In the attribute mapping details we will fill in:

Create mapping for the other attributes in the same way. Below you can find a table with the resulting mapping:

Attribute cache

For optimalization, the attribut can be cached. New mapping attribute is marked as 'cached' by default.

At this point, caching is only used in sync. This cache is cleared on start and end every sync.
If the attribute generates a value independent of the input parameters (random identifier, …), it is necessary to disable caching on such an attribute.

Send additional attributes with password

It's possible to send additional attributes to provisioning, when password is changed (e.g. password expiration in extended attribute). New flag sendOnPasswordChange was added to system attribute mapping - attribute with this flag checked will be send together with changed password to provisioning. Two ways for provisioning additional attributes are implemented:

  1. send additional attributes together with new password in one provisioning operation
  2. send additional attributes after password is changed in another provisioning operation

Two ways are be configurable by application configuration idm.sec.acc.provisioning.sendPasswordAttributesTogether:

Configuration is effective for all target systems. All target system will be using one configured way (configuration per-system is not implemented, coming soon).

Linking a role

In the previous paragraphs, we created a system which contains a scheme and mapped attributes for an identity and provisioning. In order to create an account for a specific user in the end system, we have to create a role which will be assigning this system and, at the same time, we have to assign this role to the user.

Linking a role - attribute overload

In the previous chapter we explained how to assign a role tied to a system. By doing this, we created an account which corresponds precisely to the mapping in the system. That was a default mapping. However, if want to create a role which will affect only a specific attribute, we will need to adjust the behavior (mapping) of the attribute, i.e. we will need to overload the attribute mapping.

We need to create a role where, after it has been assigned, the linked accounts will contain first name + the "overloaded attribute" invariable in the firstname attribute.

Mapped attribute strategy

The attribute strategy defines how will the attribute and primarily its value be dealt with during provisioning and synchronization.

The strategies are as follows:

SET (set as IdM calculates)

The default strategy which sends the acquired value to the end system as IdM calculates it. If the value is the same on the end system, the attribute isn't sent.

This strategy is applied both to account editing and its creation.

WRITE-IF-NULL (Set only if the value on the system is null)

The attribute value which is calculated by IdM is sent to the end system only if the end system value is calculated as equal to null. Before the final comparison whether the value is non-existent, transformation from the system is applied to the attribute value from the end system. The transformation is defined in the mapping of the attribute.

This strategy is applied both to account editing and its creation.

This strategy is also implemented in the case of synchronization. The function is similar to that of provisioning. The opposite is only the source and destination. In the case of synchronization, it is the source account on the end system and the goal is synchronized entity. Before comparing, a transformation to the system is applied.
The WRITE-IF-NULL strategy has a lower priority than SET, MERGE and AUTHORITATIVE_MERGE. Therefore, if we define one attribute with the SET strategy and another with the WRITE-IF-NULL strategy in the default mapping on the system, then the value of the WRITE-IF-NULL attribute will never be used. In this case, it will be necessary to define only the attribute with the WRITE-IF-NULL strategy in the default mapping. The other attribute with the SET strategy will have to be defined in the role as an overload of the default attribute.

CREATE (Set only when creating)

The attribute value which is calculated by IdM is sent to the end system only when creating a new account on the end system.

This strategy is also implemented in the case of synchronization. The function is similar to that of provisioning. The opposite is only the source and destination. The value of the attribute from the system is set to the entity only when it is creating.

The CREATE strategy has a lower priority than WRITE-IF-NULL, SET, MERGE and AUTHORITATIVE-MERGE.

AUTHORITATIVE_MERGE (Authoritative merge)

This strategy (identically to MERGE) alters the logic of calculating attributes and their values. With the other strategies applies the following: if there are more occurrences of the same strategy for the same attribute (more overloaded attributes in more roles), the one with the highest priority is found (according to role priorities or their names). The resulting value going into provisioning is calculated on the basis of this one attribute only.

Both the MERGE and AUTHORITATIVE_MERGE strategies, can be linked only to a multi-value scheme attribute!

The MERGE strategies are different, however. If there are more attributes overloading the same default attribute, all the values are merged into one. This resulting value (list) is sent to the IdM system as a "wish" of how the value should look like on the end system.

A situation where there are two overloaded attributes for the same default attribute, one having the AUTHORITATIVE_MERGE strategy and the other the SET or MERGE strategy, will not be valid. Such a situation is collisional and will result in an exception during provisioning!

With authoritative merge, the original values of the attribute on the end system are not taken into account (i.e. if some other system or administrator had put a different value to the attribute, it would be ignored by IdM).

Therefore, in a situation where the resulting value of the merged attribute from IdM is [A,B] and the value of the same attribute on the end system is [C,D], then the end system attribute will gain the value of [A,B] after provisioning.

MERGE (Merge)

Since version 9.3.0 was provisioning merge completely reimplemented!

This strategy follows the same pattern as authoritative merge up until the phase of creating a "wish" for IdM.

A procedure different from authoritative merge occurs at the moment of provisioning. The goal is to ensure that the attribute on the end system can be shared by more systems (it means IdM is not authority for all values in the attribute).

A situation where there are two overloaded attributes for the same default attribute, one having the MERGE strategy and the other the SET or AUTHORITATIVE_MERGE strategy, will not be valid. Such a situation is collisional and will result in an exception during provisioning!

Another goal is to ensure the correct removing of the managed values.

For identify what values are controlled by the IdM, we get it based on the settings of the roles mapping the system and overloaded this attribute (this 'calculation of the definition' approach is used since version 9.3.0. The previous approach, where the values ​​from the provisioning archive were used no longer used).

The controlled values ​​are currently valid values ​​(based on roles values) and values valid in the past.

The controlled values ​​are currently valid values ​​(based on roles values) and values valid in the past. Such a "historical" value arises at the time of the definition of role change, typically in the following cases:

Because the calculation of which values are currently controlled could be time expensive operation, are that values cached in entity SysAttributeControlledValue which is mapped on system mapping attribute. That persisted 'cache' is evicted when definiton for that attribut is changed on the role (SysRoleSystemAttribute).

The evicted cache is recalculated by using the AttributeControlledValuesRecalculationTaskExecutor task. This task recalculates the cache for all evicted attributes of the provisioning mapping.

Since version 9.7.5 is recalculation of evicted attribute not starts on save a attribute (SysRoleSystemAttribute)! Attribute on the system is marked as evicted only. Recalculation will be processed during first using of controlled values. This is typically on first update provisioning. Beware if new account is created and create provisioning is executed, then recalculation is not executed, because in this situation are controlled values not needed!
The merge attribute value must be a constant. For performance reasons, all system merge values are cached and this cache is recalculated only if the corresponding role attribute changes! If the value is dynamic, the cache will not contain the correct data!

Cache recalculation with this task can be started manually. At this startup, you must specify the system identifier and entity type (the 'IDENTITY' is filled in as default). It is also possible to deselect onlyEvicted. In this case, all attributes for that mapping will be recalculated even if their cache is not marked as evicted. Second situation when is cache recalculated is during provisioning. If the attribute is still marked as evicted.

Therefore, in a situation where the resulting value of the merged attribute from IdM is [A,B] and the value of the same attribute on the end system is [C,D], then the end system attribute will gain the value of [A,B,C,D] after provisioning.

Let us continue with the previous case, where the value [A,B,C,D] is on the end system. If we remove the role which was defining value B in IdM, then the value on the end system must be [A,C,D] after provisioning. We will then remove only the value which we are managing.

In our case we have the following information at our disposal:

By comparing these values, we can deduce that we have to remove value B, so that the result is value [A,C,D].

An advantage of this approach is the ability of detecting dynamic changes as well. This means that if we don't remove the role which assigned value B, but instead we change the calculation definition of this value, so that the result is X, then it follows from the above mentioned that we are able to correctly identify that we want to send value [A,X,C,D] to the end system.

A simple way of how to verify which attributes (values) were "wishes" in IdM and which were actually sent to the end system can be seen in the provisioning archive (Audit / Provisioning / Archive)
Final values merge from roles is set, all duplicates will be removed. For example: if you have two roles with merge mapping for same attribute and value for this attribute is same, to end system will be send only one.

Skip merged value if contract is excluded

Additional characteristics of strategies

Aside from a strategy, every attribute can also have the indications Always send and Send only if IdM value exists. These indications can be combined with all strategies.