21 Installing and Configuring a Remote Manager

This chapter describes how to configure the remote manager in the following topics:

• Overview of the Remote Manager Configuration

• Configuring the Remote Manager

• Stopping and Starting the Remote Manager

• Troubleshooting Remote Manager

21.1 Overview of the Remote Manager Configuration

While performing provisioning or reconciliation actions, Oracle Identity Manager must communicate with the target to perform the business operations. To do so, Oracle Identity Manager uses the target APIs to directly communicate with the target during provisioning and reconciliation. However, Oracle Identity Manager cannot directly communicate with the target in some instances, such as:

• The target is behind a firewall, and the target communication port is not exposed.

• The target does not provide APIs that can be invoked over the network.

• The target APIs cannot be invoked over a secure connection.

In these instances, instead of directly communicating with the target system, Oracle Identity Manager must use an Oracle Identity Manager component that acts like a proxy. This component is known as remote manager.

The remote manager is used for:

• Invoking non-remotable target APIs through Oracle Identity Manager

• Invoking target APIs that do not support SSL over secure channel

21.2 Configuring the Remote Manager

Remote manager configuration consists of the following steps:

1. Install the remote manager. See Oracle Fusion Middleware Installation Guide for Oracle Identity Management for information about installing the remote manager.

2. Establish trust relationship with remote manager and Oracle Identity Manager. See "Adding the Trust Relation" and "Configuring the Remote Manager by Using Your Own Certificate" for details.

3. Test the remote manager. See "Testing the Remote Manager Connection" for details.

This section contains the following topics:

• Adding the Trust Relation

• Configuring the Remote Manager by Using Your Own Certificate

• Testing the Remote Manager Connection

• Updating the xlconfig.xml File to Change the Port for Remote Manager

21.2.1 Adding the Trust Relation

The remote manager and Oracle Identity Manager communicate by using SSL. You must enable a trust relationship between Oracle Identity Manager and the remote manager.

Oracle Identity Manager must trust the remote manager certificate. To achieve this, you must import the remote manager certificate into the Oracle Identity Manager keystore and set it up as a trusted certificate.

If required, you can also enable client-side authentication in which the remote manager trusts the server certificate. For client-side authentication, import the certificate for Oracle Identity Manager into the remote manager keystore and set it up as a trusted certificate.

You might have to manually edit the configuration file (xlconfig.xml) associated with Oracle Identity Manager and the remote manager.

Perform the following steps to ensure that the trust relation between the application server and the remote manager is established through the certificate. The keytool utility is used to import/export the certificates.

1. Using a command prompt, navigate to the XLREMOTE_HOME directory and use the keytool utility to list the certificate fingerprints.

2. Enter the following command:

   $JAVA_HOME/jre/bin/keytool -list -keystore ./config/default-keystore.jks
   

   Note:

   The Oracle Identity Manager keystore is called default-keystore.jks. In Oracle Identity Manager, it is located in the $DOMAIN_HOME/config/fmwconfig/ directory.

   For the remote manager, the keystore is located in the $XLREMOTE_HOME/config/ directory. The keystore name is default-keystore.jks.

   On running the keytool command shown in this step, you will be prompted to enter the default password for the keystore. When you enter the keystore password, the entries in the keystore along with their certificate fingerprints (MD5 hashes) are displayed, as follows:

   Enter the default password for xellerate keystore: KEYSTORE_PASSWORD
   Your keystore contains 1 entry
   xell, Jan 7, 2005, keyEntry,
   Certificate fingerprint (MD5):
   B0:F2:33:C8:69:E4:25:A3:CB:59:E8:51:27:EE:5C:52
   

   The certificate fingerprint is marked in bold. This is used to uniquely identify the certificate in the keystore.

