Synchronization Configuration
Last modified 11 Jan 2023 15:14 +01:00
Since 3.0
This functionality is available since version 3.0.
Table of Contents

Resource Configuration contains a specialized section that defines the behaviour of synchronization mechanisms for the resource. This section specifies how midPoint reacts when a new synchronization event is detected, e.g. an event that account is created or deleted. The reaction may be to create a new user, delete or disable existing user, to ignore the even and so on. This is all defined in this configuration section.

The synchronization section is used only if there is an external or unexpected event related to the resource. E.g. this section will be used if reconciliation finds a new account, if live sync detects a delete delta for an account, if discovery finds an unexpected conflicting account and so on. I.e. this section defines a reaction to external events. This section will not be used for events that are initiated by midPoint itself (e.g. a role-based provisioning).

The Synchronization page provides a generic introduction to midPoint synchronization feature. This page describes how to configure a synchronization policy for a resource.

Synchronization Algorithm

When midPoint detects a synchronization event it follows the following algorithm:

  1. Applicable synchronization policy is determined. If no synchronization policy can be applied then the event will be ignored. The policy is determined by examining objectClass, kind, intent and evaluating a condition (if present) specified in a policy definition.

  2. Synchronization situation is determined.

  3. Appropriate reaction is found and executed.

Synchronization policy applies to all synchronization flavors by default. The idea is that midPoint will react to any change always in the same way regardless of how the change was detected. These mechanisms help keeping the policies simple and consistent. However, if an exception to this rule is needed, it can be configured e.g. by using a channel limitation (see below).

Object Synchronization Definition

The resource definition contains synchronization section which in turns contains several objectSynchronization sections. Each objectSynchronization section contains synchronization setting for a specific types of resource objects. MidPoint determines which definition to use based on kind, intent and object class of the resource object. Only one objectSynchronization section is used for each event.

The object synchronization policy has several parts:

  • name and description of the object synchronization section are used for debugging purposes

  • objectClass defines a resource object class for which this definition applies. Only objects of this object class will be processed by this definition.

  • kind and intent defines what kind and intent will be assigned to the object if it already does not have one. This is also used to determine the correct object synchronization policy, e.g. if more than one policy for a specific object class is used.

  • focusType defines a focal type that corresponds to this resource object. It is used together with correlation and confirmation expressions to determine situation and also influences the following reaction.

  • enabled flag specifies whether to use this policy or not. It can be used to temporarily turn off a specific part of a configuration.

  • condition is an expression which has to evaluate to true for the policy to be used. It can be used for a very fine-grain selection of applicable policies.

  • correlation and confirmation expressions are used to locate appropriate focal object and to determine object situation (see Correlation and Confirmation Expressions).

  • objectTemplateRef is a reference to a specific object template to be used in this case (e.g. when new user is created as a reaction to an event).

  • reconcile flag indicates whether an explicit reconciliation is requested as a reaction to this event.

  • opportunistic flag indicates whether midPoint should try to link and synchronize objects whenever possible (e.g. even during operations on other objects, see Consistency mechanism). This is on by default.

  • reaction section defines how midPoint should react to individual synchronization situations.

Situations

Main article: Synchronization Situations

When midPoint detects a synchronization event it is categorized into one of the situations. The situation describes how the change relates to the midPoint state regarding the changed resource object (account), user and the midPoint policies. MidPoint is using links and correlation and confirmation expressions to determine a situation. The Synchronization Situations page describes the details.

Channels

Main article: Channels

Channel defines a mechanism that was used to detect a change. When it comes to synchronization the channel is usually set to liveSync, reconciliation, discovery or import. The channel may be used in the reactions to alter the synchronization behaviour for some cases. E.g. a channel definition can be used to define a different behaviour during initial import and during a normal sustained operation. The Channels page provides more details about channels.

Reactions

