2 Deploying the Connector

Deploying the connector involves the following steps:

• Step 1: Verifying Deployment Requirements

• Step 2: Copying the Connector Files and External Code

• Step 3: Configuring the Oracle Identity Manager Server

• Step 4: Importing the Connector XML Files

• Step 5: Configuring Reconciliation

• Step 6: Compiling Adapters

If you want to configure the connector for multiple installations of RSA ClearTrust, then perform the following procedure:

• Configuring the Connector for Multiple Installations of the Target System

Step 1: Verifying Deployment Requirements

The following table lists the installation requirements for the connector.

Item	Requirement
Oracle Identity Manager	Oracle Identity Manager release 8.5.3 or later
Target systems	RSA ClearTrust 5.5 or 5.52
External code	The following files from the directory in which RSA ClearTrust is installed: ct_admin_api.jar ct_runtime_api.jar cleartrust.jar
Target system user account	RSA ClearTrust administrator account You provide the credentials of this user account while performing the procedure in the "Defining IT Resources" section.

Step 2: Copying the Connector Files and External Code

The files to be copied and the directories to which you must copy them are given in the following table.

Note:

Some of the directory paths given in the first column of this table correspond to the location of the connector files in the following directory on the installation media:

Web Access Control\RSA ClearTrust

Refer to the "Files and Directories That Comprise the Connector" section for more information about these files.

File	Destination Directory
lib\xliClearTrust.jar	OIM_home\xellerate\JavaTasks OIM_home\xellerate\ScheduleTask
Files in the resources directory on the installation media	OIM_home\xellerate\connectorResources
Files in the tests directory on the installation media	OIM_home\xellerate\tests
Files in the xml directory on the installation media	OIM_home\xellerate\XLIntegrations
The following files from the ClearTrust_installation_dir/lib directory: ct_admin_api.jar ct_runtime_api.jar cleartrust.jar	OIM_home\ThirdParty
The following files in the ClearTrust_installation_dir/lib/ directory: ct_admin_api.jar ct_runtime_api.jar	OIM_home\xellerate\ext

Note:

While installing Oracle Identity Manager in a clustered environment, you copy the contents of the installation directory to each node of the cluster. Similarly, you must copy the connectorResources directory and the JAR files to the corresponding directories on each node of the cluster.

Step 3: Configuring the Oracle Identity Manager Server

This section discusses the following topics:

Note:

In a clustered environment, you must perform this step on each node of the cluster.

• Adding a Log Module

• Changing to the Required Input Locale

• Clearing Content Related to Connector Resource Bundles from the Server Cache

• Enabling Logging

Adding a Log Module

To add a log module, in the OIM_home\config\log.properties file, add an entry similar to the following for a new log module:

log4j.logger.ADAPTERS.CTINTEGRATION=log_level

You can specify any one of the following log levels:

• DEBUG

• INFO

• WARN

• ERROR

• FATAL

Changing to the Required Input Locale

Changing to the required input locale (language and country setting) involves installing the required fonts and setting the required input locale.

To set the required input locale:

Note:

Depending on the operating system used, you may need to perform this procedure differently.

1. Open Control Panel.

2. Double-click Regional Options.

3. On the Input Locales tab of the Regional Options dialog box, add the input locale that you want to use and then switch to the input locale.

Clearing Content Related to Connector Resource Bundles from the Server Cache

Whenever you add a new resource bundle in the OIM_home\xellerate\connectorResources directory or make a change in an existing resource bundle, you must clear content related to connector resource bundles from the server cache.

To clear content related to connector resource bundles from the server cache:

1. In a command window, change to the OIM_home\xellerate\bin directory.

2. Enter one of the following commands:

   Note:

   You must perform Step 1 before you perform this step. If you run the command as follows, then an exception is thrown:

   OIM_home\xellerate\bin\batch_file_name
   

   • On Microsoft Windows:

     PurgeCache.bat ConnectorResourceBundle
     
     

   • On UNIX:

     PurgeCache.sh ConnectorResourceBundle
     
     

   In this command, ConnectorResourceBundle is one of the content categories that you can remove from the server cache. Refer to the following file for information about the other content categories:

   OIM_home\xellerate\config\xlConfig.xml
   

Note:

You can ignore the exception that is thrown when you perform Step 2.

Enabling Logging

When you enable logging, Oracle Identity Manager automatically stores in a log file information about events that occur during the course of provisioning and reconciliation operations. To specify the type of event for which you want logging to take place, you can set the log level to one of the following:

• ALL

  This level enables logging for all events.

• DEBUG

  This level enables logging of information about fine-grained events that are useful for debugging.

• INFO

  This level enables logging of informational messages that highlight the progress of the application at coarse-grained level.

• WARN

  This level enables logging of information about potentially harmful situations.

• ERROR

  This level enables logging of information about error events that may still allow the application to continue running.

