Skip Headers
Oracle® Identity Manager Connector Guide for IBM RACF Advanced
Release 9.0.4

Part Number E10451-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

2 Connector Deployment on Oracle Identity Manager

The following sections of this chapter describe the procedure to deploy the LDAP Gateway on the Oracle Identity Manager system:

Refer to the following section if you want to configure the connector for multiple installations of the target system:

See Also:

Chapter 3, "Connector Deployment on IBM RACF" for the procedure to deploy the Reconciliation Agent and Provisioning Agent on the mainframe

Files and Directories That Comprise the Connector

Table 2-1 describes the contents of the connector installation media.

Table 2-1 Files and Directories That Comprise the Connector

Files and Directories Description

etc/LDAP Gateway/ldapgateway.zip

Files required for LDAP Gateway deployment on the Oracle Identity Manager system

etc/Provisioning and Reconciliation Connector/Mainframe_RACF.zip

Files required for the installation of the Reconciliation Agent and Provisioning Agent on the target system

lib/idm.jar

The connector JAR file to be deployed on the Oracle Identity Manager system

lib/racf-adv-agent-recon.jar

lib/racfConnection.properties

Files required for real-time reconciliation between the target system and Oracle Identity Manager

Files in the resources directory

Each of these resource bundles contains locale-specific information that is used by the connector

Note: A resource bundle is a file containing localized versions of the text strings that are displayed on the user interface of Oracle Identity Manager. These text strings include GUI element labels and messages displayed on the Administrative and User Console.

scripts/run_initial_recon_provisioning.bat

scripts/run_initial_recon_provisioning.sh

Files that are used to perform first-time (initial) reconciliation with Oracle Identity Manager

scripts/initialRacfAdv.properties

scripts/racf-adv-initial-recon.jar

Files that are used during the initial reconciliation run

scripts/user.txt

Sample of the file containing user data that is used during initial reconciliationThis file is discussed in detail in "Running Initial Reconciliation".

xml/oimRacfAdvConnector.xml

The XML file that contains component definitions for the connector

xml/racfTrustedXellerateUser.xml

The XML file that contains definitions of the connector components that are used for trusted source reconciliation


Copying the Connector Files

Copy the following connector files to the specified destination directories on the Oracle Identity Manager system:

Note:

Do not copy the files that are not listed in this table. Those files are used later in the deployment procedure. See "Files and Directories That Comprise the Connector" for more information about the following files.

Table 2-2 Copying the Connector Files

Files Destination Directory

etc/LDAP Gateway/ldapgateway.zip

LDAP_INSTALL_DIR

This is the directory on the Oracle Identity Manager system where you want to install the LDAP Gateway. See "Installing and Configuring the LDAP Gateway" for information about installing the LDAP Gateway.

lib/racf-adv-agent-recon.jar

lib/racfConnection.properties

LDAP_INSTALL_DIR/etc

lib/idm.jar

scripts/initialRacfAdv.properties

scripts/run_initial_recon_provisioning.sh

scripts/run_initial_recon_provisioning.bat

scripts/racf-adv-initial-recon.jar

OIM_HOME/xellerate/JavaTasks

Files in the resources directory

OIM_HOME/xellerate/connectorResources

xml/oimRacfAdvConnector.xml

xml/racfTrustedXellerateUser.xml

OIM_HOME/xellerate/XLIntegrations/racf/xml


Configuring Oracle Identity Manager

Configuring Oracle Identity Manager involves the following procedures:

Note:

In a clustered environment, you must perform these steps on each node of the cluster.

Clearing Content Related to Connector Resource Bundles from the Server Cache

