6 Extending the Functionality of the Generic REST Connector

After you generate and install the connector, you can extend its functionality to address your specific business requirements.

This chapter discusses the following optional configuration procedures:

6.1 Implementing Custom Authentication

If your target system uses an authentication mechanism that is not supported by this connector, then you must implement the authentication that your target system uses and then attach it to the connector by using the plug-ins exposed by this connector. Implementing custom authentication involves creating a Java class, overriding the Map<String, String> getAuthHeaders(Map<String, Object> authParams) method that returns the authorization header in the form of a map, and updating the connector installation media to include the new Java class.
All the target system configuration and authentication details that may be required for obtaining the authorization header are passed to the Map<String, String> getAuthHeaders(Map<String, Object> authParams) method through specific IT resource parameters. All the configuration properties exposed by this connector are accessible within this method as a part of "authParams".
To implement a custom authentication:
  1. Create a Java class for implementing custom authentication. This class must implement the org.identityconnectors.restcommon.auth.spi.AuthenticationPlugin interface.
    Note down the name of this Java class. You will provide the name of the Java class while configuring the IT resource for your target system which is described later in this guide.
  2. Override the Map<String, String> getAuthHeaders(Map<String, Object> authParams) method in the custom Java class.
    This method must implement the custom authentication logic that returns the authorization header in the form of a map For example, { Authorization = Bearer XXXXXXXXXX }. The authorization header contains the access token received from the target.
  3. Package the Java class implementing the custom authentication into a JAR file.
  4. Package the JAR file containing the custom authentication implementation with the connector bundle JAR as follows:

    Note:

    Ensure to package all the JARs for any other custom implementations that you may have.
    1. Extract the contents of the org.identityconnectors.genericrest-1.0.1115.jar file into a temp directory. This file is located in the GenericREST-RELEASE_NUMBER\bundle directory.
    2. Copy the JAR file containing the custom authentication (from Step 3) to the lib directory.
    3. Regenerate the connector bundle (org.identityconnectors.genericrest-1.0.1115.jar) by running the following command: 
      jar -cvfm org.identityconnectors.genericrest-1.0.1115.jar META-INF/MANIFEST.MF *

      Note:

      While updating the connector bundle, ensure that META-INF\MANIFEST.MF file is unchanged.
  5. Run the Oracle Identity Manager Delete JARs utility to delete any existing JARs in Oracle Identity Manager database before you upload the regenerated connector bundle. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    • For Microsoft Windows:

      OIM_HOME/server/bin/DeleteJars.bat

    • For UNIX:

      OIM_HOME/server/bin/DeleteJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being deleted, and the location from which the JAR file is to be deleted. Specify 4 (ICF Bundle) as the value of the JAR type.

  6. Run the Oracle Identity Manager Upload JARs utility to upload the regenerated connector bundle to Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    • For Microsoft Windows:

      OIM_HOME/server/bin/UploadJars.bat

    • For UNIX:

      OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 (ICF Bundle) as the value of the JAR type.

  7. Restart Oracle Identity Manager.
This completes the procedure for implementing a custom authentication.

6.2 Implementing Custom Parsing

By default, the connector supports only JSON parsing during reconciliation runs. If the reconciliation data from your target system is not in JSON format, then you must write a custom parser implementation for your data format.

To implement custom parsing:
  1. Create a Java class for implementing the custom parser. This class must implement the org.identityconnectors.restcommon.parser.spi.ParserPlugin interface.
    Note down the name of this Java class. You will provide the name of the Java class while configuring the IT resource for your target system which is described later in this guide.
  2. Override the String parseRequest(Map<String, Object> attrMap) and List<Map<String, Object>> parseResponse(String response, Map<String, String> parserConfigParams) methods in the custom Java class.
    The String parseRequest(Map<String, Object> attrMap) method implements the logic for parsing an attribute and generates a string request payload.
    The List<Map<String, Object>> parseResponse(String response, Map<String, String> parserConfigParams) method implements the logic for parsing the string response received from the target in this class.
  3. Package the Java class implementing the custom parser into a JAR file.
  4. Package the JAR file containing the custom parser implementation with the connector bundle JAR as follows:

    Note:

    Ensure to package all the JARs for any other custom implementations that you may have.
    1. Extract the contents of the org.identityconnectors.genericrest-1.0.1115.jar file into a temp directory. This file is located in the GenericREST-RELEASE_NUMBER\bundle directory.
    2. Copy the JAR file containing the custom authentication (from Step 3) to the lib directory.
    3. Regenerate the connector bundle (org.identityconnectors.genericrest-1.0.1115.jar) by running the following command: 
      jar -cvfm org.identityconnectors.genericrest-1.0.1115.jar META-INF/MANIFEST.MF *

      Note:

      While updating the connector bundle, ensure that META-INF\MANIFEST.MF file is unchanged.
  5. Run the Oracle Identity Manager Delete JARs utility to delete any existing JARs in Oracle Identity Manager database before you upload the regenerated connector bundle. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    • For Microsoft Windows:

      OIM_HOME/server/bin/DeleteJars.bat

    • For UNIX:

      OIM_HOME/server/bin/DeleteJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being deleted, and the location from which the JAR file is to be deleted. Specify 4 (ICF Bundle) as the value of the JAR type.

  6. Run the Oracle Identity Manager Upload JARs utility to upload the regenerated connector bundle to Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    • For Microsoft Windows:

      OIM_HOME/server/bin/UploadJars.bat

    • For UNIX:

      OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 4 (ICF Bundle) as the value of the JAR type.

  7. Restart Oracle Identity Manager.
