Extending the Functionality of the RSA Authentication Manager Connector

4 Extending the Functionality of the RSA Authentication Manager Connector

This chapter describes procedures that you can perform to extend the functionality of the connector for addressing your specific business requirements. This chapter discusses the following sections:

Note:

From Oracle Identity Manager Release 11.1.2 onward, lookup queries are not supported. For information on managing lookups by using the Form Designer in Identity System Administration, see Managing Lookups in Oracle Fusion Middleware Administering Oracle Identity Manager .

4.1 Determining Whether an Attribute Is an Identity Management Services or Authentication Manager Attribute

Some of the sections in this chapter describe procedures to map new attributes for reconciliation and provisioning. One of the steps of these procedures is to create an entry in the lookup definition that holds the mapping between target system and Oracle Identity Manager attributes. The Decode value of these lookup definitions contains a setting that requires you to specify whether the attribute is an Identity Management Services or Authentication Manager attribute.

To determine if an attribute is an Identity Management Services or Authentication Manager attribute:

Log in to the RSA Security Console.
From the Identity list, select Users and then select Manage Existing.
Use the Search feature to display details of either a single user or all users.
For any user in the list of users displayed, click the arrow next to the user ID.
From the menu displayed:
- Select View to display the list of Identity Management Services attributes.
- Select Authentication Settings to display the list of Authentication Manager attributes.

4.2 Adding New User or Token Attributes for Reconciliation

You can add new user or token attributes for reconciliation. By default, the attributes listed in Table 1-5 and Table 1-7 are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can add new attributes (standard or custom) for reconciliation.

Note:

This connector supports configuration of the preconfigured and custom attributes of RSA Authentication Manager for reconciliation.
Only single-valued attributes can be mapped for reconciliation.

This information is divided across the following sections:

4.2.1 Adding New Attributes

To add a new attribute on the process form, perform the following procedure:

Note:

If you have already added an attribute for provisioning, then you need not repeat steps performed here.

Log in to the Oracle Identity Manager Design Console.
Add the new attribute on the process form as follows:
1. Expand Development Tools, and double-click Form Designer.
2. If you want to add a user attribute, then search for and open the UD_AMUSER process form.
  
  If you want to add a token attribute, then search for and open the UD_AMTOKEN process form.
3. Click Create New Version, and then click Add.
4. Enter the details of the field.
  
  For example, if you are adding the EMAIL field, enter UD_AMUSER_EMAIL in the Name field and then enter other details such as Variable Type, Length, Field Label, and Field Type.
5. Click the Save icon, and then click Make Version Active. The following screenshot shows the new field added to the process form:
  
  Description of the illustration process_form_field.gif

4.2.2 Adding Attributes to Reconciliation Fields

To add the new attribute to the list of reconciliation fields in the resource object, perform the following procedure:

Expand Resource Management, and double-click Resource Objects.
Search for and open either the RSA Auth Manager User or the RSA Auth Manager Token resource object.
On the Object Reconciliation tab, click Add Field.
Enter the details of the field.

For example, enter EMAIL in the Field Name field and select String from the Field Type list.

Later in this procedure, you enter the field name as the Code value of the entry that you create in the lookup definition for reconciliation.
Click the Save icon. The following screenshot shows the new reconciliation field added to the resource object:

Description of the illustration recon_field.gif
Click Create Reconciliation Profile. This copies changes made to the resource object into the MDS.

4.2.3 Creating Reconciliation Field Mapping

To create a reconciliation field mapping for the new attribute in the process definition, perform the following procedure:

Expand Process Management, and double-click Process Definition.
Search for and open either the RSA Auth Manager User or the RSA Auth Manager Token process definition.
On the Reconciliation Field Mappings tab of the RSA Auth Manager User process definition, click Add Field Map.
From the Field Name list, select the field that you want to map.
Double-click the Process Data Field field, and then select the column for the attribute. For example, select UD_AMUSER_EMAIL.
Click the Save icon. The following screenshot shows the new reconciliation field mapped to a process data field in the process definition:

Description of the illustration process_defn_field_new.gif

4.2.4 Creating Entries in Lookup Definitions

To create an entry for the field in the lookup definition that holds attribute mappings for reconciliation, perform the following procedure:

Expand Administration.
Double-click Lookup Definition.
Search for and open one of the following lookup definitions:
- For Users: Lookup.RSAAM.UM.ReconAttrMap
- For Tokens: Lookup.RSAAM.Token.ReconAttrMap
Click Add and enter the Code Key and Decode values for the field. The Code Key value must be the name of the field in the resource object.

