8 Post-Install Configuration for Oracle Identity Manager and WebSphere

After you have installed Oracle Identity Manager, you must complete some post-installation tasks before you can use the application. Some of these tasks are common to all types of Oracle Identity Manager component installations; others are application server-specific tasks. This chapter describes:

• General post-installation tasks for all Oracle Identity Manager installations—see "General Post-Installation Tasks" for more information.

• Post-installation tasks for a WebSphere configuration—see "Post-Installation Steps for WebSphere" for more information.

General Post-Installation Tasks

For any Oracle Identity Manager installation, you must change the keystore passwords from their defaults. If you are using a Remote Manager, you must enable a trust relationship between the Remote Manager and the Oracle Identity Manager server. Several of these tasks are optional and not required for system operation.

Changing Keystore Passwords (optional)

Oracle Identity Manager has two keystores: one for the Oracle Identity Manager server and one for the database. During installation, the passwords for both are set to xellerate. You can use the keytool to change the keystore password for either keystore. Oracle recommends changing the keystore passwords for all production installations.

To change the keystore password:

1. Open a command prompt on the Oracle Identity Manager host computer.

2. Navigate to the <XL_HOME>\xellerate\config directory.

3. Run the keytool with the following options:

   <JAVA_HOME>\jre\bin\keytool -storepasswd -new <new_password> -storepass xellerate -keystore .xlkeystore -storetype JKS
   
   

   where <JAVA_HOME> is the location of the Java directory associated with your application server, <new_password> is the new password for the keystore, the keystore option is the keystore whose password you are changing the (.xlkeystore for the Oracle Identity Manager server, or .xldatabasekey for the database), and the storetype option is JKS for .xlkeystore and JCEKS for .xldatabasekey.

4. Launch a plain-text editor, then open the file xlconfig.xml, which is located in the directory <XL_HOME>\xellerate\config.

5. Edit the <xl-configuration>.<Security>.<XLPKIProvider>.<KeyStore> section to specify the keystore password.

   
   

   Note: Change the <XLSymmetricProvider>.<KeyStore> section of the configuration file to update the password for the database keystore (.xldatabasekey).

   
   

   • Change the password tag to encrypted=ÓfalseÓ.

   • Enter the password (in the clear). For example, change the following block:

     <Security>
             <XLPKIProvider>
     <KeyStore>
                     <Location>.xlkeystore</Location>
                     <Password encrypted=ÓtrueÓ>xYr5V2FfkRYHxKXHeT9dDg==</Password>
                     <Type>JKS</Type>
                     <Provider>sun.security.provider.Sun</Provider>
     </KeyStore>
     
     

     to the following:

     <Security>
             <XLPKIProvider>
     <KeyStore>
                     <Location>.xlkeystore</Location>
                     <Password encrypted=ÓfalseÓ>newpassword</Password>
                     <Type>JKS</Type>
                     <Provider>sun.security.provider.Sun</Provider>
     </KeyStore>
     
     

6. Restart your application server.

   When you stop and start the application server, a backup of the configuration file is created. The configuration file (with the new password) is read in, and the password is encrypted in the file.

7. If all of the preceding steps have succeeded, you can delete the backup file.

Setting Log Levels (optional)

Oracle Identity Manager uses log4j for logging. For WebSphere-based Oracle Identity Manager installations, logging is configured in the logging properties file, <XL_HOME>/xellerate/config/log.properties.

By default, Oracle Identity Manager is configured to output at the Warning level. You can change the log level universally for all components or for an individual component. For normal operation of Oracle Identity Manager, this post-installation configuration step is not required.

Oracle Identity Manager Component Logging

The components are listed in the <XL_HOME>\xellerate\config\log.properties file in the XELLERATE section. They are:

