1. Connector Guide for IBM RACF Advanced
  2. IBM RACF Connector Deployment on Oracle Identity Manager

3 IBM RACF Connector Deployment on Oracle Identity Manager

The LDAP Gateway acts as the intermediary between Oracle Identity Manager and the connector components on the mainframe. The following sections of this chapter describe the procedure to deploy some components of the connector, including the LDAP Gateway, on the Oracle Identity Manager host computer:

Note:

The procedure to deploy the mainframe components of the connector is described in the next chapter.

3.1 Running the Connector Installer

Perform the following steps to run the Connector Installer:

  1. Ensure you have downloaded the connector installation package from the OTN website at http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/connectors-101674.html and extracted its contents.

  2. Copy the contents of the connector installation package into the following directory:

    OIM_HOME/server/ConnectorDefaultDirectory

  3. Log in to Oracle Identity System Administration.

  4. In the left pane, under Provisioning Configuration, click Manage Connector.

  5. In the Manage Connector page, click Install.

  6. From the Connector list, select IBM RACF Advanced RELEASE_NUMBER. This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory in Step 2.

    If you have copied the installation files into a different directory, then:

    1. In the Alternative Directory field, enter the full path and name of that directory.

    2. To repopulate the list of connectors in the Connector list, click Refresh.

    3. From the Connector list, select IBM RACF Advanced RELEASE_NUMBER.

  7. Click Load.

  8. To start the installation process, click Continue. In a sequence, the following tasks are automatically performed:

    1. Configuration of connector libraries.

    2. Import of the connector Target Resource user configuration XML file (by using the Deployment Manager).

    3. Compilation of adapters.

    On successful completion of a task, a check mark is displayed for the task. If a task fails, then an X mark and a message stating the reason for failure are displayed. If a task fails, make the required correction and then perform one of the following steps:

    • Retry the installation by clicking Retry.

    • Cancel the installation and begin again from Step 2.

  9. If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed.

  10. Click Exit to close the installation page.

When you run the Connector Installer, it copies the connector files and external code files to destination directories on the Oracle Identity Manager host computer. These files are listed in Files and Directories in the IBM RACF Advanced Connector Package.

3.2 Configuring the IT Resource

