5 Extending the Functionality of the Connector

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

• Section 5.1, "Configuring Limited Reconciliation Using Multiple Resource Objects"

• Section 5.2, "Adding New Attributes for Target Resource Reconciliation"

• Section 5.3, "Adding New Attributes for Provisioning"

• Section 5.4, "Removing Attributes Mapped for Target Resource Reconciliation and Provisioning"

• Section 5.5, "Configuring the Connector for Provisioning to Multiple Installations of the Target System"

• Section 5.6, "Configuring the Connector for Reconciliation of Multiple Installations of the Target System"

• Section 5.7, "Configuring the Generation of Single-Use Passwords for the Reset Password Operation"

5.1 Configuring Limited Reconciliation Using Multiple Resource Objects

In order to account for multiple user types in an organization, limited reconciliation across multiple resource objects is available. Use the resourceObject property of the VOYAGER_ID.properties file to specify the resource object that you want to use during reconciliation. You can enter more than one resource object in the value of the _resourceObject_ property. In addition, you can include CA Top Secret (TSS) attribute-value pairs to filter records for each resource object.

The following is a sample format of the value for the _resourceObject_ property:

_resourceObject_:[ATTRIBUTE1:VALUE1]RESOURCE_OBJECT1,[ATTRIBUTE2:VALUE2]RESOURCE_OBJECT2, . . .

As shown in the sample format, specifying a filter attribute is optional. If you do not specify a filter attribute, then all records for that resource object are reconciled.

Apply the following guidelines while specifying a value for the _resourceObject_ property:

• The names of the resource objects must be the same as the names that you specified while creating the resource objects by using the Design Console.

• The TopSecret attribute names must be the same as the names used in the LDAP Gateway configuration files.

  See Also:

  Section 2.9, "Installing and Configuring the LDAP Gateway" for information about the LDAP Gateway configuration files

• The value must be a regular expression as defined in the java.util.regex Java package. Note that the find methodology of the regex matcher is used rather than the matches methodology. This means that a substring matching rule can be specified in the pattern, rather than requiring the entire string matching rule.

• Multiple values can be matched, with each individual value being separated by a vertical bar (|). For example:

  [ATTRIBUTE:VALUE1|VALUE2|VALUE3]RESOURCE_OBJECT
  

• Multiple filters can be applied to the attribute and to the same resource object. For example:

  [ATTRIBUTE1:VALUE1]&[ATTRIBUTE2:VALUE2]RESOURCE_OBJECT
  

The following is a sample value for the _resourceObject_ property:

_resourceObject_:(tso.holdclass:X)TSSR01,(category:value1|value2|value3)TSSResourceObject2,(tso)TSSResourceObject24000,Resource

In this sample value:

• (tso.holdclass:X)TSSRO1 represents a user with X as the attribute value for the TSO Holdclass segment. Records that meet this criterion are reconciled with the TSSRO1 resource object.

• (category:value1|value2|value3)TSSResourceObject2 represents a user with value1, value2, or value3 as their category. Records that meet this criterion are reconciled with the TSSResourceObject2 resource object.

• (tso)TSSResourceObject24000 represents a user with TSO privileges. A TSO attribute value is not specified. Records that meet this criterion are reconciled with the TSSResourceObject24000 resource object.

• All other records are reconciled with the Resource resource object.

5.2 Adding New Attributes for Target Resource Reconciliation

Note:

You must ensure that new attributes you add for reconciliation contain only string-format data. Binary attributes must not be brought into Oracle Identity Manager natively.

By default, the attributes listed in Table 1-3 are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can add new attributes for target resource reconciliation.

The reconAttrs property contains the list of target system attributes that are mapped for real-time reconciliation with Oracle Identity Manager. This property found in the VOYAGER_ID.properties file. Attributes mapped for reconciliation are listed as the value of the reconAttrs property. If you want to add an attribute for reconciliation, then copy it from the REMOVED list to the list in the reconAttrs property.

For full reconciliation, the reconciliation scheduled task contains two sections: SingleValueAttributes and MultiValuedAttributes. Attributes that can have multiple values (such as MEMBER_OF containing multiple group names) should be entered as a comma-separated list in the MultiValuedAttributes property. All other attributes should be entered in the SingleValueAttributes property. Attributes entered in the MultiValuedAttributes property should NOT be included in the SingleValueAttributes property and vice versa.

If you are adding a custom target system attribute, then you must also add it to the list of attributes specified as the value of the configAttrs property in the tops.properties file. See Section 2.9, "Installing and Configuring the LDAP Gateway" for information about this property.

5.3 Adding New Attributes for Provisioning

By default, the attributes listed in Table 1-3 are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning.

To add a new attribute for provisioning:

See Also:

Oracle Fusion Middleware User's Guide for Oracle Identity Manager for detailed information about these steps

1. Log in to the Oracle Identity Manager Design Console.