See User Fields for Target Resource Reconciliation for information about the Decode format for users.

See Token Fields for Target Resource Reconciliation for information about the Decode format for tokens.
Click the Save icon. The following screenshot shows the entry added to the lookup definition:

Description of the illustration field_lookup_definition.gif

4.2.5 Performing Changes in a New UI Form

You must replicate all changes made to the Form Designer of the Design Console in a new UI form.

Log in to Oracle Identity System Administration.
Create and activate a sandbox. See Creating a Sandbox and Activating and Deactivating a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.
Create a new UI form to view the newly added field along with the rest of the fields. See Creating Forms By Using the Form Designer in Oracle Fusion Middleware Administering Oracle Identity Manager.
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, and then save the application instance.
Publish the sandbox. See Publishing a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

4.3 Adding New User or Token Attributes for Provisioning

You can add new user or token attributes for reconciliation. By default, the attributes listed in Table 1-10 and Table 1-11 are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning.

Note:

Only single-valued attributes can be mapped for provisioning.

This information is divided across the following sections:

4.3.1 Adding New Attributes

To add a new attribute on the process form, perform the following procedure:

Note:

If you have already added an attribute for reconciliation, then you need not repeat steps performed here.

Log in to the Oracle Identity Manager Design Console.
Add the new attribute on the process form as follows:
1. Expand Development Tools, and double-click Form Designer.
2. If you want to add a user attribute, then search for and open the UD_AMUSER process form.
  
  If you want to add a token attribute, then search for and open the UD_AMTOKEN process form.
3. Click Create New Version, and then click Add.
4. Enter the details of the attribute.
  
  For example, if you are adding the EMAIL field, enter UD_AMUSER_EMAIL in the Name field, and then enter the rest of the details of this field.
5. Click the Save icon, and then click Make Version Active. The following screenshot shows the new field added to the process form:
  
  Description of the illustration process_form_field.gif

4.3.2 Creating Entries in Lookup Definitions

To create an entry for the attribute in the lookup definition that holds attribute mappings for provisioning, perform the following procedure:

Expand Administration.
Double-click Lookup Definition.
Search for and open one of the following lookup definitions:
- For Users: Lookup.RSAAM.UM.ProvAttrMap
- For Tokens: Lookup.RSAAM.Token.ProvAttrMap
Click Add and then enter the Code Key and Decode values for the attribute. Enter the Decode value in one of the following format:

See User Fields for Provisioning for more information about the Decode format for users.

See Token Fields for Provisioning for more information about the Decode format for tokens.

For example, enter EMAIL in the Code Key column and then enter email;IMS;Core;String;EMAIL in the Decode column. The following screenshot shows the entry added to the lookup definition:

Description of the illustration lookup_entry_prov.gif

4.3.3 Creating a Task to Enable Update

Create a task to enable update of the attribute during provisioning operations.

If you do not perform this procedure, then you will not be able to modify the value of the attribute after you set a value for it during the Create User provisioning operation.

To enable the update of the attribute during provisioning operations, add a process task for updating the attribute:

Expand Process Management, and double-click Process Definition.
Search for and open either the RSA Auth Manager User or the RSA Auth Manager Token process definition.
Click Add.
On the General tab of the Creating New Task dialog box, enter a name and description for the task and then select the following:

Conditional

Required for Completion

Allow Cancellation while Pending

Allow Multiple Instances
Click the Save icon. The following screenshot shows the new task added to the process definition:

Description of the illustration new_process_task.gif
On the Integration tab of the Creating New Task dialog box, click Add.
In the Handler Selection dialog box, select Adapter, click adpRSAMUPDATEUSER, and then click the Save icon.

The list of adapter variables is displayed on the Integration tab. The following screenshot shows the list of adapter variables:

Description of the illustration new_adapter.gif
To create the mapping for the first adapter variable:

Double-click the number of the first row.

In the Edit Data Mapping for Variable dialog box, enter the following values:

Variable Name: ParentFormProcessInstanceKey

Map To: Process Data

Qualifier: Process Instance

Click the Save icon.

To create mappings for the remaining adapter variables, use the data given in the following table:

Variable Name	Data Type	Map To	Qualifier	Literal Value
Adapter return value	Object	Response Code	NA	NA
attributeFieldName	String	Literal	String	EMAIL
itResourceFieldName	String	Literal	String	UD_AMUSER_ITRESOURCE
objectType	String	Literal	String	User
processInstanceKey	Long	Process Data	Process Instance	NA

