7 Postinstallation Configuration for Oracle Identity Manager and BEA WebLogic Server

After you have installed Oracle Identity Manager, you must complete some postinstallation tasks before you can use the application. Some of the postinstallation tasks are optional, depending on your deployment.

This chapter discusses the following topics:

• Default JMS Queue Configuration

• Changing Keystore Passwords

• Required Postinstallation Tasks

• Optional Postinstallation Tasks

• Setting the Compiler Path for Adapter Compilation

• Deploying the SPML Web Service

Default JMS Queue Configuration

Previously, Oracle Identity Manager used a single JMS queue (named xlQueue) for all asynchronous operations including requests, reconciliation, attestation, and offline tasks. In release 9.1.0, 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)

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 utility to change the keystore passwords by performing the following steps:

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 utility 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 OIM_HOME\xellerate\config\xlconfig.xml.

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>sun.security.provider.Sun</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>sun.security.provider.Sun</Provider> 
     </KeyStore>
     

7. Save and close the xlconfig.xml file.

   Note:

   When you perform the procedure described in the "Shutting Down and Restarting BEA WebLogic Server" section, 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. If all of the preceding steps succeed, then you can delete the backup file.

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

   history -c
   

Required Postinstallation Tasks

After you install Oracle Identity Manager on BEA WebLogic Server, you must perform the following tasks:

• Increasing the Memory and Setting the Java Option

• Setting Up Authentication

• Setting Up the XML Registry

• WebLogic JMS Server Configuration Changes

• Setting the Transaction Timeout Parameter

• Copying the Oracle 10.2.0.3 JDBC JAR File in a Clustered Installation

• Shutting Down and Restarting BEA WebLogic Server

Increasing the Memory and Setting the Java Option

To increase the memory and set the Java option:

1. Use the WebLogic Server Administration Console to shut down the application server gracefully.

2. Navigate to BEA_HOME\user_projects\domains\domain_name. For example, C:\bea\user_projects\domains\mydomain.

3. In a text editor, open the WebLogic start script file. The start script is:

   • For Microsoft Windows:

     startWebLogic.cmd
     

   • For UNIX:

     startWebLogic.sh
     

4. JVM memory settings must be changed for production environments and when processing a large volume of data in nonproduction environments. Edit the script to specify memory options as follows:

   For Microsoft Windows, locate the line that starts with the following:

   %JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS%
   

   Add either of the following lines just before it:

   • If Sun JVM is used:

     set MEM_ARGS=-Xms1280m -Xmx1280m -XX:PermSize=128m -XX:MaxPermSize=256m
     

   • If BEA JRockit JVM is used:

     set MEM_ARGS=-Xms1280m -Xmx1280m
     

   For UNIX, locate the line that starts with the following:

   $JAVA_HOME/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS}
   

   Add either of the following lines just before it:

   • If Sun JVM is used:

     MEM_ARGS="-Xms1280m -Xmx1280m -XX:PermSize=128m -XX:MaxPermSize=256m"
     export MEM_ARGS
     

   • If BEA JRockit JVM is used:

     MEM_ARGS="-Xms1280m -Xmx1280m"
     export MEM_ARGS
     

5. If BEA JRockit JVM is being used, add the -XnoOpt option to the existing JAVA_OPTIONS. This option turns off adaptive optimization and is required for stable Oracle Identity Manager operation.

   For Microsoft Windows, locate the line that starts with the following:

   %JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS%
   

   Add the following line just before it:

   set JAVA_OPTIONS=%JAVA_OPTIONS% -XnoOpt
   

   For UNIX, locate the line that starts with the following:

   $JAVA_HOME/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS}
   

   Add the following line just before it:

   JAVA_OPTIONS="$JAVA_OPTIONS -XnoOpt"
   export JAVA_OPTIONS
   

6. Save and close the file.

Setting Up Authentication

To set up the authentication:

1. Log on to the WebLogic Server Administration Console.

2. In the left frame, select Security, Realms, myrealms, Providers, and then select Authentication.

3. Click Configure a new OIMAuthenticator.

   1. Retain the default value in the Name field.

   2. Set the Control Flag to Sufficient, and then click Create.

4. In the left frame, click Authentication, and then select DefaultAuthenticator. Set the Control Flag to Sufficient, and then click Apply.

Setting Up the XML Registry

To set up the XML registry:

1. Log on to the WebLogic Server Administration Console.

2. In the left frame, click Services.

