7 Postinstallation Configuration for Oracle Identity Manager and IBM WebSphere Application Server

After installing Oracle Identity Manager, perform the postinstallation tasks documented in this chapter that are appropriate for your deployment before using the application. Depending on the Oracle Identity Manager deployment, you might choose not to perform some of these tasks.

The postinstallation tasks are discussed in the following topics:

• Default JMS Queue Details

• Increasing the JMS Message Threshold

• Configuring WebSphere on Nondefault Ports

• Configuring the ORB Service

• Changing Keystore Passwords

• Setting Log Levels

• Enabling Single Sign-On (SSO) for Oracle Identity Manager

• Configuring Custom Authentication

• Increasing the Transaction Timeout

• Increasing the Authentication Expiration

• Selecting the Oracle 10g Data Store Helper Class

• Setting the Compiler Path for Adapter Compilation

• Deploying the SPML Web Service

• Tuning JDBC Connection Pools

• Copying the sqljdbc.jar File

7.1 Default JMS Queue Details

Previously, Oracle Identity Manager used a single JMS queue (named xlQueue) for all asynchronous operations including requests, reconciliation, attestation, and offline tasks. From release 9.1.0 onward, by default, Oracle Identity Manager uses separate JMS queues for specific operations to optimize JMS queue processing. The following list shows the JMS queues in the default configuration and indicates the operation related to each queue:

• xlQueue (for request operations)

• xlReconQueue (for reconciliation operations)

• xlAuditQueue (for auditing operations)

• xlAttestationQueue (for attestation operations)

• xlProcessQueue (for use in a future release)

7.2 Increasing the JMS Message Threshold

You must increase the default JMS message threshold of 50000 to 999999 on all the JMS queues.

To increase the default JMS message threshold for each JMS queue:

1. Log in to the WebSphere Administrative Console.

2. Click Service Integration, Buses, XellerateBus, Destinations, QUEUE_NAME, Queue Points, and QUEUE_POINT_NAME.

3. In the High Message Threshold field, enter 999999.

Repeat Steps 2 through 3 for all the JMS queues.

7.3 Configuring WebSphere on Nondefault Ports

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

7.3.1 Configuring WebSphere on Nondefault HTTP Port

To use a nondefault HTTP port:

1. Select Environment, Virtual Host, default_host, and 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 nonstandard ports for a WebSphere configuration. You must set the Virtual Host for nonstandard 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.

7.3.2 Configuring WebSphere on Nondefault Naming Service Port

To use a nondefault naming service port:

1. In the WebSphere Administrative Console, click Server, select Application Server, select SERVER_NAME, and then select Ports under Communication. Make a note of the BOOTSTRAP_ADDRESS.

   The page displays the host name and port number. The default port is 2809.

   When installing on a nondefault port, the xlconfig.xml file must be modified even if the installation is on server1. In a clustered installation, 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 files:

   • xellerate\config\xlconfig.xml

   • xlclient\config\xlconfig.xml

7.4 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 can cause the system to throw an exception. When this happens by 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 is thrown 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.Perform the following steps to enable the Pass by Reference parameter for the ORB Service:

1. Log in to the WebSphere Administrative Console.

2. Select Servers, then Application Servers, then SERVER_NAME, and then ORB Service under Container Services. The ORB Service window is displayed.

3. Locate the Pass by reference parameter and select the option for the parameter to enable it.

4. Click Apply.

5. Save the service settings.

7.5 Changing Keystore Passwords

During installation, the passwords for the Oracle Identity Manager keystores are set to xellerate. The Installer scripts and installation log contain this default password. It is strongly recommended that you change the keystore passwords for all production installations.

To change the keystore passwords you must change the storepass of .xlkeystore and the keypass of the xell entry in .xlkeystore, and these two values must be identical. Use the keytool and the following steps to change the keystore passwords:

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

2. Navigate to the OIM_HOME\xellerate\config directory.

3. Run the keytool with the following options to change the storepass:

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

4. Run the keytool with the following options to change the keypass of the xell entry in .xlkeystore:

   JAVA_HOME\jre\bin\keytool -keypasswd -alias xell -keypass xellerate -new new_password -keystore .xlkeystore -storepass new_password
   

   Note:

   Replace new_password with the same password entered in step 3.

   Table 7-1 lists the options used in the preceding example of keytool usage.

   Table 7-1 Command Options for the keytool Utility

   Option	Description
   JAVA_HOME	Location of the Java directory associated with the application server
   new_password	New password for the keystore
   -keystore option	Keystore whose password you are changing (.xlkeystore for Oracle Identity Manager or .xldatabasekey for the database)
   -storetype option	JKS for .xlkeystore and JCEKS for .xldatabasekey

   
   

5. In a text editor, open the OIM_HOME\xellerate\config\xlconfig.xml file.