log4j.logger.XELLERATE.ACCOUNTMANAGEMENT
log4j.logger.XELLERATE.SERVER
log4j.logger.XELLERATE.RESOURCEMANAGEMENT
log4j.logger.XELLERATE.REQUESTS
log4j.logger.XELLERATE.WORKFLOW
log4j.logger.XELLERATE.WEBAPP
log4j.logger.XELLERATE.SCHEDULER
log4j.logger.XELLERATE.SCHEDULER.Task
log4j.logger.XELLERATE.ADAPTERS
log4j.logger.XELLERATE.JAVACLIENT
log4j.logger.XELLERATE.POLICIES
log4j.logger.XELLERATE.RULES
log4j.logger.XELLERATE.DATABASE
log4j.logger.XELLERATE.APIS
log4j.logger.XELLERATE.OBJECTMANAGEMENT
log4j.logger.XELLERATE.JMS
log4j.logger.XELLERATE.REMOTEMANAGER
log4j.logger.XELLERATE.CACHEMANAGEMENT
log4j.logger.XELLERATE.ATTESTATION
log4j.logger.XELLERATE.AUDITOR

Setting Log Levels for WebSphere

To set Oracle Identity Manager log levels in Oracle Identity Manager running on WebSphere, edit the logging properties file (log.properties).

Complete the following steps to set log levels:

1. Open the <XL_HOME>/xellerate/config/log.properties file in a text editor.

   This file contains a general setting for Oracle Identity Manager and specific settings for the components and modules that comprise Oracle Identity Manager.

   By default, Oracle Identity Manager is configured to output at the Warning level:

   log4j.logger.XELLERATE=WARN
   
   

   This is the general value for Oracle Identity Manager. Individual components and modules are listed following the general value in the properties file. You can set individual components and modules to different log levels. The log level for a specific component overrides the general setting.

2. Set the general value to the desired log level. The following is a list of the supported log levels, appearing in descending order of information logged (DEBUG logs the most information and FATAL logs the least information):

   • DEBUG

   • INFO

   • WARN

   • ERROR

   • FATAL

3. Set other component log levels as desired. Individual components or modules can have different log levels. For example, the following values set the log level for the Account Management module to INFO, while the server is at DEBUG and the rest of Oracle Identity Manager is at the WARN level.

   log4j.logger.XELLERATE=WARN
   log4j.logger.XELLERATE.ACCOUNTMANAGEMENT=INFO
   log4j.logger.XELLERATE.SERVER=DEBUG
   
   

4. Save your changes.

5. Restart your application server so that the changes take effect.

Post-Installation Steps for WebSphere

If you are using WebSphere for your application server, after you install the Oracle Identity Manager software, perform the tasks in this section after stopping and restarting WebSphere.

Creating the Initial State of the JMS Server

To ensure that the Request Wizard in the Oracle Identity Manager Administrative and User Console (Web Client) works properly, verify that the JMS Server's initial state is set to START.

To check the initial state of the JMS server:

1. Open the server.xml file in a text editor (the file is located in <WEBSPHERE_HOME>/Appserver/config/cells/<cell name>/nodes/<node name>/servers/server1/).

2. In the JMSServer section, if necessary, change the value of the initialState variable to START. The section should look something like the following:

   <components xmi:type=Ómessagingserver:JMSServerÓ xmi:id=ÓJMSServer_1Ó
   name=ÓInternal JMS ServerÓ description=ÓInternal WebSphere JMS ServerÓ
   numThreads=Ó1Ó>
   <stateManagement xmi:id=ÓStateManageable_4Ó initialState=ÓSTARTÓ/>
   
   

3. Save and close the file.

Configuring WebSphere on Nondefault Ports

To run Oracle Identity Manager on WebSphere using nondefault ports (not 80, 443, or 9080), you must add the port mapping information for the server using the WebSphere administrative console. Add the port mapping for the HTTP transport for the nondefault server by using the WebSphere administrative console.

Configuring WebSphere on Nondefault HTTP Port

To use a nondefault HTTP port:

