5 Extending the Functionality of the Generic REST Connector

You can extend the functionality of the connector to address your specific business requirements.

The following topics discuss information related to using the connector for performing reconciliation and provisioning operations:

• Implementing Custom Authentication

• Implementing Custom Parsing

• Configuring Transformation and Validation of Data

• Configuring Action Scripts

• Configuring the Connector for Multiple Installations of the Target System

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

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

5.3 Configuring Transformation and Validation of Data

Configure transformation and validation of user account data by writing Groovy script logic while creating your application.

You can configure transformation of reconciled single-valued user 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 Governance.

Similarly, 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 attribute 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.

To configure transformation or validation of user account data, you must write Groovy scripts while creating your application. For more information about writing Groovy script-based validation and transformation logic, see Validation and Transformation of Provisioning and Reconciliation Attributes of Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

5.4 Configuring Action Scripts

You can configure Action Scripts by writing your own Groovy scripts while creating your application.

These scripts can be configured to run before or after the enable, disable, or delete an account provisioning operations. For example, you can configure a script to run before every user creation operation.

For information on adding or editing action scripts, see Updating the Provisioning Configuration in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

5.5 Configuring the Connector for Multiple Installations of the Target System

You must create copies of configurations of your base application to configure it for multiple installations of the target system.

The following example illustrates this requirement:

The London and New York offices of Example Multinational Inc. have their own installations of the target system, including independent schema for each. The company has recently installed Oracle Identity Governance, and they want to configure it to link all the installations of the target system.

To meet the requirement posed by such a scenario, you must clone your application which copies all configurations of the base application into the cloned application. For more information about cloning applications, see Cloning Applications in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.