6. Edit the <xl-configuration>.<Security>.<XLPKIProvider>.<KeyStore> section, <xl-configuration>.<Security>.<XLPKIProvider>.<Keys> section, and the <RMSecurity>.<KeyStore> section to specify the keystore password as follows:

   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, for example:

     <Security>
     <XLPKIProvider>
     <KeyStore>
           <Location>.xlkeystore</Location>
           <Password encrypted="false">new_password</Password>
           <Type>JKS</Type>
           <Provider>com.ibm.crypto.provider.IBMJCE</Provider>
     </KeyStore>
     <Keys> 
     <PrivateKey> 
     <Alias>xell</Alias> 
     <Password encrypted="false">new_password</Password> 
     </PrivateKey> 
     </Keys> 
     <RMSecurity> 
     <KeyStore> 
     <Location>.xlkeystore</Location> 
     <Password encrypted="false">new_password</Password> 
     <Type>JKS</Type> 
     <Provider>com.ibm.crypto.provider.IBMJCE</Provider> 
     </KeyStore>
     

7. Save and close the xlconfig.xml file.

8. Restart the 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.

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

   Note:

   On UNIX or Linux, you might also want to clear the command history of the shell by using the following command:

   history -c
   

7.6 Setting Log Levels

Oracle Identity Manager uses log4j for logging. Logging levels are configured in the logging properties file, OIM_HOME/xellerate/config/log.properties. By default, Oracle Identity Manager is configured to provide output at the Warning level except for DDM, which is configured to provide output at the Debug level by default. You can change the log level universally for all components or for an individual component.

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

Oracle Identity Manager components are listed in the OIM_HOME\xellerate\config\log.properties file in the XELLERATE section, for example:

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

To set Oracle Identity Manager log levels, edit the logging properties in the OIM_HOME\xellerate\config\log.properties file as described in the following procedure.

To configure log levels:

1. In a text editor, open the OIM_HOME\xellerate\config\log.properties file.

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

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 the changes.

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

7.7 Enabling Single Sign-On (SSO) for Oracle Identity Manager

The following procedure describes how to enable Single Sign-On for Oracle Identity Manager with ASCII character logins. To enable Single Sign-On with non-ASCII character logins, use the following procedure, but include the additional configuration setting described in step 4.

See Also:

Oracle Identity Manager Best Practices Guide for more information about configuring Single Sign-On for Oracle Identity Manager with Oracle Access Manager.

Note:

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

To enable Single Sign-On for Oracle Identity Manager:

1. Stop the application server gracefully.

2. In a text editor, open the OIM_HOME\xellerate\config\xlconfig.xml file.

3. Locate the following Single Sign-On configuration. The following are the default settings without Single Sign-On:

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

4. Edit the Single Sign-On configuration to be the following, and replace SSO_HEADER_NAME with the appropriate header configured in your Single Sign-On system:

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

   To enable Single Sign-On with non-ASCII character logins, you must include a decoding class name to decode the non-ASCII header value. Add the decoding class name and edit the Single Sign-On configuration as follows:

   <web-client>
   <Authentication>SSO</Authentication>
   <AuthHeader>SSO_HEADER_NAME</AuthHeader>
   <AuthHeaderDecoder>com.thortech.xl.security.auth.CoreIDSSOAuthHeaderDecoder</AuthHeaderDecoder>
   </web-client>
   

   Replace SSO_HEADER_NAME with the appropriate header configured in your Single Sign-On system.

5. Change the application server and Web server configuration to enable Single Sign-On by referring to the application and Web server vendor documentation.

6. Restart the application server.

7.8 Configuring Custom Authentication

This section describes how to use custom authentication solutions with Oracle Identity Manager.

Oracle Identity Manager deploys a Java Authentication and Authorization Service (JAAS) module to authenticate users. For unattended logins, which require offline message processing and scheduled task execution, Oracle Identity Manager uses signature-based authentication. Although you can use JAAS to handle signature-based authentication, you can create a custom authentication solution to handle standard authentication requests.

Note:

The Oracle Identity Manager JAAS module must be deployed on the application server and must be the first invoked authenticator.

To enable custom authentication on WebSphere application server, you use the WebSphere Administrative Console to define a property named customAuthentication in the Custom Properties section of the Custom User Registry, as follows:

1. Log in to the WebSphere Administrative Console

2. Expand Security and Secure administration, applications, and infrastructure.

3. Click Configure next to Standalone Custom Registry.

4. Click Custom Properties, and then click New.

5. In the Name field, enter customAuthentication.

6. In the Value field, enter the name of a custom authentication class that implements the com.ibm.websphere.security.UserRegistry class.

7. Restart the WebSphere application server.

7.8.1 Protecting the JNDI Namespace

When you specify a custom authentication solution, you must also protect the Java Naming and Directory Interface (JNDI) namespace to ensure that only designated users have permission to view resources. The primary purpose of protecting the JNDI namespace is to protect Oracle Identity Manager from any malicious applications that might be installed in the same application server instance. Even if no other applications, malicious or otherwise, are installed in the same application server instance as Oracle Identity Manager, you must protect your JNDI namespace as a routine security measure.

To configure Oracle Identity Manager to access a protected JNDI namespace, perform the following steps:

1. Open the OIM_HOME/config/xlconfig.xml file in a text editor and add the following elements to the <Discovery> element:

   <java.naming.security.principal>
   <java.naming.security.credentials>
   

