3 Configuring the Connector

After you deploy the connector, you must configure it to meet your requirements. This chapter discusses the following connector configuration procedures:

Note:

These sections provide both conceptual and procedural information about configuring the connector. It is recommended that you read the conceptual information before you perform the procedures.

• Configuring Reconciliation

• Configuring Provisioning

• Configuring the Connector for Multiple Installations of the Target System

• Transforming Data Reconciled Into Oracle Identity Manager

3.1 Configuring Reconciliation

As mentioned earlier in this guide, reconciliation involves duplicating in Oracle Identity Manager the creation of and modifications to user accounts on the target system. This section discusses the following topics related to configuring reconciliation:

• Partial Reconciliation

• Batched Reconciliation

• Configuring System Properties

• Configuring the Target System As a Trusted Source

• Configuring the Reconciliation Scheduled Tasks

• Enabling Reconciliation in Oracle Identity Manager Release 9.0.1

• Adding Custom Attributes for Reconciliation

3.1.1 Partial Reconciliation

By default, all target system records that are added or modified after the last reconciliation run are reconciled during the current reconciliation run. You can customize this process by specifying the subset of added or modified target system records that must be reconciled. You do this by creating filters for the reconciliation module.

Creating a filter involves specifying a value for the UserNameFilter scheduled task attribute, which will be used in the query SELECT criteria to retrieve the records to be reconciled. For example, if you specify the value JDoe for this attribute, then all target system user records with the user name JDoe are reconciled.

While deploying the connector, follow the instructions in the "Specifying Values for the Scheduled Task Attributes" section to specify a value for this attribute.

3.1.2 Batched Reconciliation

During a reconciliation run, all changes in the target system records are reconciled into Oracle Identity Manager. Depending on the number of records to be reconciled, this process may require a large amount of time. In addition, if the connection breaks during reconciliation, then the process would take longer to complete.

You can configure batched reconciliation to avoid these problems.

To configure batched reconciliation, you must specify values for the following user reconciliation scheduled task attributes:

• BatchSize: Use this attribute to specify the number of records that must be included in each batch. The default value is 1000.

• NumberOfBatches: Use this attribute to specify the total number of batches that must be reconciled. The default value is All.

If you specify a value other than All, then some of the newly added or modified user records may not get reconciled during the current reconciliation run. The following example illustrates this:

Suppose you specify the following values while configuring the scheduled tasks:

• BatchSize: 20

• NumberOfBatches: 10

Suppose that 314 user records were created or modified after the last reconciliation run. Of these 314 records, only 200 records would be reconciled during the current reconciliation run. The remaining 114 records would be reconciled during the next reconciliation run.

You specify values for the BatchSize and NumberOfBatches attributes by following the instructions described in the "Specifying Values for the Scheduled Task Attributes" section.

3.1.3 Configuring System Properties

To configure system properties:

1. Open the Oracle Identity Manager Design Console.

2. Navigate to the System Configuration page.

3. Check if there is an entry for "Default date format." If this entry is not there, then perform Step 4.

4. Add a new entry in the Server category:

   • Name: Default date format

   • Keyword: XL.DefaultDateFormat

   • Value: yyyy/MM/dd hh:mm:ss z

5. Click Save.

3.1.4 Configuring the Target System As a Trusted Source

While configuring the connector, the target system can be designated as a trusted source or target resource. If you designate the target system as a trusted source, then during a reconciliation run:

• For each newly created user on the target system, an OIM User is created.

• Updates made to each user on the target system are propagated to the corresponding OIM User.

If you designate the target system as a target resource, then during a reconciliation run:

• For each account created on the target system, a resource is assigned to the corresponding OIM User.

• Updates made to each account on the target system are propagated to the corresponding resource.

Note:

Skip this section if you do not want to designate the target system as a trusted source for reconciliation.

Configuring trusted source reconciliation involves the following steps:

1. Import the XML file for trusted source reconciliation, XellSSHUser.xml, by using the Deployment Manager. This section describes the procedure to import the XML file.

   Note:

   Only one target system can be designated as a trusted source. If you import the XellSSHUser.xml file while you have another trusted source configured, then both connector reconciliations would stop working.