When you deploy the connector, the resource bundles are copied from the resources directory on the installation media into the OIM_HOME/xellerate/connectorResources directory. Whenever you add a new resource bundle in 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, change to the OIM_HOME/xellerate/bin directory.

    Note:

    You must perform Step 1 before you perform Step 2. An exception is thrown if you run the command described in Step 2 as follows:
    OIM_HOME/xellerate/bin/BATCH_FILE_NAME
    
  2. Enter one of the following commands:

    • On Microsoft Windows:

      PurgeCache.bat ConnectorResourceBundle
      
    • On UNIX:

      PurgeCache.sh ConnectorResourceBundle
      

    Note:

    You can ignore the exception that is thrown when you perform Step 2. This exception is different from the one mentioned in Step 1.

    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
    

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 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 may 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:

  • BEA WebLogic Server

    To enable logging:

    1. Add the following line in the OIM_HOME/xellerate/config/log.properties file:

      log4j.logger.COM.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS=LOG_LEVEL
      
    2. In this line, replace LOG_LEVEL with the log level that you want to set.

      For example:

      log4j.logger.COM.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS=INFO
      

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

    WEBLOGIC_HOME/user_projects/domains/DOMAIN_NAME/SERVERr_NAME/SERVER_NAME.log
    
  • IBM WebSphere Application Server

    To enable logging:

    1. Add the following line in the OIM_HOME/xellerate/config/log.properties file:

      log4j.logger.COM.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS=LOG_LEVEL
      
    2. In this line, replace LOG_LEVEL with the log level that you want to set.

      For example:

      log4j.logger.COM.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS=INFO
      

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

    WEBSPHERE_HOME/AppServer/logs/SERVER_NAME/startServer.log
    
  • JBoss Application Server

    To enable logging:

    1. In the JBOSS_HOME/server/default/conf/log4j.xml file, locate or add the following lines:

      <category name="COM.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS">
         <priority value="LOG_LEVEL"/>
      </category>
      
    2. In the second XML line, replace LOG_LEVEL with the log level that you want to set. For example:

      <category name="COM.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS">
         <priority value="INFO"/>
      </category>
      

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

    JBOSS_HOME/server/default/log/server.log
    
  • Oracle Application Server

    To enable logging:

    1. Add the following line in the OIM_HOME/xellerate/config/log.properties file:

      log4j.logger.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS=LOG_LEVEL
      
    2. In this line, replace LOG_LEVEL with the log level that you want to set.

      For example:

      log4j.logger.IDENTITYFORGE.ORACLE.INTEGRATION.IDFUSEROPERATIONS=INFO
      

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

    OAS_HOME/opmn/logs/default_group~home~default_group~1.log
    

Importing the Connector XML File

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

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

  4. Locate and open the oimRacfAdvConnector.xml file, which is in the OIM_HOME/xellerate/XLIntegrations/racf/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 a new instance of the OIMLDAPGatewayResourceType IT resource type is displayed.

  8. Create an IT resource based on the OIMLDAPGatewayResourceType IT resource type. Refer to "Defining the IT Resource" for information about the parameters for which you must specify values.

  9. Click Next. The Provide IT Resource Instance Data page for a new instance of the OIMLDAPGatewayResourceType 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.

  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. These nodes represent Oracle Identity Manager entities that are redundant. Before you import the connector XML file, you must remove these entities by right-clicking each node and then selecting Remove.

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

Defining the IT Resource

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

Parameter Description
AtMap User 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.

idfPrincipalDn The administrator ID for connecting to the LDAP Gateway

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

idfPrincipalPwd The administrator password for connecting to the LDAP Gateway
idfRootContext The root context for IBM RACF

Value: dc=racf,dc=com

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

idfServerHost Host name for connecting to the LDAP Gateway

Value: localhost

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

idfServerPort The port for connecting to the LDAP Gateway

Sample value: 5389


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

Compiling Adapters

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

You must compile these adapters.

To compile adapters by using the Adapter Manager form:

  1. Open the Adapter Manager form.

  2. To compile all the adapters that you have imported into the current database, click Compile All.

    If you have created your own adapters or if a new adapter is shipped with a patch that you installed, then you might need to compile one adapter at a time. To compile multiple (but not all) adapters, select the adapters you want to compile. Then, click Compile Selected.

  3. Click Start. Oracle Identity Manager compiles the adapters that you specify.

  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.

