Configuring synchronization

To enable automated provisioning or import users from another system, the Synchronization functionality in OpenIAM is essential. Synchronization serves two primary purposes:

• Importing data from a source into OpenIAM.
• Importing data from a source, bringing it into OpenIAM, and applying rules for downstream provisioning and deprovisioning.

At a high level, the synchronization engine is responsible for:

• Retrieving data from a connector or CSV file and importing it into OpenIAM.
  • This can occur either on an ad-hoc basis or as a scheduled task.
• Mapping incoming data from the source to OpenIAM objects.
• Passing the data to the provisioning service to update downstream systems.

Configuring synchronization

To configure synchronization, follow these steps:

1. Go to webconsole > Provisioning > *Synchronization.
2. Several examples are provided to help you get started. If you are new to OpenIAM, we recommend leveraging these examples rather than creating a configuration from scratch. The following steps describe how to create a new configuration.
3. Click Create Synchronization. You will see the screen below. Complete the form as described in the table.

Developing synchronization scripts

The synchronization framework supports custom Groovy scripts at multiple points, providing flexibility to meet specific business needs. Refer to this document to learn how to develop your own synchronization scripts.

Synchronization troubleshooting

The table below describes common synchronization error messages found in the OpenIAM audit logs to help with troubleshooting.

Synchronizing objects with non-unique names

There may be cases where you need to synchronize objects that have the same name, but belong to different managed systems. A common example of this scenario is synchronizing groups that share identical names.

If synchronization is configured to match solely by name, the system will not be able to distinguish between the two groups and synchronization will fail. This is because, as of now, the synchronization engine does not support matching based on multiple fields directly.

To address this, you should use linked attributes, such as a combination of name and managed system, where the managed system acts as a unique identifier.

Starting from OpenIAM version 4.2.1.14, a custom matching script is provided to solve this issue: /sync/group/GroupCustomMatchObjectRule.groovy.

This script includes detailed comments explaining how it works. Specifically, it enables you to match group objects by their name in combination with their associated managed system, ensuring uniqueness.

To use this script select it from the list of available Transformation scripts while configuring synchronization. The code for it is given below.

// Import necessary libraries and classes
import org.apache.commons.collections.CollectionUtils
import org.openiam.base.request.BaseSearchServiceRequest
import org.openiam.base.response.list.GroupListResponse
import org.openiam.common.beans.mq.RabbitMQSender
import org.openiam.idm.searchbeans.multivalue.SynchronizationRequestSearchBean
import org.openiam.idm.srvc.grp.dto.Group
import org.openiam.idm.srvc.recon.dto.MatchConfig
import org.openiam.idm.srvc.synch.dto.LineObject
import org.openiam.match.MatchObjectRule
import org.openiam.model.GroupPair
import org.openiam.mq.constants.api.OpenIAMAPI
import org.openiam.mq.constants.api.SynchronizationObjectProcessingAPI
import org.openiam.mq.constants.queue.synchronization.SynchronizationBulkGetQueue
import org.springframework.context.ApplicationContext

/**
* Script to match a group by a combination of name + managedSysId.
*/
class GroupCustomMatchObjectRule implements MatchObjectRule {
    ApplicationContext context  // Spring application context to fetch beans

    @Override
    List lookup(final MatchConfig matchConfig, final List list) {
        // Retrieve required beans from the application context
        final SynchronizationBulkGetQueue syncBulkGetQueue = context.getBean(SynchronizationBulkGetQueue.class)
        final RabbitMQSender rabbitMQSender = context.getBean(RabbitMQSender.class)

        // Cast input list to LineObject list
        final List<LineObject> lineObjectList = list
        println "Found ${lineObjectList.size()} objects in target"

        final List<GroupPair> pairList = new ArrayList<>()  // Resulting matched pairs
        final List<Group> iamGroups = new ArrayList<>()     // IAM groups fetched from OpenIAM

        // Process only if target list is not empty
        if (CollectionUtils.isNotEmpty(lineObjectList)) {
            final Set<String> names = new HashSet<>()

            // Extract group names from the incoming line objects based on the match source field
            for (final LineObject lineObject : lineObjectList) {
                names.add(lineObject.columnMap.get(matchConfig.matchSrcFieldName).getValue())
            }
            println("Collected ${names.size()} names from target ")

            // Fetch matching groups from OpenIAM
            if (CollectionUtils.isNotEmpty(names)) {
                for (int i = 0; i < names.size(); i = i + 100) {
                    // Prepare search bean with collected names
                    SynchronizationRequestSearchBean synchronizationRequestSearchBean = new SynchronizationRequestSearchBean()
                    synchronizationRequestSearchBean.setNames(names)

                    // Wrap the bean in a base search request
                    BaseSearchServiceRequest searchRequest = new BaseSearchServiceRequest<>(synchronizationRequestSearchBean)
                    searchRequest.setFrom(0)
                    searchRequest.setSize(names.size())

                    // Call OpenIAM service via MQ
                    GroupListResponse groupListResponse = rabbitMQSender.sendAndReceive(syncBulkGetQueue,
                            (OpenIAMAPI) SynchronizationObjectProcessingAPI.FIND_GROUPS, searchRequest, GroupListResponse.class)

                    // Filter by managed system ID
                    if (groupListResponse != null && CollectionUtils.isNotEmpty(groupListResponse.getList())) {
                        println("Found groups ${groupListResponse.getList().size()} in OpenIAM ")
                        iamGroups.addAll(groupListResponse.getList().findAll { it.getManagedSysId() == matchConfig.getManagedSysId() })
                    }

                    println("After filter by managed system rested ${iamGroups.size()} groups in OpenIAM ")
                }

                // Match each target LineObject with IAM groups by name
                for (LineObject lineObject : lineObjectList) {
                    String targetGroupName = lineObject.columnMap.get(matchConfig.getMatchSrcFieldName()).getValue()
                    println("try to match ${targetGroupName}")

                    // Perform case-insensitive name match
                    Group group = iamGroups.find({ Group it ->
                        it.getName().equalsIgnoreCase(targetGroupName)
                    })

                    // If a match is found, pair them; otherwise, use empty Group object
                    if (group) {
                        println("Group was found in IAM")
                        pairList.add(new GroupPair(lineObject, group))
                    } else {
                        println("Group was NOT found in IAM")
                        pairList.add(new GroupPair(lineObject, new Group()))
                    }
                }
            } else {
                println "No names were collected from result."
            }
        }

        // Return final list of matched (or unmatched) group pairs
        return pairList
    }

    @Override
    List getMatchRegex() {
        return null
    }

    @Override
    SynchronizationObjectProcessingAPI getApi() {
        return SynchronizationObjectProcessingAPI.FIND_GROUPS
    }




    @Override
    Class getDataResponseClassName() {
        return GroupListResponse.class
    }
}
 

This approach allows accurate synchronization of objects with non-unique names across different managed systems.