2. Specify values for the attributes of the SSH UserTrusted Reconciliation task scheduled task. This procedure is described later in this guide.

To import the XML file for trusted source reconciliation:

1. Open the Oracle Identity Manager Administrative and User Console.

2. Click the Deployment Management link on the left navigation bar.

3. Click the Import link under Deployment Management. A dialog box for opening files is displayed.

4. Locate and open the XellSSHUser.xml file, which is in the OIM_HOME/xellerate/XLIntegrations/SSH/xml directory. Details of this XML file are shown on the File Preview page.

5. Click Add File. The Substitutions page is displayed.

6. Click Next. The Confirmation page is displayed.

7. Click Import.

8. In the message that is displayed, click Import to confirm that you want to import the XML file and then click OK.

3.1.5 Configuring the Reconciliation Scheduled Tasks

Note:

If you want to run full reconciliation at any time after first-time reconciliation, then run the following commands on the target system before you run the scheduled tasks:

> etc/passwd1
> etc/shadow1

To configure the reconciliation scheduled task:

1. Open the Oracle Identity Manager Design Console.

2. Expand the Xellerate Administration folder.

3. Select Task Scheduler.

4. Click Find. The details of the predefined scheduled tasks are displayed.

5. Enter a number in the Max Retries field. This number represents the number of times Oracle Identity Manager must attempt to complete the task before assigning the ERROR status to the task.

6. Ensure that the Disabled and Stop Execution check boxes are not selected.

7. In the Start region, double-click the Start Time field. From the date-time editor that is displayed, select the date and time at which you want the task to run.

8. In the Interval region, set the following schedule parameters:

   • To set the task to run on a recurring basis, select the Daily, Weekly, Recurring Intervals, Monthly, or Yearly option.

     If you select the Recurring Intervals option, then you must also specify the time interval at which you want the task to run on a recurring basis.

   • To set the task to run only once, select the Once option.

9. Provide values for the user-configurable attributes of the scheduled task. Refer to the "Specifying Values for the Scheduled Task Attributes" section for information about the values to be specified.

   See Also:

   Oracle Identity Manager Design Console Guide for information about adding and removing task attributes

10. Click Save. The scheduled task is created. The INACTIVE status is displayed in the Status field, because the task is not currently running. The task is run at the date and time that you set in Step 7.

After you create the scheduled task, proceed to the "Enabling Reconciliation in Oracle Identity Manager Release 9.0.1" section.

3.1.5.1 Specifying Values for the Scheduled Task Attributes

You must specify values for the attributes of the following user reconciliation scheduled tasks:

• Scheduled Tasks for Trusted Source and Target Resource Reconciliation

• Scheduled Task for Lookup Field Reconciliation

3.1.5.1.1 Scheduled Tasks for Trusted Source and Target Resource Reconciliation

Depending on whether you want to implement trusted source or target resource reconciliation, you must specify values for the attributes of one of the following user reconciliation scheduled tasks:

• SSH User Trusted Source Reconciliation Task (Scheduled task for trusted source reconciliation)

• SSH User Target Resource Reconciliation Task (Scheduled task for target resource reconciliation)

The following table describes the attributes of both scheduled tasks.

Note:

• Attribute values are predefined in the connector XML file that you import. Specify values only for those attributes that you want to change.

• Values (either default or user-defined) must be assigned to all the attributes. If even a single attribute value were left empty, then reconciliation would not be performed.