Installing and Configuring the LDAP Gateway

To install and configure the LDAP Gateway:

  1. Extract the contents of the ldapgateway.zip file to a directory on the same server as Oracle Identity Manager. In this document, the location (and name) of the ldapgateway directory is referred to as LDAP_INSTALL_DIR.

  2. In a text editor, open the racf.properties file. This file is located in the LDAP_INSTALL_DIR/conf directory. In this file, specify information for the following properties of the TCP/IP message transport layer:

    The default values are as follows. You can change these values.

    _type_=socket
    _isencrypted_=true
    _timeout_=5000
    _authretries_=2
    _host_=HOST_NAME_OR_IP_ADDRESS_OF_MAINFRAME
    _port_=5790
    _agentport_=5190 
    

    Note:

    If you are configuring the LDAP Gateway in the same server as Oracle Identity Manager, then specify localhost as the value of the _host_ property. If you are configuring the LDAP Gateway in a different server than Oracle Identity Manager, then specify the host name or IP address of the server as the value of the _host_ property. However, Oracle recommends that the LDAP Gateway be installed in the same server as Oracle Identity Manager.
  3. In the racf.properties file, use the following property to specify whether you want to revoke access rights or delete users during Disable User provisioning operations:

    # DEFAULT ACTION WHEN DELETE FUNCTION USED
    _defaultDelete_=delete
    

    Set revoke as the value of this property if you want the user to be disabled on the target system as the outcome of a Delete User provisioning operation.

    Set delete as the value of this property if you want the user to be deleted from the target system as the outcome of a Delete User provisioning operation.

  4. In the racf.properties file, use the _nameFormat_ property to specify the format of the Full Name attribute.

    You can use the following as the components of the format that you specify:

    • Use fn to represent the first name.

    • Use sp to represent the space character.

    • Use ln to represent the last name.

    • Use a comma (,) to represent the comma.

    • Use a period (.) to represent the period.

    • Use the vertical bar (|) as the separator for the other components.

    The following line shows a sample value for the _nameFormat_ property:

    _nameFormat_=fn|sp|ln

  5. Open the LDAP_INSTALL_DIR/etc/racfConnection.properties file and edit the following property:

    Note:

    You must also make this change in the initialRacfAdv.properties file, which is in the OIM_HOME/xellerate/JavaTasks directory.
    _itResource_=NAME_OF_THE_NEW_IT_RESOURCE
    

    Replace NAME_OF_THE_NEW_IT_RESOURCE with the name of the IT resource that you create by performing Step 8 of the procedure described in "Importing the Connector XML File".

  6. From the LDAP_INSTALL_DIR/dist/idfserver.jar file, extract the beans.xml file, open it in an editor, and set values for the following:

    • Target system administrator credentials

      You must change the administrator credentials stored in the following lines of the beans.xml file:

      Note:

      In these lines, the values that you can change are highlighted in bold font. The values that you enter in the beans.xml file must be the same as the values that you specify for the IT resource parameters and the properties in the racfConnection.properties and initialRacfAdv.properties files.
      <property name="adminUserDN" value="cn=ximRACFAdmin,dc=RACF,dc=com"/>
      <property name="adminUserPassword" value="ximRACFPwd"/>
      
    • Port used for communication between the LDAP Gateway and the mainframe LPAR that you use for the connector installation

      The default value of the port property is 5389. If you want to change this value, then edit the value of the port property defined in the beans.xml file:

      <property name="port" value="5389"/>
      
  7. To enable logging on the LDAP Gateway server:

    1. Extract the log4j.properties file from the LDAP_INSTALL_DIR/dist/idfserver.jar file.

    2. Ensure that the log4j.rootLogger variable is set to the following:

      log4j.rootLogger=DEBUG, A1
      
    3. Save and close the file.

    When you use the connector, the following LDAP Gateway log files are generated in the LDAP_INSTALL_DIR/logs directory:

    • idfserver.log.0: This is the main log file.

    • topsecret-agent-recon.log: This is ongoing reconciliation log file that stores Oracle Identity Manager reconciliation messages.

    • topsagent.log.0: This file is currently redundant, and it will be removed in a later release.

  8. Save the changes made to the beans.xml file, and then re-create the idfserver.jar file.