You must specify values for the parameters of the RacfResource IT resource as follows:

  1. Log in to the Oracle Identity System Administration.

  2. In the left pane, under Configuration, click IT Resource.

  3. In the IT Resource Name field on the Manage IT Resource page, enter RacfResource and then click Search.

  4. Click the edit icon for the IT resource.

  5. From the list at the top of the page, select Details and Parameters.

  6. Specify values for the parameters of the IT resource as described in the following table:

    Table 3-1 IT Resource Parameters for IBM RACF Advanced Connector

    Parameter Description

    AtMap User

    This parameter holds the name of the lookup definition containing attribute mappings that are used for provisioning.

    Value: AtMap.RACF

    Note: You must not change the value of this parameter.

    idfBackendDn

    Enter the user ID that the connector will use to connect to the LDAP Gateway backend.

    Sample value: cn=Directory Manager,dc=system,dc=backend

    idfBackendPassword

    Enter the password of the user ID that the connector will use to connect to the LDAP Gateway backend. You also set this password in the configuration.properties file of the LDAP Gateway.

    Note: Do not enter an encrypted value.

    idfbackendContext

    Enter the root context for LDAP Gateway backend.

    Sample Value: dc=system,dc=backend

    idfConnectTimeoutMS

    Enter an integer value that specifies the number of milliseconds after which an attempt to establish a connection between the LDAP Gateway and Oracle Identity Manager times out.

    If you do not enter a value for this parameter, then the connector uses a default time out of 300000 ms (that is, 5 minutes).

    idfPrincipalDn

    Set a user ID for an account that the connector will use to connect to the LDAP Gateway.

    Format: cn=USER_ID,dc=racf,dc=com

    Sample value: cn=idfRacfAdmin,dc=racf,dc=com

    idfPrincipalPwd

    Set a password for the account that the connector will use to connect to the LDAP Gateway. You also set this password in the files listed in the description of the idfPrincipalDn parameter.

    Note: Do not enter an encrypted value.

    idfReadTimeoutMS

    Enter an integer value that specifies the number of milliseconds after which an attempt to read data from the target system times out.

    If you do not enter a value for this parameter, then the connector uses a default time out of 1800000 ms (that is, 30 minutes).

    idfRootContext

    This parameter holds the root context for IBM RACF.

    Value: dc=racf,dc=com

    Note: You must not change the value of this parameter.

    idfServerHost

    This parameter holds the host name or IP address of the computer on which you install the LDAP Gateway. For this release of the connector, you install the LDAP Gateway on the Oracle Identity Manager host computer.

    Default value: localhost

    Note: Do not change the value of this parameter unless you have installed the LDAP Gateway on a different machine from the Oracle Identity Manager host computer.

    idfServerPort

    Enter the number of the port for connecting to the LDAP Gateway.

    Sample value: 5389

    idfSsl

    This parameter determines whether the LDAP Gateway will use SSL to connect to the target system. Enter true if using SSL. Otherwise, enter false.

    Sample value: true

    idfTrustStore

    This parameter holds the directory location of the trust store containing the SSL certificate. This parameter is optional, and should only be entered when using SSL authentication. This must be the full path to the directory location.

    Sample value: /app/home/ldapgateway/conf/idf.jks

    idfTrustStorePassword

    This parameter holds the password for the SSL trust store. This parameter is optional, and should only be entered when using SSL authentication.

    idfTrustStoreType

    This parameter holds the trust store type for the SSL trust store. This parameter is optional, and should only be entered when using SSL authentication.

    Sample value: jks

    Last Modified Time Stamp

    The most recent start time of the RACF Reconcile All LDAP Users reconciliation scheduled task is stored in this parameter. See RACF Reconcile All LDAP Users for more information about this scheduled task.

    The format of the value stored in this parameter is as follows:

    MM/dd/yy hh:mm:ss a

    In this format:

    MM is the month of the year.

    dd is the day of the month.

    yy is the year.

    hh is the hour in am/pm (01-12).

    mm is the minute in the hour.

    ss is the second in the minute.

    a is the marker for AM or PM.

    Sample value: 05/07/10 02:46:52 PM

    Default value: 0

    The reconciliation task will perform full LDAP user reconciliation when the value is 0. If the value is a non-zero, standard time-stamp value in the format given above, then incremental reconciliation is performed.

    Only records that have been created or modified after the specified time stamp are brought to Oracle Identity Manager for reconciliation.

    Note: When required, you can manually enter a time-stamp value in the specified format.

  7. To save the values, click Update.

3.3 Configuring Oracle Identity Manager

Configuring Oracle Identity Manager involves the following procedures:

Note:

In an Oracle Identity Manager cluster, you must perform these steps on each node of the cluster.

3.3.1 Creating Additional Metadata, Running Entitlement, and Catalog Synchronization Jobs

You must create additional metadata, such as a UI form and an application instance. In addition, you must run entitlement and catalog synchronization jobs. These procedures are described in the following sections:

3.3.1.1 Creating and Activating a Sandbox

Create and activate a sandbox as follows:

  1. On the upper navigation bar, click Sandboxes. The Manage Sandboxes page is displayed.
  2. On the toolbar, click Create Sandbox. The Create Sandbox dialog box is displayed.
  3. In the Sandbox Name field, enter a name for the sandbox. This is a mandatory field.
  4. In the Sandbox Description field, enter a description of the sandbox. This is an optional field.
  5. Click Save and Close. A message is displayed with the sandbox name and creation label.
  6. Click OK. The sandbox is displayed in the Available Sandboxes section of the Manage Sandboxes page.
  7. From the table showing the available sandboxes in the Manage Sandboxes page, select the newly created sandbox that you want to activate.
  8. On the toolbar, click Activate Sandbox.

    The sandbox is activated.