Obviously midPoint has to react to a synchronization event to be really useful. MidPoint usually reacts to a synchronization event by executing the usual synchronization algorithms that are used to recompute consequences of any other change in the system (i.e. Clockwork and Projector). As usual midPoint does nothing by default and the execution of this algorithm has to explicitly enabled by using a synchronize flag in the reaction.

However synchronization cases are usually little bit more complex than normal provisioning changes. Synchronization often detects inconsistencies. E.g. a real-world situation that is different than what midPoint thinks that the situation should be. For example an account which was linked to a user has been deleted. MidPoint obviously should not blindly pretend that everything is all right. MidPoint should react. And the reaction may not be a simple "synchronize the attributes" algorithm. E.g. if this account was deleted we may want to leave it deleted and just unlink it, we may want to re-create the account, we may want to disable or even delete the user that was linked to that account or we may want to do a bunch of other things. Therefore midPoint allows to specify a set of actions to take place as part of the reaction. Although the actions are usually quite simple and straightforward they can be combined into a very comprehensive policies.

Reaction definition contains:

  • name and description are used for debugging purposes.

  • situation defines a situation to which the reaction applies. The reaction will be invoked only for events that end up in this situation.

  • channel can be used to limit reaction only to specific channels.

  • synchronize flag defines whether default midPoint synchronization algorithms should be applied to this event (see below).

  • reconcile flag indicates whether an explicit reconciliation is requested as a reaction to this event.

  • objectTemplateRef object template used in case the focus object is created or modified. If not specified the default is used (from resource or system-global).

  • action defines a set of actions that should take place.

Basically midPoint can react to an event in two ways:

  • Execute an action. Action execution is defined by action element in the reaction definition. This will cause execution of the code associated with the action.

  • Execute standard synchronization procedure. This is controlled by the synchronize flag. If this flag is set to true then the standard midPoint synchronization code will be executed. The code will execute all applicable inbound/outbound mappings, precess assignments, roles, object templates and so on.

Any combination of these can be used. A combination of both action and standard synchronization is used in almost all cases.

Actions

Actions are pieces of code that influence the standard midPoint synchronization mechanism. E.g. an action may cause the account to be linked to an existing user before executing the synchronization. The effect of such action may be the synchronization of account and user attributes by the means of inbound/outbound mappings. In an extreme case the actions can even replace the standard midPoint synchronization mechanism.

The action definition contains:

  • name and description are used for debugging purposes.

  • handlerUri is a reference to the action code (see below).

  • order defines whether actions should be executed before or after standard midPoint synchronization.

  • parameters section can be used to pass custom parameters to the action.

The action code is referenced using an URI. Although there is a comprehensive set of built-in actions already available in standard midPoint distribution we cannot predict all the possible actions that may be needed in real-world deployments. Using an URI to reference the code is a nice and extensible way to extend midPoint with custom actions (see below).

Built-In Actions

Standard midPoint distribution provides a set of built-in actions that are very frequently used in IDM deployment. The built-in reactions are all located in the midPoint namespace:

Reaction URL Prefix
http://midpoint.evolveum.com/xml/ns/public/model/action-3

The built-in actions are summarized in the following table:

Action name Description Typically used in situation URI

Link

Links resource object to a focus.
E.g. links account to a user.

unlinked

http://midpoint.evolveum.com/xml/ns/public/model/action-3#link

Unlink

Unlinks resource object from a focus.
E.g. unlinks account and user.

linked
deleted

http://midpoint.evolveum.com/xml/ns/public/model/action-3#unlink

Add focus

Adds a new focus object.
E.g. creates a new user based on account.

unmatched

http://midpoint.evolveum.com/xml/ns/public/model/action-3#addFocus

Delete focus

Deletes a focus object.
E.g. deletes an user that was linked to an account.

deleted

http://midpoint.evolveum.com/xml/ns/public/model/action-3#deleteFocus

Inactivate focus

Changes activation of the focus object.
E.g. disable user that was linked to an account.

deleted