Note:

When you start using the connector, the logs for the LDAP Gateway are created in the LDAP_INSTALL_DIR/logs directory.

Configuring the Connector to Work with the Oracle Identity Manager Application Server

To ensure that the connector works with the application server that Oracle Identity Manager is deployed on:

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

    • Open the run script from the LDAP_INSTALL_DIR/bin directory.

    • Open the run_initial_recon_provisioning script from the OIM_HOME/Xellerate/JavaTasks directory.

  2. In the run and run_initial_recon_provisioning scripts, uncomment the lines related to the specific application server that you are using. In addition, change the paths to reflect the actual location of the application server directory.

    The following are the contents of the run.sh file:

    Note:

    The contents of the run_initial_recon_provisioning script are similar. You must make the same change in that script.
    SET CLASSPATH VARIABLES
    ##### SET ENVIRONMENT VARIABLES #######
    APP_HOME=/opt/ldapgateway
    TMPDIR=/opt/ldapgateway/temp
    OIM_HOME=/opt/OIM/xellerate
    OIM_CLIENT_LIB=/opt/OIM/client/xlclient/lib
     
    ##### SET JBOSS HOME ##################
    # APPSERVER_HOME=/opt/ldapgateway/lib/jboss-4.0.2
     
    ##### SET WEBSPHERE HOME ##################
    #APPSERVER_HOME=/opt/WebSphere/AppServer/lib
     
    ##### SET WEBLOGIC HOME ##################
    # APPSERVER_HOME=/opt/bea/
     
    ##### SET OC4J HOME ##################
    #APPSERVER_HOME=/opt/oracle/oc4j
    

    In the run.sh file, the lines starting with a number sign (#) are comments. To uncomment the line, remove the number sign. For example, to ensure that the connector works with JBoss Application Server, uncomment the following line:

    ##### SET JBOSS HOME ##################
    APPSERVER_HOME=/opt/ldapgateway/lib/jboss-4.0.2
    
  3. If you are using IBM WebSphere Application Server 6.1, then add the com.ibm.ws.wccm_6.1.0.jar file to the CLASSPATH variable in the run and run_initial_recon_provisioning scripts as shown in the following example:

    rem
    rem SET WEBSPHERE APPLICATION SERVER REQUIRED LIBRARIES
    rem
    set CLASSPATH=%CLASSPATH%;"%APPSERVER_HOME%"\lib\com.ibm.ws.wccm_6.1.0.jar
    

Configuring the Connector for 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 each installation of the target system.
  1. Create an IT resource based on the OIMLDAPGatewayResourceType IT resource type.

    Refer to Oracle Identity Manager Design Console Guide for information about creating IT resources. Refer to "Defining the IT Resource" 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>
    

    If you change the port number, then 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 bean.xml file.

  6. Open the LDAP_INSTALL_DIR/conf/racf.properties file and edit the following parameters:

    • _host_=IP_ADDRESS_OR_HOST_NAME_OF_THE_MAINFRAME

    • _port_=PORT_OF_THE_SECOND_INSTANCE_OF_THE_PROVISIONING_AGENT

    • _agentPort_=PORT_OF_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 IBM RACF running on each server.
  7. Open the LDAP_INSTALL_DIR/etc/racfConnection.properties file and edit the following property:

    _itResource_=NAME_OF_THE_NEW_IT_RESOURCE