This completes the procedure for implementing custom parsers.

6.3 Adding Custom OIM User Fields for Trusted Source Reconciliation

While generating the connector, you create mappings between OIM User fields and the corresponding target system fields by specifying a value for the alias entry. After generating the connector, if there are additional target system fields that you want to use during trusted source reconciliation, then you can extend the set of fields by creating custom or user-defined fields (UDFs).
To add new fields for trusted source reconciliation:
  1. Add the new field on the OIM User process form. See Configuring Custom Attributes in Oracle Fusion Middleware Administering Oracle Identity Manager for information on creating UDFs.

    Note:

    If the new field that you want to add is already present on the OIM User field, then skip this step and proceed to the next step.
  2. Log in to the Design Console.
  3. In the resource object definition, add the reconciliation field corresponding to the attribute as follows:
    1. Expand the Resource Management folder, and then double-click Resource Objects.
    2. Search for and open the resource object corresponding to your target system.
    3. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.
    4. Specify a value for the field name. For example, Building.
    5. From the Field Type list, select a data type for the field. In addition, if you want to designate the attribute as a mandatory attribute, then select the check box.
    6. Click the Save icon, and then close the dialog box.
    7. Click the Save icon.
  4. Create a reconciliation field mapping in the process definition as follows:
    1. Expand the Process Management folder, and then double-click Process Definition.
    2. Search for and open the process definition for your target system.
    3. On the Reconciliation Field Mapping tab, click Add Field Map.
    4. From the Field Name list in the Add Reconciliation Field Mapping dialog box, select the name that you have assigned to the attribute created in the resource object.
    5. Select a value from the User Attribute menu and click OK.
    6. If the field mapping is a key field for matching the process data, check the key Field for Reconciliation matching check box.
    7. Click the Save icon.
  5. Create a reconciliation profile as follows:
    1. Expand the Resource Management folder, and then double-click Resource Objects.
    2. Search for and open the resource object corresponding to your target system.
    3. On the Object Reconciliation tab, click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
    4. Click the Save icon.
  6. Add an entry for the attribute in the lookup definition for reconciliation attribute mapping as follows:
    1. Expand the Administration folder, and then double-click Lookup Definition.
    2. Search for and open the Lookup.RESOURCE.UM.ReconAttrMap lookup definition.
    3. To add a roe, click Add.
    4. In the Code Key column, enter the name that you have set for the attribute in the resource object. For example, Building.
    5. In the Decode column, enter the corresponding name of the target system column. For example, BUILDING.
    6. Click the Save icon.

6.4 Adding Custom Fields for Target Resource Reconciliation