• FATAL

  This level enables logging of information about very severe error events that could cause the application to stop functioning.

• OFF

  This level disables logging for all events.

The file in which you set the log level and the log file path depend on the application server that you use:

• For JBoss Application Server

  To enable logging:

  1. In the JBoss_home\server\default\conf\log4j.xml file, locate the following lines:

     <category name="XELLERATE">
        <priority value="log_level"/>
     </category>
     
     

  2. In the second XML code line, replace log_level with the log level that you want to set. For example:

     <category name="XELLERATE">
        <priority value="INFO"/>
     </category>
     
     

  After you enable logging, log information is written to the following file:

  JBoss_home\server\default\log\server.log
  
  

• For IBM WebSphere:

  To enable logging:

  1. Add the following line in the OIM_home\xellerate\config\log.properties file:

     log4j.logger.XELLERATE=log_level
     
     

  2. In this line, replace log_level with the log level that you want to set.

     For example:

     log4j.logger.XELLERATE=INFO
     
     

  After you enable logging, log information is written to the following file:

  WebSphere_home\AppServer\logs\server_name\startServer.log
  
  

• For BEA WebLogic

  To enable logging:

  1. Add the following line in the OIM_home\xellerate\config\log.properties file:

     log4j.logger.XELLERATE=log_level
     
     

  2. In this line, replace log_level with the log level that you want to set.

     For example:

     log4j.logger.XELLERATE=INFO
     
     

  After you enable logging, log information is written to the following file:

  WebLogic_home\user_projects\domains\domain_name\server_name\server_name.log
  
  

• For OC4J

  To enable logging:

  1. Add the following line in the OIM_home\xellerate\config\log.properties file:

     log4j.logger.XELLERATE=log_level
     
     

  2. In this line, replace log_level with the log level that you want to set.

     For example:

     log4j.logger.XELLERATE=INFO
     
     

  After you enable logging, log information is written to the following file:

  OC4J_home\opmn\logs\default_group~home~default_group~1.log
  

Step 4: Importing the Connector XML Files

You must import the connector XML files into Oracle Identity Manager in the following sequence:

1. XLIClearTrust_DM.xml

2. XLIClearTrustEntityAdp_DM.xml

3. XLICTAutoSaveAdapter_DM.xml

4. XLIClearTrustScheduleTask_DM.xml

Caution:

If you do not import the connector XML files in the specified order, then the connector may not work.

To import the connector XML file into Oracle Identity Manager:

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 locating files is displayed.

4. Locate and open the XLIClearTrust_DM.xml file, which is in the OIM_home\xellerate\XLIntegrations\ClearTrust\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 Next. The Provide IT Resource Instance Data page for the ClearTrust IT resource is displayed.

8. Specify values for the parameters of the ClearTrust IT resource. Refer to the table in the "Defining IT Resources" section for information about the values to be specified.

9. Click Next. The Provide IT Resource Instance Data page for a new instance of the ClearTrust IT resource type is displayed.

10. Click Skip to specify that you do not want to define another IT resource. The Confirmation page is displayed.

    See Also:

    If you want to define another IT resource, then refer to Oracle Identity Manager Tools Reference Guide for instructions.

11. Click View Selections.

    The contents of the XML file are displayed on the Import page. You may see a cross-shaped icon along with some nodes. Remove these nodes by right-clicking each node and then selecting Remove.

12. Click Import. The connector XML file is imported into Oracle Identity Manager.

13. Perform the same procedure to import the remaining connector XML files. These files are in the OIM_home\xellerate\XLIntegrations\ClearTrust\xml directory.

After you import the connector XML files, proceed to the "Step 5: Configuring Reconciliation" section.

Defining IT Resources

You must specify values for the ClearTrust IT resource parameters listed in the following table.

Parameter	Description
CTAdminUserId	Name of the RSA ClearTrust administrator This is a required parameter.
CTAdminPassword	Password of the RSA ClearTrust administrator This is a required parameter.
MachineName or IPAddress	Host name or IP address of the computer on which the RSA ClearTrust Entitlements Server is running. This is a required parameter.
Port	Port number on which the RSA ClearTrust Entitlements Server is running This is a required parameter. The default value is 5601.
SSLMode	SSL mode that is used to connect to the RSA ClearTrust server Note: Ensure that RSA ClearTrust is running in this mode. Otherwise, Oracle Identity Manager cannot connect to RSA ClearTrust. This is a required parameter. Note: It is recommended that you enable SSL to secure communication with the target system.
TimeOut	Timeout value for the connection that is established between Oracle Identity Manager and RSA ClearTrust This is a required parameter.
Default User Group	Default user group in RSA ClearTrust This is a required parameter.
CaFileLocation	Location of the CA certificate This parameter is used only with mutual authentication.
CaPassword	Password for the CA certificate This parameter is used only with mutual authentication.
KsFileLocation	Location of the keystore file This parameter is used only with mutual authentication.
KsPassword	Password of the keystore file This parameter is used only with mutual authentication.
KeyAlias	Key name that is to be used with the keystore file This parameter is used only with mutual authentication.
PrivatePassword	Password for the private key in the keystore file This parameter is used only with mutual authentication.
TimeStamp	This parameter is reserved for future use.
CTAdmin Group	Group to which the RSA ClearTrust administrative user belongs
CTAdmin Role	Role of the RSA ClearTrust administrative user
Target Locale: Country	Country code Default value: US Note: You must specify the value in uppercase.
Target Locale: Language	Language code Default value: en Note: You must specify the value in lowercase.