Click the Save icon in the Editing Task dialog box, and then close the dialog box.
Click the Save icon to save changes to the process definition.

4.3.4 Performing Changes in a New UI Form

To perform all changes made to the Form Designer of the Design Console in a new UI form, perform the following procedure:

Log in to Oracle Identity System Administration.
Create and activate a sandbox. See Creating and Activating a Sandbox for more information.
Create a new UI form to view the newly added field along with the rest of the fields. See Creating a New UI Form for more information about creating a UI form.
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 5.c), and then save the application instance.
Publish the sandbox. See Publishing a Sandbox for more information.

4.4 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 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 validation of data:

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 org.identityconnectors.rsaam.extension;
import java.util.*;
public class RSAAMValidator {

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

Create a JAR file to hold the Java class.
Run the Oracle Identity Manager Upload JARs utility to post the JAR file created in Step 2 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.

See Also:
Upload JAR Utility in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager
If you created the Java class for validating a process form field for reconciliation, then:
1. Log in to the Design Console.
2. Create a lookup definition named Lookup.RSAAM.UM.ReconValidation.
3. In the Code Key column, enter the resource object field name that you want to validate. For example, Firstname. In the Decode column, enter the class name. For example, org.identityconnectors.rsaam.extension.RSAAMValidator.
4. Save the changes to the lookup definition.
5. Search for and open the Lookup.RSAAM.UM.Configuration lookup definition.
6. In the Code Key column, enter Recon Validation Lookup. In the Decode column, enter Lookup.RSAAM.UM.ReconValidation.
7. Save the changes to the lookup definition.
If you created the Java class for validating a process form field for provisioning, then:
1. Log in to the Design Console.
2. Create a lookup definition by the name Lookup.RSAAM.UM.ProvValidation.
3. In the Code Key column, enter the process form field label. For example, Firstname. In the Decode column, enter the class name. For example, org.identityconnectors.rsaam.extension.RSAAMValidator.
4. Save the changes to the lookup definition.
5. Search for and open the Lookup.RSAAM.UM.Configuration lookup definition.
6. In the Code Key column, enter Provisioning Validation Lookup. In the Decode column, enter Lookup.RSAAM.UM.ProvValidation.
7. Save the changes to the lookup definition.
Purge the cache to get the changes reflected in Oracle Identity Manager. See Purging Cache in Oracle Fusion Middleware Administering Oracle Identity Manager.

4.5 Configuring Transformation of Data During Reconciliation

Note:

This section describes an optional procedure. Perform this procedure only if you want to configure transformation of data during reconciliation.

You can configure the transformation of reconciled single-valued data according to your requirements. For example, you can append the domain name with the User ID.

To configure the transformation of data:

Write code that implements the required transformation logic in a Java class.

This transformation class must implement the transform method. The following sample transformation class modifies the User ID attribute by using values fetched from the __NAME__ attribute of the target system:

pacakge oracle.iam.connectors.rsaam;
import java.util.HashMap;
public class RSAAMTransformation {
public Object transform(HashMap hmUserDetails, HashMap
hmEntitlementDetails, String sField) throws ConnectorException {
      /*
      * 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 sUserName = (String) hmUserDetails.get("__NAME__");
        return sUserName + "@example.com";
        }
}

Create a JAR file to hold the Java class.
Run the Oracle Identity Manager Upload JARs utility to post the JAR file created in Step 2 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.

See Also:
Upload JAR Utility in Oracle Fusion Middleware Developing and Customizing Applications with Oracle Identity Manager
Create a new lookup definition by the name Lookup.RSAAM.UM.ReconTransformations and then add the following entry:
1. Log in to the Design Console.
2. Expand Administration, and then double-click Lookup Definition.
3. In the Code field, enter Lookup.RSAAM.UM.ReconTransformations as the name of the lookup definition.
4. Select the Lookup Type option.
5. On the Lookup Code Information tab, click Add.
6. In the Code Key column, enter the resource object field name on which you want to apply the transformation. For example: User ID.
7. In the Decode column, enter the name of the class file. For example: oracle.iam.connectors.rsaam.RSAAMTransformation.
8. Save the lookup definition.
Purge the cache to get the changes reflected in Oracle Identity Manager. See Purging Cache in Oracle Fusion Middleware Administering Oracle Identity Manager.