3. Right-click XML, then select Configure a new XMLRegistry from the shortcut menu.

4. Enter the registry information:

   1. Enter a unique name, for example, Oracle Identity Manager XML registry.

   2. Use default values for the other fields, then click Create.

5. Click the Target and Deploy tab.

   1. Select the server option.

      Note:

      For clustered installations, select all Managed Servers that are part of the cluster.

   2. Click Apply.

6. In the left frame, click XML, and then click your new XML registry entry to expand it.

7. Right-click Parser Select Entries, and then select Configure a New XMLParserSelectRegistryEntry from the shortcut menu.

8. Enter the configuration information:

   1. Ensure that the Public ID field is blank.

   2. Ensure that the System ID field is blank.

   3. In the Root Element Tag field, enter database.

   4. In the Document Builder Factory field, enter the following:

      org.apache.crimson.jaxp.DocumentBuilderFactoryImpl
      

   5. Ensure that the Parser Class Name field is blank.

   6. In the SAX Parser Factory field, enter the following:

      org.apache.xerces.jaxp.SAXParserFactoryImpl
      

   7. Click Create.

Note:

If you are using SQL Server as the database and the Oracle Identity Manager log shows traces of exceptions related to MS JDBC classes, then you must add three MS JDBC files to the beginning of CLASSPATH in the startWebLogic script located in the domain directory, and restart the server.

Microsoft SQL Server is not supported in Oracle Identity Manager release 9.1.0. See ÒCertified ComponentsÓ in Oracle Identity Manager Release Notes for information about certified components.

Add the following files located in the /WebLogic81/server/lib/ directory to the beginning of CLASSPATH in the startWebLogic script, and restart the server:

• mssqlserver.jar

• msbase.jar

• msutil.jar

In a clustered installation, add these three JAR files in the Class Path field in the Remote Start tab of all Managed Servers.

WebLogic JMS Server Configuration Changes

Changing the WebLogic JMS Server configuration involves the following steps:

• Set the Redelivery Limit for JMS queues (xlQueue, xlReconQueue, xlProcessQueue, xlAuditQueue, and xlAttestationQueue) to 5.

• To improve performance, make the following changes for BEA WebLogic Server JMS servers:

  1. Log on to the WebLogic Server Administration Console.

  2. Navigate to Services, JMS, Servers, xlJMSServer, and then click the Thresholds & Quotas tab.

  3. Set Messages Threshold High to 250, Messages Threshold Low to 20, select Messages Paging Enabled, and then click Apply.

  Note:

  For a clustered installation of the BEA WebLogic Server, repeat the steps in this section for all the JMS servers with names starting with xlJMSServer, for example, xlJMSServerMyServer.

Setting the Transaction Timeout Parameter

To set the transaction timeout parameter:

1. Log in to the WebLogic Server Administration Console.

2. Navigate to Services, JTA, and then enter 1200 for in the Timeout Seconds field.

Copying the Oracle 10.2.0.3 JDBC JAR File in a Clustered Installation

In a BEA WebLogic Server clustered installation, perform the following (mandatory) procedure on all nodes except the first one on which Oracle Identity Manager is installed:

After backing up the ojdbc14.jar file, copy the file from the OIM_HOME/xellerate/ext directory to the BEA_HOME/weblogic81/server/lib directory.

Note:

In a nonclustered installation, the Oracle Identity Manager Installer automatically performs this procedure.

Shutting Down and Restarting BEA WebLogic Server

After performing the postinstallation tasks, shut down the application server gracefully and then restart it for the changes in settings to take effect. Refer to Chapter 8, "Starting and Stopping Oracle Identity Manager" for detailed information about starting and stopping the application server after deploying Oracle Identity Manager .

Optional Postinstallation Tasks

After installing Oracle Identity Manager, consider performing the following optional postinstallation tasks before using the application. Depending on the Oracle Identity Manager deployment, you might choose not to perform some of these tasks.

Note:

After performing any of the optional postinstallation tasks, shut down the application server gracefully and then restart it for the changes in settings to take effect. Refer to Chapter 8, "Starting and Stopping Oracle Identity Manager" for detailed information about starting and stopping the application server after deploying Oracle Identity Manager.

• Setting Log Levels

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

• Configuring Custom Authentication

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.

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

By default, Oracle Identity Manager is configured to provide output at the WARN level except for DDM, which is configured to provide output at the DEBUG level. You can change the log level universally for all components or for one or more individual component.

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