Attribute	Description	Sample Value
Server	Name of the IT resource	SSH LINUX
IsTrusted	Specifies whether or not reconciliation is to be carried out in trusted mode	Specify Yes for trusted source reconciliation. Specify No for target resource reconciliation.
Target System Recon - Resource Object name	Name of the target system resource object	SSH User
Trusted Source Recon - Resource Object name	Name of the trusted source resource object	Default value: Xellerate User Specify false (in lowercase) if you do not want to configure trusted source reconciliation
BatchSize	Number of records in each batch that is reconciled If you do not want to implement batched reconciliation, then specify nodata. See Also: The "Batched Reconciliation" section	The default value is 1000.
NoOfBatches	Number of batches to be reconciled The number of records in each batch is specified by the BatchSize attribute. See Also: The "Batched Reconciliation" section	Specify All if you want to reconcile all the batches. This is the default value. Specify an integer value if you want to reconcile only a fixed number of batches
UserNameFilter	This is a filter attribute. Use this attribute to specify the user name (User Login) for which you want to reconcile user records. If you do not want to use this filter attribute, then specify Nodata. See Also: The "Partial Reconciliation" section	The value can be either the user name or Nodata. The default value is Nodata.
TransformLookupName	This is a lookup attribute. Use this attribute to specify the lookup name used for the transformation class map that is stored in the lookup tables. This attribute is valid only when the UseTransformMapping attribute is set to Yes.	Lookup.Reconciliation.TransformationMap
UseTransformMapping	Specifies whether or not the transform mappings accessed by the TransformLookupName attribute must be used.	Enter Yes if you want the transform mappings accessed by the TransformLookupName attribute to be used. Otherwise, enter No. The default value is No.

After you specify values for these task attributes, proceed to Step 10 of the procedure to create scheduled tasks.

3.1.5.1.2 Scheduled Task for Lookup Field Reconciliation

The following are attributes of the TelnetSSHGroupLookupReconTask scheduled task for lookup field reconciliation.

Attribute	Description
Server	Name of the IT resource
Lookup Field Name	Enter UD_Lookup_SSH_PrimaryGroupNames.
Exclusion List	Enter a comma-delimited list of the names of groups on the target system that you do not want to reconcile.

3.1.6 Enabling Reconciliation in Oracle Identity Manager Release 9.0.1

If you are using Oracle Identity Manager release 9.0.1, then you must perform the following procedure to enable reconciliation:

See Also:

Oracle Identity Manager Design Console Guide

1. Open the Process Definition form for the SSH User. This form is in the Process Management folder.

2. Click the Reconciliation Field Mappings tab.

3. For each field that is of the IT resource type:

   1. Double-click the field to open the Edit Reconciliation Field Mapping window for that field.

   2. Deselect Key Field for Reconciliation Matching.

3.1.7 Adding Custom Attributes for Reconciliation

Note:

- In this section, the term "attribute" refers to the identity data fields that store user data.

- You need not perform this procedure if you do not want to add custom attributes for reconciliation.

By default, the attributes listed in the "Reconciliation Module" section are mapped for reconciliation between Oracle Identity Manager and the target system. If required, you can map additional attributes for reconciliation as follows:

See Also:

Oracle Identity Manager Design Console for detailed instructions on performing the following steps

1. Open the following file in the OIM_HOME/xellerate/XLIntegrations/SSH/config directory:

   For AIX:

   userAttribute_AIX_recon.properties
   

   For non-AIX platforms:

   userAttribute_NonAIX_recon.properties 
   

2. At the end of this file, some of the attribute definitions are preceded by comment characters. You can uncomment the definition of an attribute to make it a part of the list of reconciliation attributes. If required, you can also add new attributes in this file. The format that you must use is as follows:

   For AIX:

   Target_System_Attribute=OIM_Server_Attribute
   

   For example:

   maxage=Users.AccountExpiryDate
   

   In this example, AccountExpiryDate is the reconciliation field and maxage is the equivalent server command parameter. As a standard, the prefix "Users." is added at the start of all reconciliation field names.

   For non-AIX platforms:

   OIM_Server_Attribute=Target_System_Attribute_index
   

   For example:

   Users.DefaultShell=6
   

   In this example, DefaultShell is the reconciliation field and 6 is the equivalent server Target Server Attributes index. As a standard, the prefix "Users." is added at the start of all reconciliation field names.