2. To optionally encrypt the JNDI password, add an encrypted attribute that is assigned a value of true to the <java.naming.security.credentials> element, and assign the password as the value of the element, as follows:

   <java.naming.security.credentials
     encrypted="true">password</java.naming.security.credentials>
   

3. Add the following elements to the <Scheduler> element:

   <CustomProperties>
     <org.quartz.dataSource.OracleDS.java.naming.security.principal>user
     </org.quartz.dataSource.OracleDS.java.naming.security.principal>
     <org.quartz.dataSource.OracleDS.java.naming.security.credentials>pwd
     </org.quartz.dataSource.OracleDS.java.naming.security.credentials></CustomProperties>
   

4. Restart the server.

7.9 Increasing the Transaction Timeout

You have to increase the transaction timeout values for WebSphere Application Server because the default values can be low for certain transactions. Oracle recommends that the values as specified in the following steps.

Note:

Depending on the specific requirements, the values might require revision in the future.

1. Log in to the WebSphere Administrative Console.

2. Select Servers, Application Servers, SERVER_NAME, and then select Transaction Services under Container Services.

3. Enter 1200 for total transaction lifetime timeout.

4. Enter 1200 for maximum transaction timeout.

5. Save the service settings.

6. Restart the servers.

Note:

In the cluster environment, you must repeat the steps for all the available WebSphere servers in the cluster.

7.10 Increasing the Authentication Expiration

Be default the websphere expires the authentication information based on the timeout configuration. By default timeout is set at 120 minutes. Note that this might not be enough, if you are planning to run a long reconciliation activity or any other scheduled tasks. Therefore, timeout must be increased to a suitable value in minutes.

To increase the authentication expiration:

1. Log on to the WebSphere Administrative Console.

2. Click Security.

3. Select Secure administration, applications, and infrastructure.

4. Select Authentication mechanisms and expiration.

5. Enter the value for Timeout value for forwarded credentials between servers in minutes.

7.11 Selecting the Oracle 10g Data Store Helper Class

Perform the following steps to change the default Oracle 9i Data Store Helper class to the Oracle 10g Data Store Helper class:

1. Log on to WebSphere Administrative Console.

2. Select Resources, JDBC, Data Sources, and then select Non XA DataSource.

3. Select Oracle 10g data store helper in the Data store helper class name field.

4. Click OK, and then click Save.

5. Select Resources, JDBC, Data Sources, and then select XA DataSource.

6. Select Oracle 10g data store helper in the Data store helper class name field.

7. Click OK, and then click Save.

7.12 Setting the Compiler Path for Adapter Compilation

To compile adapters or import Deployment Manager XML files that have adapters, you must set the compiler path. To set the compiler path for adapter compilation, you must first install the Design Console. Refer to Chapter 10, "Installing and Configuring the Oracle Identity Manager Design Console" for instructions on installing the Design Console and then setting the compiler path for adapter compilation.

7.13 Deploying the SPML Web Service

Organizations can have multiple provisioning systems that exchange information about the modification of user records. In addition, there can be applications that interacts with multiple provisioning systems. The SPML Web Service provides a layer over Oracle Identity Manager to interpret SPML requests and convert them to Oracle Identity Manager calls.

The SPML Web Service is packaged in a deployable Enterprise Archive (EAR) file. This file is generated when you install Oracle Identity Manager.

Because the EAR file is generated while you install Oracle Identity Manager, a separate batch file in the Oracle Identity Manager home directory runs the scripts that deploy the SPML Web Service on the application server on which Oracle Identity Manager is running. You must run the batch file to deploy the SPML Web Service.

For details about the SPML Web Service, see Chapter 12, "The SPML Web Service" in Oracle Identity Manager Tools Reference.

7.14 Tuning JDBC Connection Pools

To implement the tuning for the JDBC connection pools used by Oracle Identity Manager:

Note:

It is strongly recommended that you implement the suggested tuning for the JDBC connection pools used by Oracle Identity Manager. This can be further tuned based on the application usage.

1. Log on to WebSphere Administrative Console.

2. Select Resources, JDBC, Data Sources, and then select Non XA DataSource. Select Connection pool properties under Additional properties. And enter/ensure the following values.

   Minimum connections: 30
   Maximum connections: 50
   

3. Click OK, and then click Save.

4. Select Resources, JDBC, Data Sources, and then select XA DataSource. Select Connection pool properties under Additional properties. And enter/ensure the following values.

   Minimum connections: 30
   Maximum connections: 50
   

5. Click OK, and click Save.

7.15 Copying the sqljdbc.jar File

Copy the sqljdbc.jar file from the C:\jdbc_install_folder\ directory to the WEBSPHERE_HOME/lib/ directory.

Note:

• For a cluster installation of Oracle Identity Manager, copy the sqljdbc.jar file to the NDM_HOME/lib directory in all the cluster nodes.

• If the sqljdbc.jar is not copied to the WEBSPHERE_HOME/lib/ directory, then Oracle Identity Manager fails to start.