1. Select Environment, select Virtual Host, select default_host, then select Host Alias.

2. Click New.

3. Enter the Host Name and Port Number.

   
   

   Note: Setting the Virtual Host, by default, does not include the non-standard ports for a WebSphere configuration. Therefore, you must set the Virtual Host for non-standard server installation and clustered environment installation.

   
   

4. Change the <ApplicationURL> tag in xlclient\config\xlconfig.xml to the correct http port.

5. Restart the application server you used to install Oracle Identity Manager.

Configuring WebSphere on Nondefault Naming Service Port

To use a nondefault naming service port:

1. To find the naming service port, use the WebSphere Administrative Console. Click Server, select Application Server, select <servername>, select End Points, then select Bootstrap_Address. The screen displays the Host Name and Port Number.

   When installing on a nondefault port, the xlconfig.xml file must be modified even if the installation is on server1. In a clustered environment, the xlconfig.xml file must always be modified.

   
   

   Note: The default server, server1, needs the configuration file, xlconfig.xml as well as all other servers (nondefault) in the cell to share the same security information.

   
   

2. Edit the discovery port settings in the following two files:

   • xellerate\config\xlconfig.xml

   • xlclient\config\xlconfig.xml

   For example, the first server other than the default server, uses 2810 as the naming service port.

Configuring WebSphere on a Nondefault Server

The WebSphere administrative console runs on the default server (server1), which is installed with all WebSphere installations. If you install WebSphere, and then use a server name other than server1 (the default), you must manually configure server1 to recognize Oracle Identity Manager.

To configure WebSphere on a nondefault server (named something other than server1):

Note: For this procedure, the name of the nondefault server is xlServer.

1. Open the server.xml file, which resides in the directory <WEBSPHERE_HOME>\config\cells\<cellname>\nodes\<nodename>\servers\server1.

   where <cellname> is the cell name.

2. Modify the server.xml file for server1 to include a XL.HomeDir system property that specifies the Oracle Identity Manager home directory. For example:

   <systemProperties xmi:id="Property_1119378049482" name="XL.HomeDir" value="C:/xlserver/xellerate" description="Xellerate Home Directory" required="true"/>
   
   

   Add the system property to the jvm entry, for example:

   <jvmEntries xmi:id="JavaVirtualMachine_1" verboseModeClass="false" verboseModeGarbageCollection="false" verboseModeJNI="false" runHProf="false" hprofArguments="" debugMode="false" debugArgs="-Djava.compiler=NONE -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777" genericJvmArguments="">
         <systemProperties xmi:id="Property_1119378049482" name="XL.HomeDir" value="C:/xlserver/xellerate" description="Xellerate Home Directory" required="true"/>
       </jvmEntries>
   
   

   
   

   Note: Refer to the WebSphere installation documentation for detailed information on setting a HomeDir system property.

   
   

3. Start the servers using the following command with arguments:

   startServer <servername> –user xelsysadm -password xelsysadm
   
   

Enabling xelsysadm Access to the Dead Letter Queue

When an Oracle Identity Manager request is created, the Oracle Identity Manager server sends a message to the JMS server. However, there are some cases where the process time is very long.

When this happens, the Oracle Identity Manager server sends a response to the end user (so that wait time is minimized) and also a message to the JMS server, asynchronously. The JMS server then sends a message to Message Driven Bean (MDB) and the MDB digests the message.

If the MDB fails to process the message, it throws an Exception. The transaction is rolled back and WebSphere resends the message to MDB until it reaches the maximum retry count.

If the MDB still fails, it again rolls back the transaction. If the retry count is reached, WebSphere does not resend the message MDB. Instead, it sends the message to SYSTEM.DEAD.LETTER.QUEUE. This measure prevents an infinite loop.