http://midpoint.evolveum.com/xml/ns/public/model/action-3#inactivateFocus

Delete shadow

Deletes the resource object.
E.g. deletes an account that is not linked to a user.

unmatched
unlinked

http://midpoint.evolveum.com/xml/ns/public/model/action-3#deleteShadow

Inactivate shadow

Changes activation of the resource object.
E.g. disable an account for which there is no owner.

unmatched
unlinked

http://midpoint.evolveum.com/xml/ns/public/model/action-3#inactivateShadow

Note that the action only modify default synchronization behaviour. E.g. the inactivateFocus action is not the only way how to disable a user. The user may be disabled also by definitions in inbound mappings or object template. Using the normal (non-action) methods is also generally a preferred way because such definition is applied to all changes resulting in a consistent policy. The synchronization actions are only applied to externally-detected changes and therefore should be only applied to cases that cannot be handled by ordinary mappings.

Custom Actions

Custom actions can be created by extension and modification of midPoint code.

Implementation and customization note

MidPoint synchronization code actually prepares a Model Context that contains all the data from the synchronization event. It is the same context that is used by other midPoint mechanisms . When the context is created the individual actions have a chance to modify or inspect it. This context is also used by the synchronization algorithms (Clockwork and Projector) which are invoked as a reaction to the event. Therefore an action that modifies the context before synchronization can very simply influence the outcome of the synchronization. In fact most synchronization actions have no more than a few lines of code.

Examples

The following configuration snippet illustrates a configuration of an authoritative resource. A user will be created when a new resource account is detected, user will be deleted when the account is deleted and so on. For this to work well it needs to be supplemented with appropriate inbound mappings which is not shown in the example to keep it focused on the configuration of synchronization part. The configuration also includes a lot of optional elements such as kind, intent and focusType which are normally not really necessary as their default values are the same as those explicitly specified in this example.

Authoritative Resource
<resource>
 ...
    <synchronization>

        <objectSynchronization>
            <name>Account sync policy</name>
            <objectClass>ri:AccountObjectClass</objectClass>
            <kind>account</kind>
            <intent>default</intent>
            <focusType>c:UserType</focusType>
            <enabled>true</enabled>

            <correlation>
                <!-- Correlation expression matches account name (icfs:name) to a user "name" property -->
                <q:equal>
                    <q:path>c:name</q:path>
                    <valueExpression>
                        <path>$account/attributes/icfs:name</path>
                    </valueExpression>
                </q:equal>
            </correlation>
            <!-- No confirmation expression -->

            <reaction>
                <situation>linked</situation>
                <synchronize>true</synchronize>
            </reaction>
            <reaction>
                <situation>deleted</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#deleteFocus</handlerUri>
                </action>
            </reaction>
            <reaction>
                <situation>unlinked</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#link</handlerUri>
                </action>
            </reaction>
            <reaction>
                <situation>unmatched</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#addFocus</handlerUri>
                </action>
            </reaction>
        </objectSynchronization>

    </synchronization>
</resource>

Reaction Examples

Usual reaction for a linked situation is just to synchronize the changes from the resource to the user. The actual synchronization is done by standard midPoint synchronization code (Clockwork and Projector) which is in turn using inbound mappings to do so. Therefore the synchronization reaction simply needs to invoke standard midPoint synchronization code:

            <reaction>
                <situation>linked</situation>
                <synchronize>true</synchronize>
            </reaction>

No action is necessary in this case. Just enable synchronization. Please note that the standard synchronization code will not be invoked unless the this reaction is explicitly defined. MidPoint does not synchronize anything by default.

A migration phase is important part of IDM solution deployment. Accounts from various resources are linked to an existing user base in this phase. Correlation and Confirmation Expressions are often used in this phase. When correlation matches the result will be unlinked situation. A simple account linking is usually the desired action:

            <reaction>
                <situation>unlinked</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#link</handlerUri>
                </action>
            </reaction>