3. In the resource object definition, add a reconciliation field corresponding to the new attribute as follows:

   1. Open the Resource Objects form. This form is in the Resource Management folder.

   2. Click Query for Records.

   3. On the Resource Objects Table tab, double-click the SSH User resource object to open it for editing.

   4. On the Object Reconciliation tab, click Add Field to open the Add Reconciliation Field dialog box.

   5. Specify a value for the field name.

      For AIX:

      You must specify the name that is to the right of the equal sign in the line that you uncomment or add while performing Step 2.

      For example, if you uncomment the maxage=Users.AccountExpiryDate line in Step 2, then you must specify Users.AccountExpiryDate as the attribute name.

      For non-AIX platforms:

      You must specify the name that is to the left of the equal sign in the line that you uncomment or add while performing Step 2.

      For example, if you uncomment the Users.DefaultShell=6 line in Step 2, then you must specify Users.DefaultShell as the attribute name.

   6. From the Field Type list, select a data type for the field.

      For example: String

   7. Save the values that you enter, and then close the dialog box.

   8. If required, repeat Steps d through g to map more fields.

4. Add a new field in the process form.

   1. Open the UD_SSH process form. This form is in the Development Tools folder of the Oracle Identity Manager Design Console.

   2. Click Create New Version.

   3. In the Create a New Version dialog box, specify the version name in the Label field, save the changes, and then close the dialog box.

   4. From the Current Version list, select the newly created version.

   5. On the Additional Columns tab, click Add.

   6. Specify the new field name and other values. For the example described in Step 3 in the connector guide, you enter the value UD_SSH_DEFAULTSHELL.

   7. Click Make Version Active and then save the changes.

5. Modify the provisioning process to include the mapping between the newly added attribute and the corresponding reconciliation field as follows:

   1. Open the SSH User provisioning process. The provisioning process form is in the Process Management folder.

   2. On the Reconciliation Field Mappings tab, click Add Field Map to open the Add Reconciliation Field Mapping dialog box.

   3. Enter the required values, save the values that you enter, and then close the dialog box.

      For the example described in Step 3 in the connector guide, you enter the values Users.DefaultShell [String] and UD_SSH_DEFAULTSHELL.

   4. If required, repeat Steps b and c to map more fields.

3.2 Configuring Provisioning

As mentioned earlier in this guide, provisioning involves creating or modifying a user's account information on the target system through Oracle Identity Manager.

This section discusses the following topics related to configuring provisioning:

• Compiling Adapters

• Adding Custom Attributes for Provisioning

3.2.1 Compiling Adapters

Note:

You must perform the procedure described in this section if you want to use the provisioning features of Oracle Identity Manager for this target system.

You need not perform the procedure to compile adapters if you have performed the procedure described in "Installing the Connector on Oracle Identity Manager Release 9.1.0 or Later".

Adapters are used to implement provisioning functions. The following adapters are imported into Oracle Identity Manager when you import the connector XML file:

See Also:

The "Supported Functionality" section for a listing of the provisioning functions that are available with this connector

• SSH Create User

• SSH Delete User

• SSH Set Password

• SSH Enable User

• SSH Disable User

• SSH Prepopulate User Login

• SSH updateDateField

• SSH updateIntField

• SSH updateStrField

• SSH updateHomeDir

You must compile these adapters before they can be used in provisioning operations.

To compile adapters by using the Adapter Manager form:

1. Open the Adapter Manager form.

2. To compile all the adapters that you import into the current database, select Compile All.

   To compile multiple (but not all) adapters, select the adapters you want to compile. Then, select Compile Selected.

   Note:

   Click Compile Previously Failed to recompile only those adapters that were not compiled successfully. Such adapters do not have an OK compilation status.

3. Click Start. Oracle Identity Manager compiles the selected adapters.

4. If Oracle Identity Manager is installed in a clustered environment, then copy the compiled adapters from the OIM_HOME/xellerate/Adapter directory to the same directory on each of the other nodes of the cluster. If required, overwrite the adapter files on the other nodes.

If you want to compile one adapter at a time, then use the Adapter Factory form.

See Also:

Oracle Identity Manager Tools Reference Guide for information about using the Adapter Factory and Adapter Manager forms