While generating the connector, you create mappings between OIM User fields and the corresponding target system fields by specifying a value for the alias entry. After generating the connector, if there are additional target system fields that you want to use during target resource reconciliation, then you can extend the set of fields by creating custom or user-defined fields (UDFs).
To add a custom field for reconciliation:
  1. Log in to the Design Console.
  2. In the resource object definition, add the reconciliation field corresponding to the attribute as follows:
    1. Expand the Resource Management folder, and then double-click Resource Objects.
    2. Search for and open the resource object corresponding to your target system.
    3. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.
    4. Specify a value for the field name. For example, Building.
    5. From the Field Type list, select a data type for the field. In addition, if you want to designate the attribute as a mandatory attribute, then select the check box.
    6. Click the Save icon, and then close the dialog box.
    7. Click the Save icon.
  3. Add an entry for the attribute in the lookup definition for reconciliation attribute mapping as follows:
    1. Expand the Administration folder, and then double-click Lookup Definition.
    2. Search for and open the Lookup.RESOURCE.UM.ReconAttrMap lookup definition.
    3. To add a row, click Add.
    4. In the Code Key column, enter the name that you have set for the attribute in the resource object. For example, Building.
    5. In the Decode column, enter the corresponding name of the target system column. For example, BUILDING.
    6. Click the Save icon.
  4. Add the attribute as a field on the process form as follows:
    1. Expand the Development Tools folder, and then double-click Form Designer.
    2. Search for and open the process form for your target system.
    3. Click Create New Version to create a version of the process form. Then, enter a version name and click the Save icon.
    4. Click Add.
    5. In the newly added row, enter values for the Name, Variant Type, Field Label, and Field Type columns. If required, enter values for the rest of the columns.

      Note:

      • If the attribute on the target system is of the Time, or Timestamp format, then set the value of the Variant Type column to String.

      • If you want to handle date attributes of the target system as a date editor, then set the value of the Variant Type column to Date. Otherwise, set it to String.

    6. Click the Save icon.
    7. Click Make Version Active to activate the new version of the process form.
  5. Create a reconciliation field mapping in the process definition as follows:
    1. Expand the Process Management folder, and then double-click Process Definition.
    2. Search for and open the process definition for your target system.
    3. On the Reconciliation Field Mapping tab, click Add Field Map.
    4. From the Field Name list in the Add Reconciliation Field Mapping dialog box, select the name that you have assigned to the attribute created in the resource object.
    5. Double-click the Process Data Field, a new pop-up will appear. The entries in the pop-up correspond to the process form fields.
    6. Select the corresponding newly added field from the pop-up.
    7. If the field mapping is a key field for matching the process data, check the key Field for Reconciliation matching check box.
    8. Click the Save icon.
  6. Create a reconciliation profile as follows:
    1. Expand the Resource Management folder, and then double-click Resource Objects.
    2. Search for and open the resource object corresponding to your target system.
    3. On the Object Reconciliation tab, click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.
    4. Click the Save icon.
  7. Perform all changes made to the Form Designer of the Design Console (in Step 4) in a new UI form as follows:
    1. Log in to Oracle Identity System Administration.
    2. Create and active a sandbox. See Creating and Activating a Sandbox.
    3. Create a new UI form to view the newly added field along with the rest of the fields. See Creating a New UI Form.
    4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form (created in Step 7.c), and then save the application instance.
    5. Publish the sandbox. See Publishing a Sandbox.
  8. Add the attribute for provisioning. See Adding Custom Fields for Provisioning.

6.5 Adding Custom Fields for Provisioning