Note that standard midPoint synchronization run is still needed for the link to be created. No synchronization means no change. But even if the synchronization is executed it does not necessarily mean that the account attributes or the user property values will be synchronized. Whether the values are affected is determined by inbound mappings and outbound mappings. If the mappings are empty then only a simple link will be executed.

Typical authoritative resource will need to create new users when new account is detected. This is a reaction to unmatched situation. The addFocus action is used to force the creation of new user:

            <reaction>
                <situation>unmatched</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#addFocus</handlerUri>
                </action>
            </reaction>

The new empty user will be created and the account will be linked to it. Inbound mappings and object template can be used to populate the empty user. In fact one of these must be used e.g. to set correct name for the new user.

Non-authorative resource will typically react to unmatched situation in a very different way. Such resources will often delete or disable the account. This can easily be achieved using a deleteShadow action:

            <reaction>
                <situation>unmatched</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#deleteShadow</handlerUri>
                </action>
            </reaction>

Group Synchronization Example

MidPoint synchronization capability goes beyond simple user-account synchronization. MidPoint has a generic synchronization capability that can be used to synchronize almost any type of objects. The following example shows a configuration to synchronize groups (resource objects) and roles (midPoint objects). This setup will create a new midPoint role when a new group is detected on the resource.

Group Synchronization
<resource>
 ...
    <synchronization>
        ...
        <objectSynchronization>
            <name>Group sync policy</name>
            <objectClass>ri:GroupObjectClass</objectClass>
            <kind>entitlement</kind>
            <intent>group</intent>
            <focusType>c:RoleType</focusType>
            <enabled>true</enabled>
            <correlation>
                <q:equal>
                    <q:path>c:name</q:path>
                    <valueExpression>
                        <path>$shadow/attributes/icfs:name</path>
                    </valueExpression>
                </q:equal>
            </correlation>
            <reaction>
                <situation>linked</situation>
                <synchronize>true</synchronize>
            </reaction>
            <reaction>
                <situation>deleted</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#unlink</handlerUri>
                </action>
            </reaction>
            <reaction>
                <situation>unlinked</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#link</handlerUri>
                </action>
            </reaction>
            <reaction>
                <situation>unmatched</situation>
                <synchronize>true</synchronize>
                <action>
                    <handlerUri>http://midpoint.evolveum.com/xml/ns/public/model/action-3#addFocus</handlerUri>
                </action>
            </reaction>
        </objectSynchronization>

    </synchronization>
</resource>

Conditions

It is sometimes needed to synchronize objects that have the same object class but that have to be divided to several intents. The object class is the primary information that midPoint uses to decide what to do with an object and if the objects have the same object class midPoint would not be able to decide properly. Therefore a more advanced approach is needed in this case.

There may be several objectSynchronization sections for the same object class and they may contain a condition. MidPoint will try all the objectSynchronization sections that are defined for a specific object class and it will evaluate the conditions. The fist section for which the condition matches is used to process the object.

Following code provides a configuration example to determine account intent based on the first letter of the username. The account starting with "T" are considered to be testing accounts, accounts starting with any other letter are considered to be default accounts. Please note the specification of intent in the objectSynchronization sections.

objectSynchronization condition example
    <synchronization>
        <objectSynchronization>
            <objectClass>ri:AccountObjectClass</objectClass>
            <kind>account</kind>
            <intent>default</intent>
            <enabled>true</enabled>
            <condition>
                <script>
                    <code>!basic.getAttributeValue(shadow, 'http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3', 'name').startsWith("T")</code>
                </script>
            </condition>
            <!-- correlation and reactions for "default" accounts here -->
        </objectSynchronization>

        <objectSynchronization>
            <objectClass>ri:AccountObjectClass</objectClass>
            <kind>account</kind>
            <intent>test</intent>
            <enabled>true</enabled>
            <condition>
                <script>
                    <code>basic.getAttributeValue(shadow, 'http://midpoint.evolveum.com/xml/ns/public/connector/icf-1/resource-schema-3', 'name').startsWith("T")</code>
                </script>
            </condition>
            <!-- correlation and reactions for "test" accounts here -->
        </objectSynchronization>
    </synchronization>

