Keeping in Sync - LDAP Reconciliation
By Sarah Bowen-Oracle on Sep 03, 2013
This article is intended for Fusion Apps customers either starting out on their implementation or who are facing Lightweight Directory Access Protocol (LDAP) reconciliation issues. The content of this article relates to Release 5 (11.1.5) and later versions of Fusion Apps.
Although focusing on the subject of LDAP (Oracle Internet Directory) Store reconciliation with Oracle Identity Manager (OIM), this entry does also touch on other LDAP reconciliation processes. For wider reading on the topic of Identity Management in Fusion Apps, please refer to Fusion 11g Release 7 (188.8.131.52.0) TOI: IDM in Oracle Cloud and Fusion Applications (Fusion Learning Centre>Release 7> Technology Management>All Products) , or for user creation/employee data flows, refer to this broader article.
Oracle Fusion Applications rely on Oracle Identity Management Products to manage Users, Roles and Permissions. Application users are created by using the Hire Employee task within the Fusion HCM Core application. The Hire Employee task creates User(s) and Role(s) entries in the underlying identity store through Oracle Identity Manager (OIM). It may be Active Directory (AD) or Oracle's Internet Directory (OID) or any combination of those.
Although the users can be managed inside the Fusion HCM application, it is worthwhile to understand the process of synchronizing between HCM, LDAP store and Oracle User and Role entries within OIM to support environment setup & validation.
User creation in Fusion Apps is a business process that spans across both Core HCM and OIM. The creation of users happens slightly differently depending on whether the person is uploaded via File Based Loader (FBL) or manually entered in the UI.
- For Persons loaded via FBL, the username and the status will both show as pending until the ‘Send Pending LDAP Requests’ process is run -- regardless of the hire date. Only those requests of current date or earlier will be picked up. This ‘Send Pending LDAP requests’ will result in new users being created in OIM.
- For Persons created via the Fusion HCM ‘Manage Users’ UI, if you do not have the ‘Send Pending LDAP Requests’ scheduled then you can use the ‘Copy Data to LDAP’ button. You can only create users where the hire date is the current date, not users with future hire dates.
- The ‘Copy Data to LDAP’ button on the UI will not work for users that are in a pending status. It only works for users that have been created.
- If you are creating users manually using the Fusion HCM "Manage Users" screen, and running into issues, you may find this MyOracle Support troubleshooting article useful (Doc ID 1459830.1).
- Running the above LDAP requests processing results in creation of user records in OIM and, depending on whether a OIM resource is configured with an SMTP server, email notifications are automatically sent (with user name and password) to the user if a valid work email address exists.
- This process can be done only once so care should be taken not to run the process while the SMTP server is not configured - this would result in the inability to generate email notifications for new user creation. At the same time if the process is run too early and the organization is not ready to start using the system, emails will be generated to users with their credentials and could result in premature use of the system. For further information on enabling email notifications, please review the MyOracle Support article on HCM Cloud Service Definition: E-Mail Notifications (Doc ID: 1534683.1).
- A copy of the email notification is also sent to the user’s manager. To prevent password notifications being sent to the users "manager", follow the instructions in this MyOracle Support article (Doc ID: 1487978.1).
- From Release 5, it is possible to suppress user account creation and email notifications if so desired. Likewise, it is possible to suppress the assignment and removal of roles for all users.
Are there other LDAP Synchronization jobs to consider?
In fact the area of LDAP synchronization can be broken down into two areas:
- Between Fusion HCM and OIM
- Between OIM and the LDAP
Let us first take the flows between Fusion HCM and OIM:
- ‘Retrieve Latest LDAP Changes’ - Copies users and roles from LDAP to HCM User Management. The process requests from OIM any changes that may not have arrived because of a failure or error.
The section ‘‘Define Synchronization of Users and Roles from LDAP’ of the Oracle® Fusion Applications Common Implementation Guide explains that OIM maintains LDAP user accounts for users of Oracle Fusion Applications. Amongst other things, OIM also stores the definitions of abstract, job, and data roles and holds information about roles provisioned to users.
During an implementation, any existing information about users, roles, and roles provisioned to users must be copied from the LDAP directory to the Oracle Fusion Applications tables. Once the Oracle Fusion Applications tables are initialized with this information, it is maintained automatically.
To perform the initialization, the installation Fusion Apps super user should run the process ‘Retrieve Latest LDAP Changes’ (this is available via the ‘Run User and Roles Synchronization Process task, once an offering has been configured and a set up task list has been created). Once the ‘Retrieve Latest LDAP Changes’ process has been run, users can then be provisioned with roles through HCM. The process name appears as SyncRolesJob which was the process name for ‘Retrieve latest LDAP Changes’ in Fusion Apps 11.1.2 (and earlier versions).
- ‘Send Pending LDAP Requests’ – This process sends bulk requests and future-dated requests that are now active to OIM to create, suspend, and re-enable user accounts, as appropriate. It also identifies future-dated transactions and manages role provisioning and de-provisioning at the appropriate time.
For further details on how these two programs work, and when to schedule them, please see http://docs.oracle.com/cloud/farel8/common/OCHUS/F1210304AN1EB1F.htm.
Secondly, let’s look at the reconciliation processes between OIM and LDAP. These jobs can be broken down into
a) full reconciliation processes:
- LDAP User Create and Update Full Reconciliation
- LDAP User Delete Full Reconciliation (Note: do NOT enable this job)
- LDAP Role Create and Update Full Reconciliation
- LDAP Role Hierarchy Full Reconciliation
- LDAP Role Membership Full Reconciliation
- LDAP Role Delete Full Reconciliation (Note: do NOT enable this job)
b) and incremental reconciliation processes:
- LDAP User Create and Update Reconciliation
- LDAP User Delete Reconciliation
- LDAP Role Create and Update Reconciliation
- LDAP Role Hierarchy Reconciliation
- LDAP Role Membership Reconciliation
- LDAP Role Delete Reconciliation
- Fusion Applications Role Category Seeding
The incremental LDAP jobs are not enabled by default, as some prerequisite steps are needed to point these to OID. Note that the actual configuration of integration between Oracle Identity Manager and LDAP is performed while installing Oracle Identity Manager. For further information on how to configure the integration of OIM with LDAP please refer to Configuring the Integration with LDAP in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager.
MyOracle Support Doc ID 1377101.1 describes how to identify which jobs are currently enabled or disabled in your environment. It also reminds the reader that as part of the installation and configuration of OIM, the LDAP jobs should be run in a particular order.
The full reconciliation jobs, as opposed to the incremental jobs, put a significant load on the OIM CPU (about 40% CPU usage). Hence it is advisable to run these when the system is not being so actively used. Please reference to MyOracle Support Troubleshooting: OIM Out of Sync with LDAP (Doc ID 1467067.1) for guidance and further troubleshooting .
To view all OIM/LDAP reconciliation jobs directly in your system, login to OIM as follows:
- Login to OIM console (as the OIM Superuser 'xelsysadmin')
- Go to Advanced console
- Click Search Scheduled Jobs, use wild card search LDAP*
- To submit a job, simply click on, for example, LDAP Role Membership Full Reconciliation job
- Click Run Now
(If the Run Now button is greyed out, then click Disable first to disable scheduling and then you can click Run Now. Also remember to turn scheduling back on by clicking Enable after the job finishes).
What do these LDAP Synchronization jobs do exactly?
In general terms, these jobs ensure that HCM/OIM, and OIM and LDAP are in sync with each other. Without being synchronized, users may not be able to log into Fusion Applications because they are not in the identity store, so credentials cannot be verified. Data roles will not be visible in OIM after generating from the data role template until LDAP reconciliation has taken place.
The system roll-back feature ensures that if OIM cannot make changes correctly, then LDAP will roll back to reflect the same position as OIM. For further details please refer to Provisioning Data From Oracle Identity Manager to LDAP Identity Store.
The "LDAP Scheduled Tasks” link in the Oracle Fusion Middleware Administrator’s Guide for OIM, provides specific descriptions of each LDAP/OIM Reconciliation job. For example, the LDAP User Create and Update Reconciliation job reconciles user updates based on the change log from LDAP. The incremental reconciliation jobs make updates based on change logs. Compare these to the full reconciliation jobs, such as LDAP User Create and Update Full Reconciliation job, that reference all users under the search base (defined in the Directory Server IT resource) to do the reconciliation with the LDAP.
When and how often should I run these LDAP Synchronization jobs?
Retrieve Latest LDAP Changes process is always the first implementation task but can also be run periodically, say daily1, to keep the tables synchronized with subsequent updates to LDAP. For example, if you know that a failure has occurred between OIM and Oracle Fusion HCM, then you can run Retrieve Latest LDAP Changes to ensure that user and role information is synchronized.
It is recommended to run the Send Pending LDAP Requests process at least daily to ensure that future-dated changes are identified and processed as soon as they take effect. For example, you could schedule this process to automatically run daily.
For the LDAP/OIM reconciliation, it is generally recommended to run the full reconciliation (Job Name: LDAP Role Create and Update Full Reconciliation) periodically e.g. monthly, but run the incremental reconciliation (Job Name: LDAP Role Create and Update Reconciliation) more frequently in-between full reconciliations runs e.g. Daily or hourly.
Indeed, MyOracle Support Doc ID 1507370.1 recommends setting the incremental LDAP/OIM reconciliation jobs to run every 5 minutes or even more frequently, depending on your business needs, to avoid issues with asynchronous data from LDAP to OIM.
There are a number of articles on MyOracleSupport that provide guidance on LDAP issues. Generally speaking the cause of these issues are due to the LDAP reconciliation jobs not having been run, or not having been run in the correct order. Below are a few sample issues reported, included here as pointers for those who may be struggling to resolve an issue:
- User and Role Provisioning - Troubleshooting Guide (Doc ID 1459830.1) Helpful as it walks through a number of issues and how to overcome them.
- Message "The User Request Is Pending" Displays on the Manager Users-User Details (Doc ID 1409103.1)
- Out-of-Sync Role Information Prevent User From Seeing Correct Options In Fusion Applications Navigator Menu (Doc ID 1392703.1)
- Accessing Home Page Tab Getting Intermittent Error: "PER-PER_POTRT_INACTIVE_ASSIGNMENT, can not be accessed." (Doc ID 1492040.1)
- Fusion Applications - IT Security Manager Role Not Found In Oracle Identity Manager (Doc ID 1377101.1).
- User Account In Pending Status In HCM Manage User Account Page After HR2HR Load (Doc ID 1571217.1). Highlights that if the creation date for a user is in the future, even after running the ‘Send Pending LDAP Requests process, the user create request only gets processed after reaching this creation date.
Once you’re up and running and happily synchronizing, please do give a thought to tuning your LDAP Synchronization jobs. Review to the MyOracle Support articles on Performance Tuning Guidelines and Diagnostics Collection for Oracle Identity Manager (OIM) (Doc ID 1539554.1) and Tuning Settings For LDAP Reconciliation Between OID And OIM 11g (Doc ID 1534049.1) for more information.
Other useful links
- Identity Management Forum on MyOracle Support. Get your questions answered, receive OIM updates and more.
- How to Setup LDAP Sync After Install in OIM 11g (Doc ID 1272682.1) Explains how to setup Oracle Identity Manager (OIM) 11g LDAP sync feature after the product install is done. This article is applicable to OIM version 184.108.40.206 only.
- How to Create New User from Oracle Identity Management (OIM)? (Doc ID 1384051.1)
- How To Clean Up User Data In A Fusion Application Environment (Doc ID 1494265.1) Explains how to remove existing user data and reload (for project implementation purposes).
- How to Validate Fusion Application Users And Roles Using Oracle Identity Manager [Video] (Doc ID 1359326.1)
- LDAP scripts to assist with troubleshooting Fusion Apps user access related issues (Doc ID 1356241.1)
- Support also have numerous diagnostic tests available for analyzing where things may have gone wrong. See Fusion Applications Troubleshooting Overview Master Doc ID 109.1. For example,What Diagnostic Tests Are Available For Fusion Human Capital Management (Doc ID 1358207.1) – Steps to run the diagnostic test ‘user and role provisioning diagnostics’ and ‘user and role: user details’.
1 - Overview Chapter of Oracle® Fusion Applications Coexistence for HCM Implementation Guide 11g Release 6 (11.1.6) Part Number E20378-04