3.3.1.2 Creating a New UI Form

Create a new UI form as follows:

  1. In the left pane, under Configuration, click Form Designer.
  2. Under Search Results, click Create.
  3. Select the resource type for which you want to create the form, for example, OIMRacfResourceObject.
  4. Enter a form name and click Create.
3.3.1.3 Creating an Application Instance

Create an application instance as follows:

  1. In the System Administration page, under Configuration in the left pane, click Application Instances.
  2. Under Search Results, click Create.
  3. Enter appropriate values for the fields displayed on the Attributes form and click Save.
  4. In the Form drop-down list, select the newly created form and click Apply.
  5. Publish the application instance to an organization to make the application instance available for requesting and subsequent provisioning to users.
3.3.1.4 Publishing a Sandbox
Before publishing a sandbox, perform the following procedure as a best practice to validate all sandbox changes made till this stage as it is difficult to revert the changes after a sandbox is published:
  1. In Identity System Administration, deactivate the sandbox.
  2. Log out of Identity System Administration.
  3. Log in to Identity Self Service using the xelsysadm user credentials and then activate the sandbox that you deactivated in Step 1.
  4. In the Catalog, ensure that the Concur application instance form appears with correct fields.
  5. Publish the sandbox. See Publishing a Sandbox in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.
3.3.1.5 Harvesting Entitlements and Sync Catalog

To harvest entitlements and sync catalog:

  1. Run the scheduled jobs for lookup field synchronization. See Scheduled Tasks for Lookup Field Synchronization for more information about these scheduled jobs.
  2. Run the Entitlement List scheduled job to populate Entitlement Assignment schema from child process form table.
  3. Run the Catalog Synchronization Job scheduled job.

See Also:

Predefined Scheduled Tasks in Oracle Fusion Middleware Administering Oracle Identity Governance for a description of the Entitlement List and Catalog Synchronization Job scheduled jobs.

3.3.1.6 Updating an Existing Application Instance with a New Form

For any changes you do in the Form Designer, you must create a new UI form and update the changes in an application instance. To update an existing application instance with a new form:

  1. Create a sandbox and activate it as described in Creating and Activating a Sandbox.
  2. Create a new UI form for the resource as described in Creating a New UI Form.
  3. Open the existing application instance.
  4. In the Form field, select the new UI form that you created.
  5. Save the application instance.
  6. Publish the sandbox as described in Publishing a Sandbox.

3.3.2 Localizing Field Labels in UI Forms

Perform the following steps to localize field labels that you add to in UI forms:

  1. Log in to Oracle Enterprise Manager.

  2. In the left pane, expand Application Deployments and then select oracle.iam.console.identity.sysadmin.ear.

  3. In the right pane, from the Application Deployment list, select MDS Configuration.

  4. On the MDS Configuration page, click Export and save the archive to the local computer.

  5. Extract the contents of the archive, and open the following file in a text editor:

    SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle.xlf

  6. Edit the BizEditorBundle.xlf file as follows:

    1. Search for the following text:

      <file source-language="en"  
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

    2. Replace with the following text:

      <file source-language="en" target-language="LANG_CODE"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

      In this text, replace LANG_CODE with the code of the language that you want to localize the form field labels. The following is a sample value for localizing the form field labels in Japanese: 

      <file source-language="en" target-language="ja"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">

    3. Search for the application instance code. The original code will be in the following format:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_<Field_Name>__c_description']}">
<source><Field_Label></source>
<target/>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.<UI_Form_Name>.entity. <UI_Form_Name>EO.UD_<Field_Name>__c_LABEL">
<source><Field_Label></source>
<target/>
</trans-unit>

      For example, the following sample code show the update that should be made for the FULL NAME field on a UI form named RacfUserFormv1:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_IDF_RACF_ADV_CN__c_description']}">