Using Synchronization When Not Synchronizing Anything

The synchronization section may be required even if you are not explicitly synchronizing anything into midPoint. You may need it even if there is no live sync running and you have no inbound mappings. MidPoint is always consulting the <configuration> section when it finds a new resource object. And that can happen even if you do not have any explicit synchronization. E.g. it can happen during associationTargetSearch expression, it can even happen during ordinary listing of resource objects, it can happen when midPoint discovers new group that is already associated with an account, etc. If the resource behaves correctly and you do not plan to do anything special with these objects you do not need to specify synchronization section at all. But you might need to specify the sections if you need some special handling - especially if you need to sort out the objects to intents.

In that case a minimal synchronization section will do:

    <synchronization>
        <objectSynchronization>
            <name>sync group</name>
            <objectClass>ri:group</objectClass>
            <kind>entitlement</kind>
            <intent>group</intent>
            <enabled>true</enabled>
        </objectSynchronization>
    </synchronization>

This section will tell midPoint that when object of group object class is discovered it should be sorted out to entitlement kind and group intent. MidPoint has an algorithm how to sort objects to kinds and intents even if synchronization section is not present. But it is not entirely reliable. Therefore using synchronization section is recommended to make this unambiguous. This is required especially if there are several intents for the same object class. In that case several objectSynchronization sections with appropriate conditions are required.

There is objectType in schemaHandling. And there is objectSynchronization. These two sections describe essentially the same concept, but they describe slightly different aspects of this. This is a relic of early midPoint design (midPoint 1.x). In the future these sections will be probably merged into one. (MID-2831)

Notes

As usual the default midPoint action is "do nothing". Therefore midPoint will do nothing unless a synchronization reaction is explicitly set up. This default setting limits potential damage that midPoint might cause during system setup, experiments and tests.

MidPoint is transparently managing object shadows in the identity repository all the time. This mechanism is independent of synchronization policy, situations or reactions. This has to be done independently as the shadows are just a cache of the real state of the resource. Therefore a new shadow will be created automatically for each new account even if no policy or reaction is defined. The shadows will also automatically be deleted if a corresponding resource object is deleted even though no synchronization policy defines that explicitly. Shadows are managed automatically and you do not need to care about it explicitly. However it still applies that midPoint will not react to a change in a shadow in any other way than by updating the shadow in repository unless there is an explicit synchronization reaction set up.

The last situation of each resource object is recorded its corresponding shadow. Therefore it can be used for troubleshooting and reporting.

Import of objects from the resource is also considered to be a form of synchronization. Therefore it needs a valid synchronization policy to work correctly.

Standard midPoint synchronization code will reconcile the attributes if it has appropriate fresh data already available. If all the data are available then reconciliation itself is cheap and midPoint will do it. This provides much better overall consistency. Therefore the reconciliation will happen by default when a new account is created as all the data are already there. The reconcile flag is generally used only to explicitly force reconciliation if it does not happen automatically.

Standard midPoint synchronization code will also process assignments. Therefore even if the account is linked to the user by synchronization code it does not mean that it will not be deleted later by the standard synchronization code. This may easily happen if the account is not assigned (which is likely) and the projection policy is set to a strict setting. Adjust the projection policy (e.g. by using legalization option) to resolve the situation.

Compatibility note: The versions before 3.0 had a slightly different concept of reactions and the internal implementation was very different. However the setup is still backward compatible. Even old reaction URLs should work well. As the older versions did not have the synchronize flag the side effect is that the synchronize flag in a reaction defaults to true if at least one action was specified.

See Also

Was this page helpful?
YES NO
Thanks for your feedback