After you specify values for these IT resource parameters, proceed to Step 9 of the procedure to import connector XML files.

Step 5: Configuring Reconciliation

This section discusses the following topics:

• Adding Prerequisites for Reconciliation

• Creating Scheduled Tasks

• Enabling Reconciliation in Oracle Identity Manager Release 9.0.1

Adding Prerequisites for Reconciliation

This section describes the following prerequisite steps for configuring reconciliation:

• Configuring System Properties

• Configuring Trusted Source Reconciliation

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.

Configuring Trusted Source Reconciliation

Note:

Perform this step of the procedure only if you want to configure trusted source reconciliation. Only one connector can be configured for trusted source reconciliation. If you configure trusted source reconciliation for this connector while you have another trusted source configured, then both connector reconciliations would stop working.

Refer to Oracle Identity Manager Connector Framework Guide for conceptual information about reconciliation configurations.

This procedure involves the following steps:

1. In the Oracle Identity Manager Design Console, open the Resource Object form.

2. Search for the Xellerate User.

3. On the Object Reconciliation tab, add reconciliation fields as required. Add all those reconciliation fields that would be needed to provide input for the mandatory fields in the Xellerate User form, such as User Login and First Name. However, you can ignore the Password field, although it is a mandatory field.

4. Open the Process Definition form.

5. Search for the Xellerate User.

6. On the Reconciliation Field Mappings tab, add the required reconciliation field mappings. All the mandatory fields of the User Defined process form must be mapped.

7. Open the Reconciliation Rules form.

8. Create a rule for the Xellerate User object, with a rule element as required. The Reconciliation Rules form is in the Development Tools folder.

9. After you create the rule, select the Active check box.

Creating Scheduled Tasks

To create the 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 task 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, set 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 attributes of the scheduled task. Refer to the following table for information about the values to be specified.

   Attribute	Description	Sample Value
   Server	Name of the IT Resource	ClearTrust
   Target System CT Recon - Resource Object name	Name of the target system parent resource object	ClearTrust
   Trusted Source Recon - Resource Object name	Name of the Oracle Identity Manager resource object	The default value is Xellerate User
   Paging Range	Paging range to extract user accounts from the target system	10
   TrialRecNum	Use this parameter if you only want to check connectivity with the target and reconcile a few records to ensure that reconciliation with the relevant target is working. Specify the number of records that you want to reconcile as the value of this parameter.	3
   UseReconFieldMap	If this attribute is set to true, the Client Customize reconciliation is activated and only the fields in the Attribute Name: CTReconciliationFields lookup are reconciled. Otherwise, all the available fields are reconciled.	True
   CTReconciliationFields	Name of the lookup definition that stores the reconciliation field data used in customized reconciliation	Lookup.CTReconciliation.FieldMap
   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
   Date Format	Format in which date values sent from the target system are to be saved during reconciliation The value that you specify must be the same as the value specified in the "Configuring System Properties" section.	yyyy/MM/dd hh:mm:ss z

   
   

   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.

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

Step 6: Compiling Adapters

The following adapters are imported into Oracle Identity Manager when you import the connector XML file:

• CTUpdateUserProperty

• CTUpdateGroup

• CTStringTask

• CTModifyUser

• CTDeleteUser

• CTDeleteGroup

• CTCreateUser

• CTAssign Default Group

• CTAddGroup

• CTPrepopStartDate

• CTPrepopString

• CTPrepopDateAddOneYear

• CTEmailValidation

• CTAdd Default Group to User

• CTEndOrPwdExpDateValidatio

You must compile these adapters before you can use them to provision accounts on the target system.

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.

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.

Note:

To compile one adapter at a time, use the Adapter Factory form. Refer to Oracle Identity Manager Tools Reference Guide for information about using the Adapter Factory and Adapter Manager forms.

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 RSA ClearTrust. Refer to Oracle Identity Manager Design Console Guide for detailed instructions on performing each step of this procedure.

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

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 "Step 5: Configuring Reconciliation" section for instructions. Note that you need to modify only 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.

   You can designate either a single or multiple installations of RSA ClearTrust as the 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 RSA ClearTrust installation to which you want to provision the user.