<source>FULL NAME</source>
<target/>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.RacfUserFormv1.entity.RacfUserFormv1EO.UD_IDF_RACF_ADV_CN__c_LABEL">
<source>FULL NAME</source>
<target/>
</trans-unit>

    4. Open the resource file from the /resources directory in the connector installation media, for example Racf-Adv_ja.properties, and get the value of the attribute from the file, for example global.udf.UD_IDF_RACF_ADV_CN=\u6C0F\u540D.

    5. Replace the original code shown in Step 6.c with the following:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_<Field_Name>__c_description']}">
<source>< global.udf.UD_Field_Name></source>
<target/>enter Unicode values here</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.<UI_Form_Name>.entity. <UI_Form_Name>EO.UD_<Field_Name>__c_LABEL">
<source><Field_Label></source>
<target/>enter Unicode values here</target>
</trans-unit>

      As an example, the code for FULL_NAME field translation would be:

      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_IDF_RACF_ADV_CN__c_description']}">
      <source>FULL_NAME</source>
<target>\u6C0F\u540D</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.RacfUserFormv1.entity.RacfUserFormv1EO.UD_IDF_RACF_ADV_CN__c_LABEL">
<source>FULL_NAME</source>
<target>\u6C0F\u540D</target>
</trans-unit>

    6. Repeat Steps 6.c through 6.e for all attributes of the process form.

    7. Save the file as BizEditorBundle_LANG_CODE.xlf. In this file name, replace LANG_CODE with the code of the language to which you are localizing. Sample file name: BizEditorBundle_ja.xlf.

  7. Repackage the ZIP file and import it into MDS.

  8. Log out of and log in to Oracle Identity Manager.

3.3.3 Clearing Content Related to Connector Resource Bundles from the Server Cache for Oracle Identity Manager Connector

When you deploy the connector, the resource bundles are copied from the resources directory on the installation media into Oracle Identity Manager database. Whenever you add a new resource bundle to the 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, switch to the OIM_HOME/server/bin directory.
  2. Enter one of the following commands:

    Note:

    You can use the PurgeCache utility to purge the cache for any content category. Run PurgeCache.bat CATEGORY_NAME on Microsoft Windows or PurgeCache.sh CATEGORY_NAME on UNIX. The CATEGORY_NAME argument represents the name of the content category that must be purged.

    For example, the following commands purge Metadata entries from the server cache:

    PurgeCache.bat MetaData

    PurgeCache.sh MetaData

    • On Microsoft Windows: PurgeCache.bat All

    • On UNIX: PurgeCache.sh All

    When prompted, enter the user name and password of an account belonging to the SYSTEM ADMINISTRATORS group. In addition, you are prompted to enter the service URL in the following format:

    t3://OIM_HOST_NAME:OIM_PORT_NUMBER

    In this format:

    • Replace OIM_HOST_NAME with the host name or IP address of the Oracle Identity Manager host computer.

    • Replace OIM_PORT_NUMBER with the port on which Oracle Identity Manager is listening.

3.3.4 Enabling Logging for IBM RACF Advanced Connector

The IBM RACF Advanced connector supports two forms of logging, namely LDAP gateway-level logging and Oracle Identity Manager-level logging. This section discusses the following topics:

3.3.4.1 Enabling Logging for the LDAP Gateway

LDAP Gateway logging operations are managed by the log4j2.properties file, which is located in the LDAP_INSTALL_DIR/conf/ directory. In the log4j2.properties file, edit the rootLogger log level: 

rootLogger.level = INFO

The following is a list of log levels that can be used:

  • 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 messages that highlight the progress of the application at a 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 might 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.

Multiple log files are available for use with the connector. Table 3-2 lists the name, location, and contents of each LDAP gateway log file.