3. To establish a trust relationship between Oracle Identity Manager and the remote manager:

   1. Copy the remote manager certificate to the server computer. On the remote manager computer, locate the XLREMOTE_HOME/xlremote/config/xlserver.cert file, and copy it to the server computer.

   2. Open a command prompt on the server computer.

   3. To import the certificate by using the keytool utility, use the following command:

      $JAVA_HOME\jre\bin\keytool -import -alias rm_trusted_cert -file RM_CERT_LOCATION\xlserver.cert -trustcacerts -keystore $DOMAIN_HOME\config\fmwconfig\default-keystore.jks -storepass KEYSTORE_PASSWORD
      

      JAVA_HOME is the location of the Java directory for the application server, the value of alias is the name for the certificate in the store, and RM_CERT_LOCATION is the location in which you copied the certificate.

   4. Enter Y at the prompt to trust the certificate.

   5. On to the remote manager computer, in a text editor, open the $XLREMOTE_HOME/xlremote/config/xlconfig.xml file.

   6. Locate the <RMIOverSSL> property and ensure that the value is set to true, for example:

      <RMIOverSSL>true</RMIOverSSL>
      

   7. Locate the <KeyManagerFactory> property. If you are using the IBM JRE, then set the value to IBMX509. For example:

      <KeyManagerFactory>IBMX509</KeyManagerFactory>
      

      For all other JREs, set the value to SUNX509. For example:

      <KeyManagerFactory>SUNX509</KeyManagerFactory>
      

   8. Save the file.

      Note:

      The server certificate in OIM_HOME is also named xlserver.cert. Ensure that you do not overwrite that certificate.

   9. Restart Oracle Identity Manager.

21.2.2 Configuring the Remote Manager by Using Your Own Certificate

When the remote manager is installed, the installer generates a keypair and certificate with some default parameters, such as key password, certificate expiration time, and CN. However, you might need to change some of the parameters because of business security requirements. As a result, you need to generate and use a keypair and certificate, instead of the default certificates that are installed.

To configure the remote manager by using your own certificate on the remote manager server:

Note:

Perform the procedure given in this section only if you want to use your own certificate instead of the default Oracle Identity Manager certificates. Otherwise, skip this section.

1. Generate a new custom keystore and certificate. To do so, use the keytool utility, as shown in the following example:

   keytool-genkeypair -keystore test.jks -alias rmcert -storepass welcome1 -keyalg DSA -keysize 1024 -dname "CN=TestUser, OU=fmw, O=Oracle, C=US" -keypass PASSWORD -validity 3650
   

   Note the password that you use for the new keystore.

2. Copy the new keystore to the $XLREMOTE_HOME/config/ directory.

3. In a text editor, open the $REMOTE_MANAGER/config/xlconfig.xml file.

4. Locate the <RMSecurity> tag and change the value in the <Location> and <Password> tags as follows:

   • If you are using the IBM JRE, then change the values to:

     <KeyStore>
     <Location>new_keystore_name</Location>
     <Password encrypted="false">new_keystore_pwd</Password>
     <Type>JKS</Type>
     <Provider>com.ibm.crypto.provider.IBMJCE</Provider>
     </KeyStore>
     

   • For all other JREs, change the values to:

     <KeyStore>
     <Location>new_keystore_name</Location>
     <Password encrypted="false">new_keystore_pwd</Password>
     <Type>JKS</Type>
     <Provider>sun.security.provider.Sun</Provider>
     </KeyStore>
     

5. Restart the remote manager server, and reopen the xlconfig.xml file to ensure that the password for the new keystore is encrypted.

To configure the remote manager by using your own certificate on Oracle Identity Manager:

1. Export the certificate from the newly created keystore on the remote manager computer, as shown in the following example:

   keytool-export -keystore test.jks -storepass welcome1 -alias rmcert -file test.cer
   

2. Copy the new certificate file to the $DOMAIN_HOME/config/fmwconfig/ directory.

3. Import certificate into default-keystore.jks, as shown in the following example:

   keytool-import -keystore test.jks -storepass welcome1 -alias test_alias -file test.cer -trustcacerts
   