2. Add the new attribute on the process form as follows:

   1. Expand Development Tools.

   2. Double-click Form Designer.

   3. Search for and open the UD_IDF_TOPS process form.

   4. Click Create New Version, and then click Add.

   5. Enter the details of the attribute.

   6. Click Save and then click Make Version Active.

3. Create an entry for the attribute in the lookup definition for provisioning as follows:

   1. Expand Administration.

   2. Double-click Lookup Definition.

   3. Search for and open the AtMap.TOPS lookup definition.

   4. Click Add and then enter the Code Key and Decode values for the attribute.

      The Code Key value must be the name of the field on the process form. The Decode value is the name of the attribute on the target system.

4. To enable update of the attribute during provisioning operations, create a process task as follows:

   See Also:

   Oracle Fusion Middleware User's Guide for Oracle Identity Manager for detailed information about these steps

   1. Expand Process Management, and double-click Process Definition.

   2. Search for and open the OIMTopSecretProvisioningProcess process definition.

   3. Click Add.

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

   5. Click Save.

   6. On the Integration tab of the Creating New Task dialog box, click Add.

   7. In the Handler Selection dialog box, select Adapter, click adpMODIFYTOPSUSER, and then click the Save icon.

      The list of adapter variables is displayed on the Integration tab.

   8. 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: Adapter return value

      Data Type: Object

      Map To: Response code

      Click the Save icon.

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

      Variable Number	Variable Name	Map To	Qualifier
      Second	idfResource	IT Resource	Not applicable
      Third	uid	Process Data	LoginId
      Fourth	attrName	Literal	cn string
      Fifth	attrValue	Process Data	UD_TOPS_ADV_NAME string

      
      

   10. Click the Save icon in the Editing Task dialog box, and then close the dialog box.

   11. Click the Save icon to save changes to the process definition.

5. If you are adding a custom attribute or custom dataset, then set values for the configDatasets_and _configAttrs_ properties in the tops.properties file. See Step 3 of Section 2.9, "Installing and Configuring the LDAP Gateway" for information about these properties.

5.4 Removing Attributes Mapped for Target Resource Reconciliation and Provisioning

Note:

You must not remove the uid, cn, sn, givenName, or userPassword attribute. These attributes are mandatory on the target system.

The reconAttrs property contains the list of target system attributes that are mapped for real-time reconciliation and provisioning. This property is found in the VOYAGER_ID.properties file. If you want to remove an attribute mapped for real-time reconciliation and provisioning, then remove it from the reconAttrs property.

The SingleValueAttributes and MultiValuedAttributes properties contain the list of target system attributes that are mapped for initial reconciliation. These properties are found in the TopSecret Reconcile All Users scheduled task. If you want to remove an attribute mapped for initial reconciliation, then remove it from the SingleValueAttributes or MultiValuedAttributes property.

5.5 Configuring the Connector for Provisioning to Multiple Installations of the Target System

You can configure the connector for multiple installations of the target system. You can also configure the connector for a scenario in which multiple logical partitions (LPARs), which are not associated with the first LPAR, are configured in the target system.

For each installation of the target system, you create an IT resource and configure an additional instance of the LDAP Gateway.

To configure the connector for the second installation of the target system:

Note:

Perform the same procedure for all installations of the target system.

1. Create an IT resource based on the OIMLDAPGatewayResourceType IT resource type.

   See Oracle Fusion Middleware User's Guide for Oracle Identity Manager for information about creating IT resources. See Table 2-2, "IT Resource Parameters" for information about the parameters of the IT resource.

2. Copy the current LDAP_INSTALL_DIR directory, including all the subdirectories, to a new location.

   Note:

   In the remaining steps of this procedure, LDAP_INSTALL_DIR refers to the newly copied directory.

3. Extract the contents of the LDAP_INSTALL_DIR/dist/idfserver.jar file.

4. In the beans.xml file, change the value of the port in the <property name="port" value="xxxx"/> line to specify a port that is different from the port used for the first instance of the LDAP Gateway. The default port number is shown in the following example:

   <bean id="listener" class="com.identityforge.idfserver.nio.Listener">
   <constructor-arg><ref bean="bus"/></constructor-arg>
   <property name="admin"><value>false</value></property>
   <property name="config"><value>../conf/listener.xml</value></property>
   <property name="port" value="5389"/>
   </bean>
   

   When you change the port number, you must make the same change in the value of the idfServerPort parameter of the IT resource that you create.

5. Save and close the beans.xml file.

6. Open the LDAP_INSTALL_DIR/conf/tops.properties file and set values for the following parameters:

   • _host_= Enter the IP address or host name of the mainframe.

   • _port_= Enter the port number for the second instance of the Provisioning agent.

   • _agentPort_= Enter the port number for the second instance of the Reconciliation agent.

     Note:

     The value of the _agentPort_ parameter must not be the same as that of the first instance if a second LPAR, which is not associated with the first LPAR, is configured in the target system. This value can be the same as the value of the idfServerPort parameter if you have two mainframe servers with CA Top Secret running on each server.

