OpenIDM 3.1.0 restful APIs - how to

Supported Operations: Create,Read,Update,Delete,Action and Query

URI for accessing a managed objects: /openidm/managed/type/id

Example: /openidm/managed/user/?_queryId=query-all-ids

URI for accessing system objects: /openidm/system/resource-name/type/id

Example :  /openidm/system/ad/__ACCOUNT__/?_queryId=query-all-ids

As part of the http request the following headers need to be added for the authentication:

X-OpenIDM-Username  - This will be the user name configured in open-idm

X-OpenIDM-Password - This is the password

Create:

Http Type : POST

URI: /openidm/managed/user/?_action=create

Headers:

Body:

Output:

**Note: You can also create objects using HTTP PUT. Also you can pass the _id value incase you don't want to generate the random UUID.  Here are the request details:

URI: /openidm/managed/user/mike123

Headers:

Body:

Output:

Read - Query:

HTTP Type: GET

URI: /openidm/managed/user/?_queryId=query-all-ids

Headers:

Output:

QueryFilter:

For equal to:

URI: /openidm/managed/user/?_queryFilter=userName+eq+"vishnuindla"&_fields=userName,givenName,sn,mail

For starts with:

URI:

URI: /openidm/managed/user/?_queryFilter=userName+sw+"vishnu"&_fields=userName,givenName,sn,mail

Headers:

Output:

Update:

Http Type:  PUT

URI: /openidm/managed/user/0bffb692-5881-4bd0-abd5-edb1e4fc23e3

Headers:

Body:

Output:

Delete:

HTTP Type: DELETE

URI: /openidm/managed/user/8476d76e-a09c-4223-877d-965a686491c8

Headers:

Body:

 Output:

OAM - OIM Integration Password Management

Out-of-the-box self service password management feature of OIM can be used if OAM-OIM integration is enabled. One of the key factors necessary for enabling OAM-OIM integration is that LDAP sync should be enabled in OIM.

OAM-OIM integration process extends the user schema in LDAP. The list of attributes and object classes which are added to schema can be found in IAM_HOME/oam/server/oim-intg/ldif/ojd/schema/ojd_user_schema_add.ldif (This is OUD specific LDIF file).
In OAM, this enablement process also sets the flag "IdentityServiceEnabled" in oam-config.xml to "true".

When a user is created in OIM (through API or console), it gets synched to LDAP (OUD for an instance) with new attributes. The value for couple of attributes are set at the time of user creation, for example: obpasswordchangeflag is set to true. This flag is also set to true when resetPassword API in OIM.

In an OAM-OIM integrated environment when a user tries to authenticate to an application protected by OAM (which uses OUD for user authentication), OAM checks for couple of attributes. Based on these attributes OAM will redirect the user to URLs which are configured in oam-config.xml.

1. If obpasswordchangeflag is true, then user will be redirected to the URL configured for “ForcedPasswordChangeURL” attribute in oam-config.xml.
2. If user has tried multiple times with invalid credentials his “oblogintrycount” attribute will keep on incrementing. Once this value exceeds the value configured in oam-config.xml the user will be redirected to “AccountLockedURL”.

Now to change the flag to false or update the login try count, OIM comes into picture. Using OIM APIs for change password or unlock account, these attribute values could be set to false(obpasswordchangeflag) or 0(oblogintrycount) respectively.

OAM checks for these values when two conditions are satisfied, first IdentityServiceEnabled is true and secondly user identity store (used for authenticating the user) in OAM is a default store.  Only then these attributes are validated. Else OAM ignores and authenticates the user and redirects the user to the landing page. 
In an OAM-OIM integrated environment for OAM to honour password management attributes its very important that user directory store used for authentication is set as default store.

Also another important thing to know is that while setting up resources, policies and authentication schemes, the authentication level of force change password page (configured in oam-config.xml) should be lower than the authentication level of protected application. If its set to same level, when a user is redirected to force change password page (when obpasswordchangeflag is true), and user opens another tab in the same browser to access the protected application,  user will be redirected to the protected resource even when his/her password's state in LDAP is temporary.

