Best Practices from Oracle Development's A‑Team
OIM 11g OID (LDAP) Groups Request-Based Provisioning with custom approval – Part I
Introduction
In recent days, I was assigned the task to implement a use case that I am sure many customers of Oracle have in mind but are not sure how to implement in OIM 11g. I even saw some thread inquiring about this very topic with no answer. Well, after some time I was able to put together an implementation of a Custom Approval process and a Custom UI based on ADF to request entitlements for users which in turn will be converted to Group memberships in OID (this also applies to any standard LDAP connector supported by OIM since the architecture is very similar for all of them). This article will be divided in 2 parts.
To give the audience a little overview this diagram shows the architecture of the solution:
As shown in the figure above, the use case is implemented by taking advantage of a very powerful feature of OIM 11g, which is the integration with SOA to execute custom composites as approval processes. Inside the custom composite an invocation to a Web Service that implements the logic to insert records on the Child Table associated with the provisioning process instance of OID User Resource Object that in turn is associated with the Beneficiary of the original request. When an administrator provisions entitlements to a given person the following sequence of steps takes place:
- The WebService Data Control in the custom UI (ADF Web Application) inserts all the entitlements previously selected for this person into a Staging Table in Oracle Database.
- Then an API call to UserManager service is issued to create the OIM user in OIM.
- An Access Policy is evaluated against the recently created OIM user and an OID account is provisioned to the user.
- Once the OID user is created a process task which is dependent on the completion of the Create User Process Task gets executed. This process task reads the records in the staging table and does one of two things:
- If the entitlement doesn’t require approval, the process task directly inserts the Child Record in the UD_OID_GRP child table, which in turn causes the connector to add the group in the target system (OID in this case).
- If the entitlement requires approval, the process task creates a request to modify a provisioned resource using a pre-configured request template that has Template Level approval only (Request and Operation level approvals are configured with Auto-Approval flag on). The associated approval process is our custom composite, which will be described in detail later.
- For entitlements that require approval, the BPEL process part of the custom approval process retrieves the Login ID of the Approver for the requested entitlement. Then it copies the value of the approver’s login id into the task’s owner (part of the input payload).
- The Human Task picks the approver from the task owner and routes the request to the approver’s queue.
- The approver logs in to OIM and approves/rejects the request.
- Inside the composite, the Approved block executes upon request approval and calls a Web Service that exposes a method to insert the corresponding child table record into the Child Table. This in turn triggers the adapter to add the user to the group in the target system (OID)
There are several important things to keep in mind here:
- Even though the request type is MODIFYRESOURCE and the values for the child table attributes are submitted in the form, the child records are not inserted automatically after the request is approved. This has caused a lot of confusion for customers who have posted questions about how to accomplish this and no one had answered before. This is why one needs to implement the child record insertion logic and make it execute in the Approved block inside the BPEL process of the Custom Approval Process SOA composite. Later I will present such logic to you for reference.
- Remember that Request Based Provisioning is not configured nor enabled out of the box in OIM 11g after connector installation. You need to import the Data Sets into MDS (This applies to any of the LDAP type connectors of OIM in 11g’s world). I will provide the steps to accomplish this later in this post.
- Make sure Auto Pre-populate and Auto Save form are enabled for all provisioning processes that are automatic (OID User and OID Group).
Main Article
Now, let’s start with the procedure to make this happen. In order to implement this functionality we are going to need the following components in our solution:
- Java Process Task – The purpose of this task is to read the Staging table and for each entitlement assigned to the beneficiary user’s login ID, either a request will be submitted for approval or a direct entitlement provisioning is performed immediately.
- Approval Process Custom SOA Composite – This SOA composite includes the following elements:
- DB Adapter Web Service that retrieves the Approver Login ID for the requested Entitlement ID/Login ID combination.
- JAX-WS Web Service that inserts the Entitlement as a group in the Child Table of OID User Resource.
- Custom UI based on ADF and ADF Data Controls – This user interface provides access to the following functionality:
- Create Internal/External Entitlements
- Assign Approvers/Sponsors to Internal/External Entitlements respectively
- Create Simulation HR Accounts that will be converted into OIM users.
- Run the workflow to create OIM users and initiate the process of provisioning the LDAP OID Account and subsequently provisioning the corresponding entitlements as LDAP Groups.
- Request Template for Entitlements – This component links the custom approval process with the request for entitlements. The configuration of this request template is described in detail later.
- Approval Policy at Request Level – This Approval Policy is used to disable the out of the box Request Level approval that will send the request to the XELSYSADM user’s queue. This policy is configured as auto approved.
- Approval Policy at Operation Level – This Approval Policy is used to disable the out of the box Operation Level approval that will send the request to the XELSYSADM user’s queue. This policy is also configured for auto approval.
Java Process Task
This component is the one that does the heavy lifting when it comes to creating and submitting Modify Provisioned Resource Requests to OIM.
The figure below is the constructor of the Process Task. The parameters to the constructor allow the class to connect to the database hosting the Staging Table with the entitlements per user:
The figure shown next shows the method that obtains the entitlements for a given user and traverses the result set to submit requests for entitlements requiring approval or insert the records in OID User RO’s child table which will trigger the addition of the user into the corresponding group on the target system.
Here is the method that processes the entitlements returned by the query:
Notice the method buildBeneficiaryData presented below. This is a very important method since it actually builds the main structure of the request before submitting it.
This is the method that does direct provisioning of LDAP Groups:
The RESOURCE constant has the value of “OID User”.The RESOURCE_ATTR_NAME constant has the value of “Objects.Name”. This is to work with OID User Resource Object, if you need to work with a different LDAP Server, replace the value of this constant with the name of your LDAP Server Associated Resource Object.
For retrieving user attributes, we provide the following method:
Configure this task to be a dependant of the Create User Task of the OID User Provisioning process. That will ensure that the task only executes when the OID User has been successfully provisioned. For details on how to accomplish this, please refer to the OIM documentation part of the Fusion Middleware 11g documentation set.
Custom Approval Process (BPEL)
The requirement for this scenario is that some entitlements require approval from an Approver or a Sponsor depending on the type of entitlement being requested. Internal users request only Internal type entitlements and External users can only select External entitlements. This is enforced by the User Interface by displaying a list of selectable entitlements according to the type of user to be created in OIM. The most important elements to notice are:
The invocation task labeled as callGetEntApprover. This Task gets the Login ID of the BeneficiaryDetails and the Entitlement ID taken from the ObjectDetails parts of the inputVariable’s payload, which contains all the request data.
The invocation task labeled as call_addUserToLDAPGroup included in the block that is executed when the task gets approved. The Web Service takes two parameters:the login ID of the beneficiary and the entitlement ID of the requested entitlement. Both pieces of data come from the request data available in the inputVariable’s payload.
Disabling Request and Operation Level approvals
Out of the box, OIM has Request and Operation level approvals configured for standard requests. Both of these send an approval request to XELSYSADM and OIMINTERNAL user which are both part of the SYSTEM ADMINISTRATORS group. If this is not the desired effect, here is how to disable these approvals:
Create an Approval Policy for Request Level, the configuration from my implementation is presented below:
Now for the Operation Level approval here is the Approval Policy shown in the figure below:
Notice the value in the Scope of the policy: OID User. This is required for operation level Approval Policies. You have to select the Resource Object for which the Approval Process is defined. In my case it is the OID User but in other cases it could be iPlanet User, AD User, etc. The easiest way to do it is by Composite Name which is what I did for these two Approval Policies.