7. Save and close the tops.properties file.

8. Delete the LDAP_INSTALL_DIR/etc/VOYAGER_ID.properties file.

9. In a Linux or Solaris environment, if there are not enough socket file descriptors to open up all the ports needed for the server, then:

   1. In a text editor, open the run script from the LDAP_INSTALL_DIR/bin directory.

   2. Add the following line in the file:

      -Djava.nio.channels.spi.SelectorProvider=sun.nio.ch.PollSelectorProvider
       
      

   3. Save and close the file.

When you perform provisioning operations:

When you use the Administrative and User Console to perform provisioning, you can specify the IT resource corresponding to the CA Top Secret installation to which you want to provision the user.

5.6 Configuring the Connector for Reconciliation of Multiple Installations of the Target System

You can configure the connector for reconciling multiple installations of the target system. For each installation of the target system, you create a corresponding .properties file in the /ldapgateway/etc/ directory.

To configure the connector for additional installations of the target system:

Note:

Perform the same procedure for all installations of the target system.

1. Make a copy the current LDAP_INSTALL_DIR/etc/ .properties file, saving it in the /etc/ directory. The default name for this file is VOYAGER_ID.properties; otherwise, select the .properties file whose name matches the VOYAGER_ID of the target system you would like to configure for reconciliation.

   See Section 3.5, "Configuring the Started Tasks" for information about the VOYAGER_ID property.

2. Open the copied file and set a value for the following properties:

   • _itResource_

     Use this property to specify the name of the IT resource.

   • _userStatus_

     Enter either Provisioned or Enabled depending on the status that must be set for accounts that are created through target resource reconciliation.

   • _xlAdminId_

     Use the xlAdminId property to specify the user ID of a user belonging to the SYSTEM ADMINISTRATORS group.

   • _xlAdminPwd_

     Use the xlAdminPwd property to specify the password of the user whose user ID you specify as the value of the xlAdminId property. This property is used only on Oracle Identity Manager release 11.1.1. If required, you can encrypt the password for security purposes. You can use the propertyEncrypt script to encrypt passwords. This script is in the scripts directory on the installation media. The procedure to use the script is given in Step Error! Reference source not found. After you run the script, copy the encrypted password as the value of the xlAdminPwd property.

   • _xlAdminPwdEncrypt_

     Enter true as the value of the xlAdminPwdEncrypt property if you have set an encrypted password as the value of the xlAdminPwd property. Otherwise, enter false. This property is used only on Oracle Identity Manager release 11.1.1.

   • _xlJndiUrl_

     This property is used only on Oracle Identity Manager release 11.1.1.

     To determine the JNDI URL:

     1. In a text editor, open the following file:

        OIM_DC_HOME/xlclient/Config/xlconfig.xml

        Here, OIM_DC_HOME is the name and full path of the directory in which you install the Oracle Identity Manager Design Console.

     2. Copy the value of the java.naming.provider.url element.

     3. Set the value for the xlJndiUrl property.

        Sample value: t3://localhost:14000/oim

   • _xlJndiFactory_

     The default value is weblogic.jndi.WLInitialContextFactory. Do not change this default value. This property is used only on Oracle Identity Manager release 11.1.1.

   Note:

   In the remaining steps of this procedure, LDAP_INSTALL_DIR refers to the newly copied directory.

3. The Voyager reconciliation agent sends a unique identifier value, called VOYAGER_ID, each time a reconciliation event occurs. This value must match the name of the .properties file being used by the topsecret-adv-agent-recon.jar file for reconciliation.

   Rename the copied file to match the VOYAGER_ID property. For example, if the target system has VOYAGER_ID = VOYAGE14, then the .properties file should be named VOYAGE14.properties.

5.7 Configuring the Generation of Single-Use Passwords for the Reset Password Operation

You can create and configure an adapter that generates single-use passwords when the Reset Password operation is performed. To create the adapter:

See Also:

Oracle Fusion Middleware User's Guide for Oracle Identity Manager for detailed information about the steps of this procedure

1. Use the Adapter Factory to create a copy of the ResetPassword adapter.

2. Add the following variables to the adapter that you create:

   passwordExpire: boolean or String

   passwordExpireInterval: String

3. The idm.jar file is located in the JavaTasks directory. When you create and map the new adapter task, use the following functions defined in this file:

   • public String resetPassword(String idfUserId, String idfNewPwd, boolean expire, String expireInDays)

   • public String resetPassword(String idfUserId, String idfNewPwd, String expireNow, String expireInDays)

   In these functions, the expire and expireNow parameters expect the value true to expire users' passwords.

4. Compile the adapter.

5. Create a process task, and associate it with the object corresponding to the event for which you want single-use passwords to be generated. For example, you can associate the process task with the Password Updated task or with the event that the PWD_EXP check box on the process form is selected.