To view detailed information about an adapter:

1. Highlight the adapter in the Adapter Manager form.

2. Double-click the row header of the adapter, or right-click the adapter.

3. Select Launch Adapter from the shortcut menu that is displayed. Details of the adapter are displayed.

3.2.2 Adding Custom Attributes for Provisioning

Note:

In this section, the term "attribute" refers to the identity data fields that store user data.

By default, the attributes listed in the "Provisioning Module" section are mapped for provisioning between Oracle Identity Manager and the target system. If required, you can map additional attributes for provisioning as follows:

See Also:

Oracle Identity Manager Design Console Guide

1. Modify the attribute entries in the following file:

   For the AIX platform:

   OIM_HOME/xellerate/XLIntegrations/SSH/config/userAttribute_AIX_prov.properties
   

   For non-AIX platforms:

   OIM_HOME/xellerate/XLIntegrations/SSH/config/userAttribute_NonAIX_prov.properties
   

   If required, you can add new attributes in this file. The format that you must use is as follows:

   OimAttributeName=TargetAttributeName
   

   For example:

   homeDir=-d
   

2. Add a new column in the process form.

   Note:

   If you have already performed Step 4 of the "Adding Custom Attributes for Reconciliation" section, then directly proceed to Step 3.

   1. Open the process form. This form is in the Development Tools folder of the Oracle Identity Manager Design Console.

   2. Click Create New Version.

   3. In the Create a New Version dialog box, specify the version name in the Label field, save the changes, and then close the dialog box.

   4. From the Current Version list, select the newly created version.

   5. On the Additional Columns tab, click Add.

   6. Specify the new field name and other values.

   7. Click Make Version Active and save the changes.

3. Add a new variable in the variable list.

   1. Open the Adapter Factory form. This form is in the Development Tools folder of the Oracle Identity Manager Design Console.

   2. Click the Query for Records icon.

   3. On the Adapter Factory Table tab, double-click the adpSSHCREATEUSER adapter from the list.

   4. On the Variable List tab, click Add.

   5. In the Add a Variable dialog box, specify the required values and then save and close the dialog box.

4. Define an additional adapter task for the newly added variable in the adpSSHCREATEUSER adapter.

   1. On the Adapter Tasks tab of the Adapter Factory form, click Add.

   2. In the Adapter Task Selection dialog box, select Functional Task, select Java from the list of functional task types, and then click Continue.

   3. In the Object Instance Selection dialog box, select Persistent Instance and then click Continue.

   4. In the Add an Adapter Factory Task dialog box, specify the task name, select the setProperty method from the Method list, and then click Save.

   5. Map the application method parameters, and then save and close the dialog box. To map the application method parameters:

      For the "Output: String Return variable (Adapter Variable)" parameter:

      i. From the Map to list, select Literal.

      ii. From the Name list, select Return variable.

      For the "Input: String input (Adapter Variable)" parameter:

      i. From the Map to list, select Adapter Variables.

      ii. From the Name list, select Input.

      For the "Input: String (Literal)" parameter:

      i. From the Map to list, select Literal.

      ii. From the Name list, select String.

      iii. In the Value field, specify the name that is to the left of the equal sign in the line that you uncomment or add while performing Step 1.For example, if you uncomment the homeDir=-d line in Step 1, then you must specify homeDir as the attribute name.

      For the "Input: String (Adapter Variable)" parameter:

      i. From the Map to list, select Adapter Variables.

      ii. From the Name list, select the newly added adapter variable.

   6. Repeat Steps b through g to create more adapter tasks.

5. Create an additional adapter task to set the input variable.

   1. Open the Adapter Factory form. This form is in the Development Tools folder in the Oracle Identity Manager Design Console.

   2. On the Adapter Tasks tab, click Add.

   3. In the Adapter Task Selection dialog box, select Logic Task, select SET VARIABLE from the list, and then click Continue.

   4. In the Edit Set Variable Task Parameters dialog box, select input from the Variable Name list, select Adapter Task from the Operand Type list, and the Operand Qualifier as the Adapter Task that you have created in the previous step. Then, click Save.