SYSTEM.DEAD.LETTER.QUEUE is a system resource that is protected by the Embedded Java Message Server, so, an authorized client is required to access it. For Oracle Identity Manager, the WebSphere administrative user, xelsysadm, is the user id that must be authorized. You must add xelsysadm in the integral-jms-authorizations.xml file so that xelsysadm has permission to access SYSTEM.DEAD.LETTER.QUEUE.

Note: If you used a user ID or password other than xelsysadm for WebSphere, enter it instead of xelsysadm in the procedure that follows.

To add xelsysadm as an authorized user:

1. Navigate to <WebSphere_Home>config\cells\<cell_name>.

2. Open the file integral-jms-authorizations.xml, in a text editor.

3. Search for the tag, <queue-admin-userids>.

   
   

   Note: There are two <queue-admin-userids> tags in the file. One is commented out and the other is not. Modify the tag that is not commented out.

   
   

4. Add the line <userid>xelsysadm</userid>, so that it looks like:

   <queue-admin-userids>
      <userid>xelsysadm</userid> 
     </queue-admin-userids>
   
   

5. Save your changes.

6. Restart the server.

Set the Maximum Retries for JMS Listener

If the maximum retries for JMS Listener is less than or equal to 5, it shuts down the JMS Listener before the Embedded Java Message Server sends the message to SYSTEM.DEAD.LETTER.QUEUE. Therefore, to prevent the JMS Listener from shutting down, change the default value to a number greater than 5.

To change the retries for the JMS Listener:

1. Launch the WebSphere administrative console.

2. Click Servers on the left pane and navigate to Application Servers, select <Server_Name>.

3. On the Configuration tab, scroll to the Additional Properties section, then select Message Listener Service, and click Listener Ports.

4. Click MessageHandlerMDB_JMSPort.

5. Modify maximum retries from 5 to a greater value.

6. Click OK and then click Save.

Configuring the ORB Service

When a business transaction, for example, searching for multiple requests or users, returns a large dataset object (greater than 500KB), it may cause the system to throw an exception. When this happens using WebSphere, CORBA_NO_MEMORY is recorded in the WebSphere log file and System Error is displayed as an error message window in the Oracle Identity Manager Administrative and User Console.WebSphere documentation explains that this exception happens because an Application Server can record totally out of heap space or insufficient heap space to satisfy allocation request when the Java virtual machine is unable to allocate a block contiguous space on the heap to allocate a large object.To avoid this exception, you must enable WebSphere to pass parameters by reference through ORB. If enabled, ORB passes parameters by reference, instead of by value, which avoids making an object copy. If you do not enable Pass by reference, the parameters are copied to the stack before every remote method call is made.Use the following steps to enable the Pass by Reference parameter for the ORB Service:

1. Open the WebSphere Administrative Console.

2. Select Servers>Application Servers><Server_Name>>ORB Service. The ORB Service window appears.

3. Locate the Pass by reference parameter and enable the check-box by selecting it.

4. Click Apply.

5. Save the service settings.

Enabling SIngle Sign-On (SSO)

Use the following steps to enable SSO for Oracle Identity Manager:

1. Stop the application server gracefully.

2. Launch a plain-text editor and open the <XL_HOME>\xellerate\config\xlconfig.xml file.

3. Locate the following SSO configuration (these are the default settings without SSO):

   <web-client>
           <Authentication>Default</Authentication>
           <AuthHeader>REMOTE_USER</AuthHeader>
   </web-client>
   
   

4. Edit the SSO configuration to be the following:

   <web-client>
           <Authentication>SSO</Authentication>
           <AuthHeader><SSO_HEADER_NAME></AuthHeader>
   </web-client>
   
   

   Replace <SSO_HEADER_NAME> with the appropriate header configured in your SSO system.

5. Change your application server and web server configuration to enable SSO. Refer to your application and web server vendor documentation for detailed instructions.

6. Restart the application server.

Note: Header names comprised only of alphabetic characters are certified. Oracle recommends not using special characters or numeric characters in header names.