Configure reconciliation
What is Reconciliation?
While synchronization is used to detect changes in the source system, Reconciliation is used to detect/monitor changes at the target system. These changes can be: creation, modification, or deletion of an account on the target system. Reconciliation compares the contents of the account index to what each Resource currently contains. For example, if Active Directory is one of the Managed Systems, then changes made directly on Active Directory can be detected and then synchronized back into OpenIAM and the systems that it manages based on the rules that are in place.
In addition, our Reconciliation feature is able to detect changes in the OpenIAM system and post them to the target system.
At a high level, the reconciliation engine is responsible for:
- Getting data from the connector and bringing it into OpenIAM
- This can be done either on an ad-hoc basis or it can be a regularly scheduled task.
- Mapping the incoming data from the source to objects in the OpenIAM system
- Passing the incoming data to the provisioning service to update downstream systems.
- Compare data in Open IAM with data from connector and make different actions according situations:
- Object exists in IDM and object exists in Target system.
- Object exists in IDM and object not exists in Target system.
- Object not exists in IDM and object exists in Target system.
- Object deleted in IDM and object exists in Target system.
The following sequence diagram shows our default logic of the reconciliation algorithm.
Complete and Incremental Reconciliation
Complete synchronization allows the user to take all the data in a source and synchronize it across target systems. The incremental synch only synchronizes records that have changed after the last record was processed.
Selecting Users to Reconcile
Reconciliation is fulfilled for all Managed Systems using the query filter that can find the necessary users for the Managed System. If no filter is specified, then all accounts are considered.
The system searches IDM/targetsystem users to reconcile with the help of IDM Search Query Script/Target System Search Query Script and its parameters. Then the system reconciles the found users to the target system/IDM according to the Situation List rules.
Situations
The OpenIAM Identity Manager is able to recognize a number of situations, which can occur during the reconciliation process:
- IDM (deleted) and Resource (exists)
- IDM (exists) and Resource (exists)
- IDM (exists) and Resource (not exists)
- IDM (not exists) and Resource (exists)
The response to the situations listed above can be one of the following:
- Do Nothing
- Add Record to IDM from Resource - Creates an IDM User from a target system entry. The mapping is provided by a Groovy script.
- Delete from Resource - Deletes the target system/IDM entry.
- Disable (or Change Status in Resource)
- Delete from IDM - Deletes the Identity of a user for the target system.
- Remove from IDM
- Add Record to Resource from IDM - Creates an entry in the target system with data provided by the IdM user. The same mapping as in provisioning is used.
- Update IDM from Resource
- Update Resource from IDM - Provides the ability to merge the data of the target system and the IdM using a Groovy script. All data of the IdM user, which is not overwritten by this script, will be transferred to the target system.
For example, you may not need to create user accounts in the target system if a new user has been added to OpenIAM. In this case, select "DO NOTHING" for the following case: IDM (exists) and Resource (not exists).
The listed types of events can also be linked to the notifications. For example, consider an Active Directory Admin making another account a Domain Admin. Reconciliation rules can be configured to allow this change and to add it back to OpenIAM. Alternatively, these changes can be reversed and a notification can be sent alerting the security team of a security breach.
Configure reconciliation
Before configuring reconciliation, be sure to confire the required Managed System.
In order to enable reconciliation between a target system and OpenIAM, you need to make configuration settings in OpenIAM. At high level, user needs to:
- Develop reconciliation Groovy scripts
- Define reconciliation rules in OpenIAM and refer them to the Groovy scripts
- Configure situations in OpenIAM
To configure resociliation, follow the instructions below.
- Step 1: Develop Groovy Scripts
You can find script examples and more details on Groovy Scripts for reconciliation here.
- Step 2: Configure Reconciliation
To configure the reconciliation rules, go to Provisioning → Managed System → Reconciliation → Add. User can add one or several reconciliation configurations for the following objects: Users, User Groups, User Roles, Organizations.
In the Reconciliation window, fill in the required fields. The fields description is in the following table.
| Field | Description | Example value |
|---|---|---|
| Type | A configuration can be one of the following types: User; Group; Role; Organization. When you select the "Group" type, then the reconciliation will synchronize the Group objects, etc. Configurations can belong to one type but have different filters. | User |
| Use Custom Reconciliation Logic? | If you check this box, then the following "Custorm Processor Script" field will appear. So, the custom reconciliation script will be used instead of standard core script. This custom script can realize a logic specific for your environment. | Checked |
| Custom Processor Script | Specify the path to the Groovy script that will realize a custom logic for reconciliation. If you leave the field empty, then the default behaviour will be used. | /recon/GroupProcessir.groovy |
| Status | Select either "Active" or "Inactive" to specify if the configuration should be applied. | Active |
| Frequency | Select the frequency to run Reconciliation automatically according to the selected frequency: Every 5/15/1 Hour/ Run Nightly. If no value is selected, then Reconciliation can be launched manually by sclicking on the "Save and Reconcile" button. | |
| Email address for notification of completion | Enter email address used for notifications. You can find some information about notifications above. | |
| Send report about "Do nothing" cases | Is the field is checked, the use will receive emails on all the "Do nothing" cases run in the system | Checked |
| Target System Search Query Script | Specify the path to the Groovy script to extract data from target system for reconciliation. At the output we obtain a search string (used in LDAP/AD). In this string, two variables are available for the parameterized search: searchFilter and updatedSince. These variables are taken from the reconciliation configuration (the Target System Search Query Filter and Updated Since field values.) | recon/PowershellADSearchQuery.groovy |
| Target System Search Query Filter | Enter the parameter that was set in "Target System Search Query Script" for custom search (see the searchFilter parameter above). This field is used for any target system. | (&(objectCategory=person)(objectClass=user)(SamAccountName=Kats.Tanaka)(&(!(employeeType= Contract))(!(title=Contractor)))) |
| IDM Search Query Script | Specify the path to the Groovy script to extract data from IDM OpenIAM system for reconciliation. So, the script will search IDM users, not the target system accounts. | recon/UserSearchScript.groovy |
| IDM Search Query Filter | Enter the parameter that was set in "IDM Search Query script" for custom search. This is a similar parameter to Target System Search Query Filter, but used for IDM, not for the target system. Typically this filter is in JSON format, but can be specified in any supported format (see the searchFilter parameter above, here in JSON format). | {"employeeId": "notexists"} |
| Updated Since | Enter the parameter that is used in both scripts to extract data for reconciliation by date period. The Updated Since parameter is used to set up the time of the last update in order to ignore old records. | |
| IDM Repository Field | Specify the field by that has to match User object (PRINCIPAL NAME, IDM USER ID, PRIMARY EMAIL ADDRESS, EMPLOYEE ID, CUSTOM ATTRIBUTE). | PRINCIPAL NAME |
| Source Attribute Name | Enter the attribute name in the Target system by which we match the User. | SamAccountName |
| IDM Custom Attribute Name | This filled value is empty (disabled) by default. Enable it only if the "IDM Repository Field" is selected as the "CUSTOM ATTRIBUTE". | |
| Custom Rule for Matching | Specify the path to the Groovy script for custom matching. This script is used if you need complex matching, not the simple "target system attribute" - "user property" matching (CSV 'EMPLOYEE_ID' to User.empoloyeeId.) The Custom Rule for Matching can be used, for example, if the form of saved data is different for users in the target system and in OpenIAM. | |
| Report | Report type HTML/CSV. See Reconciliation Report. | |
| Pre-/Post-processor Script | Specify a path to the scripts responsible for pre- and post processor behavior. | recon/PrePostExecutorSample.groovy |
Tip for one-way reconciliation
If you need a one-way reconciliation, for example, from the target system to IDM only, specify a filter to always return no results in the "IDM Search Query Filter" field. For example, by specifying {"employeeId": "notexists"} we are trying to find a user with employeeId that never exists. So, no users will be found and no users will be reconciled.
To receive users from the target system, specify a normal filter in the "Target System Search Query Filter" field.
So, the Reconciliation will go in one direction only, from the target system to OpenIAM.
The examples for field filling are given below:
For LDAP Managed System
For AD Powershell Managed System
- Step 3: Define Policy Map
Reconciliation use the Policy Map attributes to build a list of required attributes from the target system.
For example, if the value of userPrincipalName it to know, user needs to request it from the target system. This means user must have a Policy Map attribute for userPrincipalName set up.
Note that sometimes target systems don't allow reading specific attributes, e.g. Password. User can check another attributes on the target system if their values can be used to find out the required value if you can't read the necessary attribute directly.
It's important to write the name of required attribute correctly.
- Step 4: Configure Situations
The following table provides information on how to configure situations.
| Field | Description |
|---|---|
| Recon Situation | Situations describe what we should do if one of the situations happens. |
| Response | The action that the system must fulfill once the situation has happened. It can be "Do nothing", "Add Record to IDM from Resource", "Delete from Resource Disable (or change status in Resource)", "Delete from IDM", "Remove from IDM Disable (or change status in IDM)", "Add Record to Resource from IDM", "Update IDM from Resource" and "Update Resource from IDM". |
| Script | Enter a path to a groovy population script. The population script is used for creating a new user or editing the existing user's attributes received from the target system. So, the script defines rules how to fill ProvisionUser object from the Target systems attributes. User can provide separate scripts for different situations or have one script for all situations. |
| Custom Command | User can use customization scripts for Reconciliation Commands. If the field is empty, then the default commands will be used. Custom scripts add custom logic into Reconciliation commands. A custom script can be added for any reconciliation type: User, User Group, User Role, Organization. |
Record of Reconciliation Activities
Every reconciliation and synchronization activities logs information about it activities into Elasticsearch.
Activity history placed on: webconsole → Administration → Reconciliation history
You can create and download csv file with data for selected activity. (Press “Download” button).
Select “Info” button to redirect into activity page.
Press “Info” button for get information about object.