6. Map the process form columns and adapter variables for the Create User process task as follows:

   1. Open the Process Definition form. This form is in the Process Management folder of the Design Console.

   2. Click the Query for Records icon.

   3. On the Process Definition Table tab, double-click the SSH User process.

   4. On the Tasks tab, double-click the Create User task.

   5. In the Closing Form dialog box, click Yes.

   6. On the Integration tab of the Editing Task Columns Create User dialog box, map the unmapped variables, and then save and close the dialog box. To map an unmapped variable:

      i. Double-click the row in which N is displayed in the Status column. The value N signifies that the variable is not mapped.

      ii. From the Map to list in the Edit Data Mapping for Variables dialog box, select Process Data.

      iii. From the Qualifier list, select the name of the variable.

      Repeat Steps i through iii for all unmapped variables.

Repeat Steps 1 through 6 if you want to add more attributes.

3.3 Configuring the Connector for Multiple Installations of the Target System

Note:

Perform this procedure only if you want to configure the connector for multiple installations of the target system.

You may want to configure the connector for multiple installations of the target system. The following example illustrates this requirement:

The Tokyo, London, and New York offices of Example Multinational Inc. have their own installations of the target system. The company has recently installed Oracle Identity Manager, and they want to configure Oracle Identity Manager to link all the installations of the target system.

To meet the requirement posed by such a scenario, you must configure the connector for multiple installations of the target system.

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

See Also:

Oracle Identity Manager Design Console Guide for detailed instructions on performing each step of this procedure

1. Create and configure one IT resource for each target system installation.

   The IT Resources form is in the Resource Management folder. An IT resource is created when you import the connector XML file. You can use this IT resource as the template for creating the remaining IT resources, of the same resource type.

2. Configure reconciliation for each target system installation. Refer to the "Configuring Reconciliation" section for instructions. Note that you only need to modify the attributes that are used to specify the IT resource and to specify whether or not the target system installation is to be set up as a trusted source.

3. If required, modify the fields to be reconciled for the Xellerate User resource object.

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

3.4 Transforming Data Reconciled Into Oracle Identity Manager

This section discusses the TransformLookupName and UseTransformMapping attributes of the scheduled tasks for target resource and trusted source reconciliation, SSH User Target Resource Reconciliation Task and SSH User Trusted Source Reconciliation Task.

During reconciliation, you may want to transform the values of some target system fields before they are stored in Oracle Identity Manager. Appending a number at the end of the user ID is an example of a data transformation.

The TransformLookupName and UseTransformMapping attributes provide a method for implementing such transformations. To use these attributes

1. Identify the fields that you want to transform.

2. Create the Java file containing the code implementation of the transformation that must be performed during reconciliation. See Appendix C, "Sample Transformation Class" for information about creating a transformation class.

3. Compile the Java file. While compiling the file, you must reference the xliSSH.jar file in the OIM_HOME/xellerate/ScheduleTask directory.

4. Create JAR files containing the code to implement the required transformations on the fields.

5. Copy the JAR files into the following directory:

   OIM_HOME/xellerate/ScheduleTask

6. In the Lookup.Reconciliation.TransformationMap lookup definition, add an entry for the transformation. In the Code Key column, enter the name of the reconciliation field (in the resource object) on which you want the transformation to be performed. In the Decode column, enter the name of the class file. For example:

   Note:

   You can use this lookup definition for both UNIX SSH and SSH Telnet.

   Code Key: First Name

   Decode: AppendNumber

   See Also:

   Oracle Identity Manager Design Console Guide for information about creating lookup definitions

7. While configuring the SSH User Target Resource Reconciliation Task and SSH User Trusted Source Reconciliation Task scheduled tasks by performing the procedure described in "Scheduled Tasks for Trusted Source and Target Resource Reconciliation":

   • Enter the name of the lookup definition as the value of the TransformLookupName attribute.

   • Enter Yes as the value of the UseTransformMapping attribute to specify that you want transformations to be applied. If you enter No as the value, then the transformations are not applied.