While generating the connector, by performing the procedure described in Generating and Installing the Connector Metadata Package you create mappings between the OIM User fields and the corresponding target system fields (columns) by specifying a value for the alias entry. If there are additional target system fields that you want to use during provisioning, then you can extend the existing set of fields by creating custom or user-defined fields (UDFs).
To add a new user-defined field for provisioning:
  1. Add the attribute as a field on the process form as follows:

    Note:

    Directly proceed to the next step if you have already added the field to the process form while performing the procedure described in Adding Custom Fields for Target Resource Reconciliation.
    1. Expand Development Tools, and then double-click Form Designer.
    2. Search for and open the process form for your target system.
    3. Click Create New Version to create a version of the form. Then, enter a version name and click the Save icon.
    4. Click Add.
    5. In the newly added row, enter values for the Name, Variant Type, Field Label, and Field Type columns. If required, enter values for the rest of the columns.

      Note:

      • If the attribute on the target system is of the Time, or Timestamp format, then set the value of the Variant Type column to String.

      • If you want to handle date attributes of the target system as a date editor, then set the value of the Variant Type column to Date. Otherwise, set it to String.

    6. Click the Save icon.
    7. Click Make Version Active to activate the new version of the process form.
  2. Perform all changes made to the Form Designer of the Design Console (in Step 1) in a new UI form as follows:
    1. Log in to Oracle Identity System Administration.
    2. Create and active a sandbox. See Creating and Activating a Sandbox.
    3. Create a new UI form to view the Creating and Activating a Sandbox newly added field along with the rest of the fields. See Creating a New UI Form.
    4. Associate the newly created UI form with the application instance of your target system. To do so, open the existing application instance for your resource, from the Form field, select the form (created in Step 2.c.), and then save the application instance.
    5. Publish the sandbox. See Publishing a Sandbox.
  3. Add an entry in the lookup definition for provisioning attribute mappings as follows:
    1. Expand Administration, and then double-click Lookup Definition.
    2. Search for and open the Lookup.RESOURCE.UM.ProvAttrMap lookup definition.
    3. To add a row, click Add.
    4. In the Code Key column, enter the field label for the attribute on the process form. See Step 1 for information about this field name.
    5. In the Decode column, enter the corresponding name of the target system column. For example, BUILDING.
    6. Click the Save icon.
  4. To enable updates of the attribute, add an update process task in the process definition as follows:
    1. Expand Process Management, and then double-click Process Definition.
    2. Search for and open the process definition for your target system.
    3. On the Tasks tab, click Add.
    4. On the General tab of the dialog box that is displayed, enter a name and description for the task, and then select the following fields in the Task Properties section:

      • Conditional

      • Required for Completion

      • Allow Cancellation while Pending

      • Allow Multiple Instances

      Note:

      The name must be in the PROCESS_FORM_FIELD_NAME Updated format.
    5. Click the Save icon.
    6. On the Integration tab, attach the adapter responsible for performing the update account provisioning operations and map the adapter variables as listed in the following table:
      Variable Name Data Type Map To Qualifier Literal Value

      processKeyInstance

      Long

      Process Data

      Process Instance

      NA

      Adapter return value

      Object

      Response Code

      NA

      NA

      objectType

      String

      Literal

      String

      User

      attrFieldName

      String

      Literal

      String

      Building

      itResourceFieldName

      String

      Literal

      String

      IT Resource Form Field Name
    7. Click the Save icon.
    8. On the Response tab, add appropriate responses.
    9. Click the Save icon.
    10. Click the Save icon and then close the dialog box.
  5. Adding the attribute for reconciliation.
    When you add an attribute on the process form, you must also enable reconciliation of values for that attribute from the target system. See Adding Custom Fields for Target Resource Reconciliation .

6.6 Configuring Transformation of Data During User Reconciliation

You can configure transformation of reconciled single-valued data according to your requirements. For example, you can use First Name and Last Name values to create a value for the Full Name field in Oracle Identity Manager.

Note:

This section describes an optional procedure. Perform this procedure only if you want to configure transformation of data during reconciliation.
To configure transformation of data:
  1. Write code that implements the required transformation logic in a Java class.
    The following sample transformation class creates a value for the Full Name attribute by using values fetched from the FIRST_NAME and LAST_NAME columns of the target system:
       package oracle.iam.connectors.common.transform;   

   import java.util.HashMap;   

   public class TransformAttribute {         

          /*       
          Description:Abstract method for transforming the attributes              
          
          param hmUserDetails<String,Object>          
 
          HashMap containing parent data details         
 
          param hmEntitlementDetails <String,Object>          

          HashMap containing child data details               

          */       
          public Object transform(HashMap hmUserDetails, HashMap hmEntitlementDetails,String sField) {       
          /*        
           * You must write code to transform the attributes.        
           Parent data attribute values can be fetched by         
           using hmUserDetails.get("Field Name").        
           *To fetch child data values, loop through the        
           * ArrayList/Vector fetched by hmEntitlementDetails.get("Child          Table")        
           * Return the transformed attribute.        
           */       
          String sFirstName= (String)hmUserDetails.get("First Name");       
          String sLastName= (String)hmUserDetails.get("Last Name");       
          String sFullName=sFirstName+"."+sLastName;       
          return sFullName;       
          } 
   }
  2. Create a JAR file to hold the Java class.
  3. Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 1 as the value of the JAR type.

  4. Create a lookup definition for transformation and add an entry to it as follows:
    1. Log in to the Design Console.
    2. Expand Administration, and then double-click Lookup Definition.
    3. In the Code field, enter Lookup.RESOURCE.UM.ReconTransformation as the name of the lookup definition.
    4. Select the Lookup Type option.
    5. On the Lookup Code Information tab, click Add.
      A new row is added.
    6. In the Code Key column, enter the name of the resource object field into which you want to store the transformed value. For example: FirstName.
    7. In the Decode column, enter the name of the class that implements the transformation logic. For example, oracle.iam.connectors.common.transform.TransformAttribute.
    8. Save the changes to the lookup definition.
  5. Add an entry in the Lookup.RESOURCE.UM.Configuration lookup definition to enable transformation as follows:
    1. Expand Administration, and then double-click Lookup Definition.
    2. Search for and open the Lookup.RESOURCE.UM.Configuration lookup definition.
    3. Create an entry that holds the name of the lookup definition used for transformation as follows:

      Code Key: Recon Transformation Lookup

      Decode: Lookup.RESOURCE.UM.ReconTransformation

    4. Save the changes to the lookup definition.

