7 Developing Event Handlers for Extending User Management Operations

7.2.2.1 Implementing Custom Event Handlers

To implement custom event handlers:

1. Implement one of the SPIs mentioned in Table 7-3 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 7-1 shows a sample custom validation handler code fragment that checks to ensure that $ is not used in a password.

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.

// 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

Example 7-3 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

// 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;
}

7.2.2.2 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.

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

   Note:

   You need not define all the custom event definitions in the same file. They could be split across multiple new event definition files or they could be added to any existing event definition file. Exporting the desired event definition file, modifying it, and importing it back implements the latter. For information about exporting and importing event definition files, see Chapter 30, "MDS Utilities and User Modifiable Metadata Files".