OIM 11GR2 Custom Transformation Provider GTC

1. Create a class which will implement com.thortech.xl.gc.spi.TransformationProvider.
2. You will need to add the jar file xlGenConnector.jar to the classpath which can be found in the OIM server lib
3. This class can be a part of your JavaTasks jar or can be in a different jar altogether. This has to be uploaded to JavaTasks using the UploadJar Utility
4. The following MDS file need to be uploaded to the location: /db/GTC/ProviderDefinitions
5. Make sure to update the class,name and the response codes in the below xml file
1. <?xml version='1.0' encoding='UTF-8'?>
   <Provider>
      <Transformation>
        <TransformationProvider class="com.suncorp.javatasks.CustomTransformationProvider"
                                name="CustomTransformationProvider">
          <Configuration>
            <Parameter type="Runtime" datatype="String" required="YES" encrypted="NO" name="Input"/>
            <Response code="REMQUOTES_INPUTSTR_MISSING" description="Input String is Missing"/>
          </Configuration>
        </TransformationProvider>
     </Transformation>
   </Provider>
     
6.  You will need to create 2 resource bundle files. And they should be named after the transformationprovider name you have specified in the xml above. In my case they will be as shown below:
1. CustomTransformationProvider.properties
2. CustomTransformationProvider_en.properties
7. The following will be the contents of the property file:
8. ###### Transformation Provider  ######
   
   
   
   
   #gc.provider.TransformationProvider.CustomTransformationProvider=CustomTransformationProvider
   TransformationProvider.CustomTransformationProvider.Input.label=Input
   TransformationProvider.CustomTransformationProvider.Input.description=UserLogin
   #gc.error.TransformationProvider.CustomTransformationProvider.REMQUOTES_INPUTSTR_MISSING= Input String Missing
   
   
   GC.GCPROV.TransformationProvider.CustomTransformationProvider.REMQUOTES_INPUTSTR_MISSING=Input String Missing
   GC.GCPROV.TransformationProvider.CustomTransformationProvider.REMQUOTES_INPUTSTR_MISSING.description=The input string is missing.
    
9. Upload the above resource bundles to the following location using the UploadResourceBundles Utility which will be option "2": Connector Resources
10. Once all this is in place you should be able to see the transformation provider in the modify GTC connector UI as shown below:
11. 
    
    
12. You should be good to go and test your transformation.
     
     

OIM Performance Monitoring 11G R2 PS 1

OIM performance can be monitored here:

http://OIM-HOST:PORT/dms

Simple OIM UI customisation

The below Oracle PDF link is quite helpful incase of any simple UI customisations:

Simple Web Customization

OIM 11GR2 PS2 Installation steps - High Level

1. Install weblogic 10.3.6 or later
2. Run the RCU. All the R2 PS2 IAM related downloads can be found at http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/oid-11gr2-2104316.html
3. Download the latest SOA versioned 11.1.1.7
4. Install the IAM components into the selected middleware home
5. Install SOA
6. Extend the weblogic domain or create a new domain for all the required IAM components by running the domain config.
7. Create the policy store
8. Configure SOA
9. Configure OIM
10. Start SOA followed by OIM

Few Issues I ran into were:

- Had to increase the number of DB cursors to 800

- Had to increase the number of DB processes to 800

- Since I am running it on a vm image the image itself requires 6GB of RAM

The install of R2 PS2 is very straight forward and there are no issues/known issues while setting up OIM so far like the ones we faced while setting up R2 PS1. I will post more on the enhancements and features introduced in this release.

All the related documentation can be found below:

http://docs.oracle.com/cd/E40329_01/index.htm

http://www.oracle.com/technetwork/middleware/id-mgmt/overview/oim-11gr2-whats-new-1709505.pdf

OIM 11GR2 PS2 UI Screens

Virtualization Session closed [Root exception is oracle.ods.virtualization.service.VirtualizationException: Virtualization Session closed]