4. Check if the connection between remote manager and Oracle Identity Manager is established, as described in "Testing the Remote Manager Connection".

21.2.3 Testing the Remote Manager Connection

To test if the connection between remote manager and Oracle Identity Manager is established:

1. Login to the Design Console.

2. Open the Remote Manager form. This form displays the following:

   • The names and IP addresses of the remote managers that communicate with Oracle Identity Manager

   • Whether or not the remote managers are running

   • Whether or not the remote managers represent IT resources that Oracle Identity Manager can use

   See Also:

   "Remote Manager Form" in the Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for information about the Remote Manager form

3. Verify if the check boxes in the Running and IT Resource columns are selected for the remote manager service that you configured. This ensures that the remote manager is running and it represents an IT resource that Oracle Identity Manager can use.

21.2.4 Updating the xlconfig.xml File to Change the Port for Remote Manager

Changing the port for the remote manager is not required at the time of configuring the remote manager. This is required if you need to change ports while using the product.

To update the xlconfig.xml file and start the remote manager on a new port as opposed to what was set during installation:

1. In a text editor, open the $XLREMOTE_HOME/xlremote/config/xlconfig.xml file.

2. Edit the following tags and change the port number:

   • ListenPortunder RMSecurity for remote manager SSL Listen port

   • RMIRegistryPort under RMSecurity for RMI Registry

3. Restart the remote manager. See "Stopping and Starting the Remote Manager" for details.

21.3 Stopping and Starting the Remote Manager

To stop remote manager, navigate to the console from which the remote manager was started, and press CTRL+C. The remote manager is a command-line application, which will stop on this signal.

To start the remote manager, run the following script:

For UNIX:

$XLREMOTE_HOME/xlremote/remotemanager.sh

For Microsoft Windows:

$XLREMOTE_HOME\xlremote\remotemanager.bat

21.4 Troubleshooting Remote Manager

Table 21-1 lists the troubleshooting steps that you can perform if you encounter problems with the remote manager:

Table 21-1 Troubleshooting Remote Manager

Problem	Solution
You encounter certificate trust issues.	Ensure that the remote manager certificate is trusted on the Oracle Identity Manager side.
	Ensure that the remote manager certificate has not expired.
	Ensure that the remote manager port is correctly configured on the Oracle Identity Manager host. In other words, ensure that the port configured on the Oracle Identity Manager host must be the same port in the remote manager configuration.
	Ensure that the remote manager configuration, such as keystore location, alias, password, and key password, in the xlconfig.xml file and Oracle Identity Manager host configuration in the oim-config.xml file are correct.
	Ensure that the correct server certificate is trusted on the remote manager if client-auth is set.
After ensuring all the conditions to resolve certificate trust issues, failure occurs while communicating between the remote manager and Oracle Identity Manager.	Restart Oracle Identity Manager and remote manager by passing the following flag: -Djavax.net.debug={all|ssl} This flag, when turned on stores all the information related to the SSL/TLS handshake in the logs. Here, all turns on all debugging, and ssl turns on SSL debugging. Note: Use this flag only for debugging purpose. When turned on, it dumps a huge amount of information in the logs.
The remote manager connection fails.	Ensure that there is no firewall between Oracle Identity Manager and remote manager that is blocking tcp traffic on the specific port. To do this, telnet from the Oracle Identity Manager host to the remote manager host on the remote manager port.
Provisioning through the remote manager fails.	Ensure that the adapter JAR files (which are usually located in the $OIM_HOME/JavaTasks/ directory or in the database) are copied on the remote manager host in the JavaTasks/ directory.
	Ensure that the remote manager-based adapters have a Remote Task to invoke target APIs, as opposed to regular adapters, which can just use Java Task to do the same.
	Ensure that the remote manager-based connectors: - Define a remote manager IT resource. - Set the remote manager IT resource on the remote manager field on the regular IT resource, which contains the connectivity information of the target