Table 3-2 Log Files and their Contents

Log File Description

nohup.out

This log file contains the console window output from the LDAP Gateway. This file is primarily used in conjunction with the run.sh script (instead of the run.bat file)

Location: …/ldapgateway/bin/

idfserver.log.0

This log file contains provisioning and reconciliation logging messages from the LDAP Gateway and is the primary log file used by the gateway component.

Location: …/ldapgateway/logs/
3.3.4.2 Event Logging in Oracle Identity Manager

Oracle Identity Manager uses Oracle Java Diagnostic Logging (OJDL) for logging. OJDL is based on java.util.logger. This section contains the following topics:

Understanding the Log Levels

Configuring Logging in Oracle Identity Manager

3.3.4.2.1 Understanding the Log Levels

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:

  • ERROR:1

  • WARNING:1

  • NOTIFICATION:1

  • TRACE:1

  • TRACE:16

  • TRACE:32

Oracle Identity Manager level logging operations are managed by the logging.xml file which is located in the following directory:

DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/

Loggers are used to configure logging operations for the Oracle Identity Manager functions of the connector.

3.3.4.2.2 Configuring Logging in Oracle Identity Manager

OIM level logging operations are managed by the logging.xml file, which is located in following directory:

DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/

Loggers are used to configure logging operations for the connector's OIM functions. To configure loggers:

  1. In the text editor, open the DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/logging.xml file.
  2. Locate the logger you want to configure. If adding a logger for the first time, you must create the logger definition. Table 3-3 lists the Oracle Identity Manager loggers for this connector.

    Table 3-3 Logger Parameters

    Logger Description

    COM.IDENTITYFORGE.IDFUSEROPERATIONS

    Logs events related to provisioning operations from Oracle Identity Manager to the LDAP gateway, such as user creation and modification events.

    COM.IDENTITYFORGE.UTIL.RACF.IDFLDAPOPERATIONSIMPL

    Logs events related to basic LDAP functions, including connecting to and disconnecting from the LDAP gateway.

    COM.IDENTITYFORGE.RACF.TASKS.DELETERECONCILEOIMUSERSTASK

    Logs events related to the RACF Delete OIM Users scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.FINDALLDATASETSTASK

    Logs events related to the Find All Datasets scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.FINDALLGROUPSTASK

    Logs events related to the Find All Groups scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.FINDALLSOURCESTASK

    Logs events related to the Find All Sources scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.FINDALLSECURITYATTRIBUTESTASK

    		 Logs events related to the RACF Find All Security Attributes scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.RECONCILEALLLDAPUSERSTASK

    Logs events related to the Reconcile All LDAP Users scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.RECONCILEALLUSERSTASK

    Logs events related to the Reconcile All Users scheduled task

    COM.IDENTITYFORGE.RACF.TASKS.RECONCILEDELETEDLDAPUSERSTASK

    Logs events related to the RACF Reconcile Deleted LDAP Users scheduled task.

    COM.IDENTITYFORGE.RACF.TASKS.RECONCILEUSERSTOINTERNALLDAPTASK

    Logs events related to the RACF Reconcile Users to Internal LDAP scheduled task.
  3. Define the <logger> element and its handlers. You can use the standard odl-handler as the log handler, or write your own.

    The following is an example of a logger definition for the Reconcile All Users scheduled task:

    <logger name="COM.IDENTITYFORGE.RACF.TASKS.RECONCILEALLUSERSTASK" level='TRACE:32'>
<handler name='odl-handler'/>
</logger>

  4. Save the changes and close the file.
  5. Restart the Oracle Identity Manager server for the changes to take effect.

Log statements will be written to the path that is defined in the log handler that you assigned in the logger definition. For example, in the above logger definition for the Reconcile All Users scheduled task (in step 3), the handler is odl-handler, which has the following default output file path:

${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-diagnostic.log'