1. Open the OIM_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, as follows:

   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.

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, whereas 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.

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

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 can contain only English-language characters, the dash character (-), and the underscore character (_). Oracle recommends that you do not use special characters or numeric characters in header names.

To enable Single Sign-On for Oracle Identity Manager:

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

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

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

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

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 should 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 should be the first invoked authenticator.

To enable custom authentication on BEA WebLogic Server, you use the WebLogic Server Console, which allows you to add multiple authentication providers and invoke them in a specific order. The custom authentication provider that you specify will handle standard authentication requests, and the Oracle Identity Manager JAAS module will continue to handle signature-based authentication.

Note:

The custom authentication provider that you specify must come after the Oracle Identity Manager JAAS module in the WebLogic Server Console's list of authentication providers.

To specify a custom authentication provider for BEA WebLogic Server:

1. Start the WebLogic Server Console and open the Authentication Providers page from domain/Security/Realms/realm name/Providers/Authentication.

2. In the Authentication Providers page, select Oracle Identity Manager Authenticator from the table at the bottom of the page. The Oracle Identity Manager Authenticator page is displayed.

3. In the Oracle Identity Manager Authenticator page, select the Allow Custom Authentication option in the Details tab, and then click Apply.

4. In the Authentication Providers page, configure a new authentication provider by clicking the Configure a new ... link for the custom authentication provider that you want to add.

5. When you finish configuring the new authentication provider, confirm that it is listed after Oracle Identity Manager Authenticator (which is the Oracle Identity Manager JAAS module) in the list of authentication providers. If the Oracle Identity Manager Authenticator is not listed above your custom authentication provider, then click Reorder the Configured Authentication Providers.

Protecting the JNDI Namespace

When you specify a custom authentication solution, you should 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 should protect your JNDI namespace as a routine security measure.

To protect your JNDI namespace and configure Oracle Identity Manager to access it:

1. From the WebLogic Server Console:

   1. Right-click the server name and go to the JNDI tree view.

   2. Right-click the tree and then define the security policy.

   3. Specify the policy as User name of the caller xelsysadm or user name of the caller Internal.

      Note:

      For a clustered installation, repeat the steps for all the available servers in the domain where Oracle Identity Manager is installed.

2. 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>user</java.naming.security.principal>
   <java.naming.security.credentials>user_password</java.naming.security.credentials>
   

   For user, specify Internal. For user_password, enter the password for Internal.

3. 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 element's value, as follows:

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

   Note:

   To protect the plaintext password, it is strongly recommended that you add the encrypted="true" attribute.

4. 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>user_password
     </org.quartz.dataSource.OracleDS.java.naming.security.credentials></CustomProperties>
   

Troubleshooting the JNDI Namespace Configuration

If you create a user and that is the only user who can perform lookups, you might see the following exception when attempting to start Oracle Identity Manager where user_name represents the user you created to perform lookups:

[XELLERATE.ACCOUNTMANAGEMENT],Class/Method: Authenticate/connect User with ID: user_name was not found in Xellerate.
[XELLERATE.ACCOUNTMANAGEMENT],Class/Method: Authenticate/connect User with ID: user_name was not found in Xellerate.
[XELLERATE.ACCOUNTMANAGEMENT],Class/Method: XellerateLoginModuleImpl/login encounter some problems:
com.thortech.xl.security.tcLoginException:
  at com.thortech.xl.security.tcLoginExceptionUtil.createException(Unknown Source)
  at com.thortech.xl.security.tcLoginExceptionUtil.createException(Unknown Source)
  at com.thortech.xl.security.Authenticate.connect(Unknown Source)
  at com.thortech.xl.security.wl.XellerateLoginModuleImpl.login(Unknown Source)
  at weblogic.security.service.DelegateLoginModuleImpl.login(DelegateLoginModuleImpl.java:71)

To resolve this issue, refresh the embedded LDAP directory in the Managed Server with the LDAP directory in the Administrative Server after starting Oracle Identity Manager by using the following steps:

1. Log on to the WebLogic Server Administration Console.

2. Click the domain name for the Managed Server.

3. Click View Domain-wide security settings.

4. Click the Embedded LDAP tab.

5. Select the Refresh replica at startup option, and then click Apply.

Note:

You should only perform these steps once to resolve this issue, and you can disable the Refresh replica at startup option after restarting the Admin and Managed Servers.

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.

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