Virtualization Session closed [Root exception is oracle.ods.virtualization.service.VirtualizationException: Virtualization Session closed]

]]

[2013-10-24T16:32:55.662+10:00] [oim_server1] [ERROR] [] [oracle.iam.platform.entitymgr.provider.ldap] [tid: [ACTIVE].ExecuteThread: '24' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: xelsysadm] [ecid: 25895f7b083841ff:686be906:141e3ebf07f:-8000-0000000000003637,0] [APP: oim#11.1.2.0.0] An error occurred while modifying the entity in LDAP, and the corresponding error is - {0}[[

javax.naming.NamingException: Error: OPERATIONS_ERROR

Virtualization Session closed [Root exception is oracle.ods.virtualization.service.VirtualizationException: Virtualization Session closed]

        at oracle.ods.virtualization.jndi.OVDUtil.mapErrorCode(OVDUtil.java:200)

        at oracle.ods.virtualization.jndi.OVDContext.modifyAttributes(OVDContext.java:678)

        at javax.naming.directory.InitialDirContext.modifyAttributes(InitialDirContext.java:153)

        at oracle.iam.platform.entitymgr.provider.ldap.LDAPUtil.modifyAttributes(LDAPUtil.java:1137)

        at oracle.iam.platform.entitymgr.provider.ldap.LDAPDataProvider.modifyEntity(LDAPDataProvider.java:966)

        at oracle.iam.platform.entitymgr.provider.ldap.LDAPDataProvider.modify(LDAPDataProvider.java:845)

        at oracle.iam.platform.entitymgr.impl.EntityManagerImpl.modifyEntity(EntityManagerImpl.java:391)

 Solution:

The above error is encountered when the connection pooling paramter in the "Directory Server" IT Resource is set to "false" . Set it ot "True" and then try again.

oracle.ods.virtualization.engine.util.DirectoryException: LDAP Error 1 : No LDAP connection available to process request for DN: cn=Directory Manager

Solution:
Increase maxPoolSize / maxPoolChecks by modifying
adapters.os_xml located at <DOMAIN_HOME>/config/fmwconfig/ovd/default

tcAdpUtils/genXellerateAdapter encounter some problems: /tmp/oracle/oim/adapters/adpTEST.java (No such file or directory)

Solution:

- Stop the OIM server
-Clear the tmp directory under the oimserver
-restart the OIM server

Try recompiling the adapters again. This should fix it!!

If not try giving the +RWX permissions to the folder /tmp/oracle. It should do the magic.

OIM 11GR2 PS1 Certifications

In OIM PS1 they have embedded both the certification and attestation features. The certification is the same as the OIA certification. To turn on the certification in OIM modify the below system property and restart the server:

Property Name: Display Certification or Attestation
Value: Certification or Attestation or both

Xellerate User Task Flow- Modification

To enable the triggers in the xellerate user task flow follow the below steps:

Change the system property in OIM:



Save it and restart the server.

After restart you should be able to trigger any task based on the USR profile updates including User Enable/Disable.

Custom Event Handlers in OIM 11G-From OIM Dev Guide

Implementing Custom Event Handlers

To implement custom event handlers:

1. Implement one of the SPIs mentioned in table below to write a custom pre-process, post-process, or validation handler.
   
   Table 7-3 SPIs to Write Custom Event Handlers

   Stage	SPI to implement
   Pre-Process	oracle.iam.platform.kernel.spi.PreProcessHandler
   Post-Process	oracle.iam.platform.kernel.spi.PostProcessHandler
   Validation	oracle.iam.platform.kernel.spi.ValidationHandler

2. Include the following JAR files in the class path to compile a custom class:
   From OIM_INSTALL_HOME/server/platform
   
   • iam-platform-kernel.jar
   • iam-platform-util.jar
   • iam-platform-context.jar
   • iam-plaftorm-authz-service.jar
   From OIM_INSTALL_HOME/designconsole/lib
   
   • OIMClient.jar
   • xlAPI.jar
   From OIM_INSTALL_HOME/designconsole/lib and OIM_INSTALL_HOME/server:
   All other JAR files
3. Create a library of JAR files containing the custom classes.

The following code samples illustrate how to invoke Oracle Identity Manager 9.1.x APIs and 11g APIs to customize user management operations. See SPI Javadocs for more information.

Example 1: Custom Password Validation

Example shows a sample custom validation handler code fragment that checks to ensure that $ is not used in a password.

Example 7-1 Sample Custom Validation Handler

throws ValidationException, ValidationFailedException {
    HashMap<String, Serializable> parameters = orchestration.getParameters();
    String password = (parameters.get("usr_password") instanceof ContextAware)
      ? (String) ((ContextAware) parameters.get("usr_password")).getObjectValue()
      : (String) parameters.get("usr_password");
    if (password.contains("$")) {
      throw new ValidationFailedException();
    }
}

Example 2: Custom Pre-process Event Handler to Set Middle Initial

Example 7-2 shows a sample custom pre process event handler code fragment that sets the middle initial to the first letter of the first name if the user does not have a middle name.

Example 7-2 Sample Custom Pre Process Event Handler

// This custom preprocess event handler sets the first letter of the first name as the middle initial
// when the user doesn't have a middle name
public EventResult execute(long processId, long eventId, Orchestration orchestration) {
   HashMap<String, Serializable> parameters = orchestration.getParameters();
   // If the middle name is empty set the first letter of the first name as the     middle initial
  String middleName = getParamaterValue(parameters, "Middle Name");
  if (isNullOrEmpty(middleName)) {
     String firstName = getParamaterValue(parameters, "First Name");
     middleName = firstName.substring(0,1);
     orchestration.addParameter("Middle Name", middleName);
  }
  return new EventResult();
}
private String getParamaterValue(HashMap<String, Serializable> parameters, String key) {
  String value = (parameters.get(key) instanceof ContextAware)
  ? (String) ((ContextAware) parameters.get(key)).getObjectValue()
  : (String) parameters.get(key);
  return value;
}

Example 3: Custom Post-process Event Handler to Provision Resource Object

 shows a sample custom post process event handler code fragment that provisions a resource object OBJ005 to a user whose role is ROLE 00.5

Example 7-3 Sample Custom Post Process Event Handler

// This custom post process event handler provisions resource object 'OBJ005' to a user who has role 'ROLE 005'
public EventResult execute(long processId, long eventId, Orchestration orchestration) {
tcUserOperationsIntf userOperationsService = Platform.getService(tcUserOperationsIntf.class);
try {
String userKey = getUserKey(processId, orchestration);
if (hasRole(userKey, "ROLE 005")) {
long objKey = findObject("OBJ001");
userOperationsService.provisionResource(Long.getLong(userKey), objKey);
}
} catch (Exception e) {
throw new EventFailedException("Error occurred ", e);
}
 
return new EventResult();
}
 
// This method retrieves the key of the user entity on which an operation is performed
// This method shows how to retrieve the operation being performed, entity type
// and the associated value objects 
private String getUserKey (long processID, Orchestration orchestration) {
String userKey;
String entityType = orchestration.getTarget().getType();
EventResult result = new EventResult();
 
if (!orchestration.getOperation().equals("CREATE")) {
userKey = orchestration.getTarget().getEntityId();
} else {
OrchestrationEngine orchEngine = Platform.getService(OrchestrationEngine.class);
userKey = (String) orchEngine.getActionResult(processID);
}
return userKey;
}
 
// This method checks if a given user has a given role. 
// It demonstrates how to invoke a OIM 11g API from a custom event handler
private boolean hasRole(String userKey, String roleName) 
throws Exception {
RoleManager roleManager = Platform.getService(RoleManager.class);
List<Identity> roles = roleManager.getUserMemberships(userKey);
 
for (Iterator iterator = roles.iterator(); iterator.hasNext();) {
Role role = (Role) iterator.next();
if (roleName.equals((String)role.getAttribute("Role Name"))) {
return true;
}
 
}
return false;
}
 
// This method finds details about a resource object with the given name. 
// It demonstrates how to invoke a 9.1.x API from a custom event handler
private long findObject(String objName) throws Exception {
long objKey = 0;
tcObjectOperationsIntf objectOperationsService = Platform.getService(tcObjectOperationsIntf.class);
HashMap params = new HashMap();
params.put("Objects.Name", objName);
tcResultSet objects = objectOperationsService.findObjects(params);
for (int i = 0; i < objects.getRowCount(); i++) {
objects.goToRow(i);
if (objects.getStringValue("Objects.Name").equals(objName)) {
objKey = objects.getLongValue("Objects.Key");
}
}
return objKey;
}

Creating Plug-ins for Custom Event Handlers

To create plug-ins containing custom event handlers, you need to develop the appropriate event handler classes. See Chapter 6, "Developing Plug-ins" for details.

Note:

Ensure that plug-in point used in the plug-in definition is set to oracle.iam.platform.kernel.spi.EventHandler.

Note:

The plug-ins can be packaged as required, just like the JAR files, as long as they adhere to the packaging guidelines.

Here is an example of a plug-in XML file:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins>
  <plugins pluginpoint="oracle.iam.platform.kernel.spi.EventHandler">
    <plugin pluginclass=  
       "oracle.oim.extensions.preprocess.SamplePreprocessExtension" 
        version="1.0" 
        name="SamplePreprocessExtension">
    </plugin>
    <plugin pluginclass= 
        "oracle.oim.extensions.postprocess.SamplePostprocessExtension"
         version="1.0" 
         name="SamplePostprocessExtension">
    </plugin>
    <plugin pluginclass= 
       "oracle.oim.extensions.validation.SampleValidationExtension"
        version="1.0" 
        name="SampleValidationExtension">
    </plugin>
  </plugins>
</oimplugins>

7.2.2.3 Defining Custom Events

Take these steps to define custom events:

1. Create the metadata XML file containing definitions of all the custom events.
   Example 7-4 shows what a metadata file looks like:
   
   Example 7-4 Sample Metadata XML File for Custom Event Definitions

   <?xml version='1.0' encoding='utf-8'?>
   <eventhandlers>
     <!-- Custom preprocess event handlers -->
     <action-handler
       class="oracle.oim.extensions.preprocess.SamplePreprocessExtension"
       entity-type="User" 
       operation="CREATE" 
       name="SamplePreprocessExtension"
       Stage="preprocess"
       order="1000" 
       sync="TRUE"/>
    
     <!-- Custom postprocess event handlers -->
     <action-handler
       class="oracle.oim.extensions.postprocess.SamplePostprocessExtension"
       entity-type="User" 
       operation="CREATE" 
       name="SamplePostprocessExtension"
       stage="postprocess"
       order="1000" 
       sync="TRUE"/>
    
     <action-handler
       class="oracle.oim.extensions.postprocess.SamplePostprocessExtension"
       entity-type="User" 
       operation="MODIFY" 
       name="SamplePostprocessExtension"
       stage="postprocess"
       order="1000" 
       sync="TRUE"/>
    
     <!-- Custom validation event handlers -->
      <validation-handler
       class="oracle.oim.extensions.validation.SampleValidationExtension"
       entity-type="User" 
       operation="CREATE" 
       name="SampleValidationExtension"
       order="1000"/>       
    
      <validation-handler
       class="oracle.oim.extensions.validation.SampleValidationExtension"
       entity-type="User" 
       operation="MODIFY" 
       name="SampleValidationExtension"
       order="1000"/>       
   </eventhandlers>
   

2. Import these event definitions into MDS. See Chapter 30, "MDS Utilities and User Modifiable Metadata Files" for more information. For a shiphome-based install the scripts necessary to import the event definitions are located in the following directory:
   OIM_HOME/common/wlst