6.7 Configuring Validation of Data During Reconciliation and Provisioning

You can configure validation of reconciled and provisioned single-valued data according to your requirements.

For example, you can validate data fetched from the FIRST_NAME column to ensure that it does not contain the number sign (#). In addition, you can validate data entered in the First Name field on the process form so that the number sign (#) is not sent to the target system during provisioning operations.
For data that fails the validation check, the following message is displayed or recorded in the log file:

oracle.iam.connectors.icfcommon.recon.SearchReconTask : handle : Recon event skipped, validation failed [Validation failed for attribute: [FIELD_NAME]]

Note:

This feature cannot be applied to the Locked/Unlocked status attribute of the target system.
To configure validation of data:
  1. Write code that implements the required validation logic in a Java class.

    The following sample validation class checks if the value in the First Name attribute contains the number sign (#):

    package com.validate; 
import java.util.*; 
public class MyValidation { 
public boolean validate(HashMap hmUserDetails,               
              HashMap hmEntitlementDetails, String field) {             
            /*          
         * You must write code to validate attributes. Parent          
         * data values can be fetched by using hmUserDetails.get(field)          
         * For child data values, loop through the          
         * ArrayList/Vector fetched by hmEntitlementDetails.get("Child Table")          
         * Depending on the outcome of the validation operation,           
         * the code must return true or false.          
         */          
         /*          
         * In this sample code, the value "false" is returned if the field          
         * contains the number sign (#). Otherwise, the value "true" is          
         * returned.          
         */             
            boolean valid=true;             
            String sFirstName=(String) hmUserDetails.get(field);             
            for(int i=0;i<sFirstName.length();i++){               
              if (sFirstName.charAt(i) == '#'){                     
                    valid=false;                      
                    break;               
              }              
            }             
            return valid;       
       } 
}
  2. Create a JAR file to hold the Java class.
  3. Run the Oracle Identity Manager Upload JARs utility to post the JAR file to the Oracle Identity Manager database. This utility is copied into the following location when you install Oracle Identity Manager:

    Note:

    Before you use this utility, verify that the WL_HOME environment variable is set to the directory in which Oracle WebLogic Server is installed.

    For Microsoft Windows:

    OIM_HOME/server/bin/UploadJars.bat

    For UNIX:

    OIM_HOME/server/bin/UploadJars.sh

    When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. Specify 1 as the value of the JAR type.

  4. If you created the Java class for validating a process form field for reconciliation, then:
    1. Log in to the Design Console.
    2. Expand Administration, and then double-click Lookup Definition.
    3. In the Code field, enter Lookup.RESOURCE.UM.ReconValidation as the name of the lookup definition.
    4. Select the Lookup Type option.
    5. On the Lookup Code Information tab, click Add.
      A new row is added.
    6. In the Code Key column, enter the resource object field name. For example, First Name.
    7. In the Decode column, enter the class name. For example, com.validate.MyValidation.
    8. Save the changes to the lookup definition.
    9. Search for and open the Lookup.RESOURCE.UM.Configuration lookup definition.
    10. Create an entry with the following values:

      Code Key: Recon Validation Lookup

      Decode: Lookup.RESOURCE.UM.ReconValidation

    11. Save the changes to the lookup definition.
  5. If you created the Java class for validating a process form field for provisioning, then:
    1. Log in to the Design Console.
    2. Expand Administration, and then double-click Lookup Definition.
    3. In the Code field, enter Lookup.RESOURCE.UM.ProvValidation as the name of the lookup definition.
    4. Select the Lookup Type option.
    5. On the Lookup Code Information tab, click Add.
      A new row is added.
    6. In the Code Key column, enter the process form field name. In the Decode column, enter the class name.
    7. Save the changes to the lookup definition.
    8. Search for and open the Lookup.RESOURCE.UM.Configuration lookup definition.
    9. Create an entry with the following values:

      Code Key: Provisioning Validation Lookup

      Decode: Lookup.RESOURCE.UM.ProvValidation

    10. Save the changes to the lookup definition.