7 Postinstallation Configuration for Oracle Identity Manager and JBoss Application Server

After installing Oracle Identity Manager, you must complete some postinstallation tasks before using the application. Depending on the deployment, you might choose not to perform some of these tasks. The following is a list of the postinstallation tasks documented in this chapter:

Default JMS Queue Configuration
Reserving JBoss Application Server Ports on Microsoft Windows Installation
Changing Keystore Passwords
Setting Log Levels
Enabling Single Sign-On (SSO) for Oracle Identity Manager
Configuring Multiple JBoss Application Server Installations to Use a Single Database
Configuring Custom Authentication
Setting the Compiler Path for Adapter Compilation
Encrypting Oracle Identity Manager Database Password in the xell-ds.xml File for JBoss Application Server
Deploying the SPML Web Service
Tuning JDBC Connection Pools

Note:

The examples in this chapter are Microsoft Windows-based, however the postinstallation tasks apply to UNIX as well.

7.1 Default JMS Queue Configuration

In releases earlier than 9.1.0, Oracle Identity Manager uses a single JMS queue (named xlQueue) for all asynchronous operations including requests, reconciliation, attestation, and offline tasks. 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 Reserving JBoss Application Server Ports on Microsoft Windows Installation

Perform the following steps to reserve the necessary ports for JBoss Application Server on Microsoft Windows installation:

Select Run from the Windows Start menu. The Run dialog box is displayed.
Enter regedt32 in the Run dialog box and click OK. The Registry Editor window is displayed.

Navigate to the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

If it does not already exist, create a ReservedPorts value, as follows:
1. Point to New on the Edit menu and click Multi-String Value.
2. Enter ReservedPorts as the value name and press Enter.
Double-click the ReservedPorts value. The Edit Multi-String dialog box is displayed.
In the Edit Multi-String dialog box, enter 1098-1434 in the Value data box.
Click OK to close the Edit Multi-String dialog box, and then close the Registry Editor window.

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

Open a command prompt on the Oracle Identity Manager host computer.
Navigate to the OIM_HOME\xellerate\config directory.

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

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

Open OIM_HOME\xellerate\config\xlconfig.xml in a text editor.

Edit the <xl-configuration>.<Security>.<XLPKIProvider>.<KeyStore> section, <xl-configuration>.<Security>.<XLPKIProvider>.<Keys> section, and <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 (in the clear), 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>

Save and close the xlconfig.xml file.
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.
If all of the preceding steps have succeeded, you can delete the backup file.

Note:
On UNIX, you might also want to clear the shell's command history by using the following command:
history -c

7.4 Setting Log Levels

Oracle Identity Manager uses log4j for logging. For JBoss-based installations, logging is configured in the log4j.xml file.

By default, the log level is set to Warning, except for DDM, for which the log level is set to Debug by default. You can change the log level universally for all components or for an individual component. For normal operation of Oracle Identity Manager, this postinstallation configuration step is not required.

7.4.1 Oracle Identity Manager Component Logging

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

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

7.4.2 Setting Log Levels for JBoss Application Server

The log4j.xml file is used for all logging with JBoss Application Server; therefore, Oracle Identity Manager components use an Xellerate tag. The log4j.xml file contains a general setting for Xellerate:

<category name="XELLERATE">
  <priority value="WARN" />
</category>

You can change the log level for all components by editing the priority value of the general setting, or for a specific component by adding a new logging category element.

The available categories are listed in the log.properties file in the XELLERATE section. See Oracle Identity Manager Component Logging for more information.

For example, to change the level for Oracle Identity Manager, add the following element to the log4j.xml file:

<category name="XELLERATE.SERVER">
  <priority value="WARN" />
  <appender-ref ref="FILE"/>
</category>

To set Oracle Identity Manager log levels in JBoss Application Server:

Open the JBOSS_HOME\server\default\conf\log4j.xml file in a text editor.
Insert an element for the desired component.
Set the priority value to the appropriate level for the desired components.

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
Save your changes.

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

7.6 Configuring Multiple JBoss Application Server Installations to Use a Single Database

When two or more non-clustered JBoss Application Server installations connected to a load balancer point to a single database, you must configure the individual JBoss Application Server instances to use different JMS tables.

Complete the following procedure on the second and all other JBoss Application Server instances by using the same Oracle Identity Manager database so they use different JMS tables:

Open the JBOSS_HOME\server\default\deploy\jms\database_name-jdbc2-service.xml in a text editor.

Note that database_name refers to the common database used by multiple JBoss Application Server instances.
In all the queries and statements in the sqlProperties section of the database_name-jdbc2-service.xml, change the names of the tables represented by JMS_MESSAGES and JMS_TRANSACTIONS to new, unique, and valid values.

Add the following statements to the end of the file:

DELETE_TEMPORARY_MESSAGES = DELETE FROM NEW_JMS_MESSAGES_NAME
    WHERE TXOP='T'
CREATE_IDX_MESSAGE_TXOP_TXID = CREATE INDEX
    NEW_JMS_MESSAGES_NAME_TXOP_TXID ON NEW_JMS_MESSAGES_NAME (TXOP, TXID)
CREATE_IDX_MESSAGE_DESTINATION = CREATE INDEX
    NEW_JMS_MESSAGES_NAME_DESTINATION ON NEW_JMS_MESSAGES_NAME(DESTINATION)

Note:

NEW_JMS_MESSAGES_NAME represents the new name of the JMS_MESSAGES tables you changed in step 2.

Save and close the file.

7.7 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 your application server and should be the first invoked authenticator.

To enable custom authentication on JBoss Application Server, you implement a custom authentication module class. Oracle Identity Manager will then delegate standard authentication requests to the custom authentication module.

To implement custom authentication for JBoss Application Server:

Open the OIM_HOME\config\xlconfig.xml file in a text editor and add the following element, replacing CustomLoginModule with the name of your custom login module class.
```
<login-module>
     <thirdPartyLoginModule>CustomLoginModule</thirdPartyLoginModule>
</login-module>
```

Optional. Specify configuration properties for the custom authentication module by opening the JBOSS_HOME\config\login-config.xml file in a text editor and adding a module option within the <login-module> element for the com.thortech.xl.security.jboss.UsernamePasswordLoginModule package. Oracle Identity Manager will delegate the specified properties to the custom authentication module class. For example, the following rolesProperties module option will be delegated to the custom authentication module class.

<application-policy name = "xellerate">
    <authentication>
      <login-module
        code="com.thortech.xl.security.jboss.XLClientLoginModule"
        flag="required">
      </login-module>
      <login-module code=
          "com.thortech.xl.security.jboss.UsernamePasswordLoginModule"
           flag = "required" >
         <module-option name =
           "unauthenticatedIdentity">Unknown</module-option>
         <module-option name = 
           "data-source">java:/jdbc/xlDS</module-option>
         <module-option name = 
           "rolesProperties">customRoleProperties</module-option>
      </login-module>    </authentication>
  </application-policy>

Copy your custom authentication JAR file to the JBOSS_HOME\server\default\lib directory.

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

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>
```
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>
```

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>

7.7.2 Increasing the Transaction Timeout

You might have to increase the transaction timeout values for JBoss Application Servers, as the default values can be low for certain transactions. Oracle recommends the values specified in the following step:

Open the JBOSS_HOME\server\default\conf\jboss-service.xml file and ensure that transaction timeout attribute value is set to 1200 as follows:

<attribute name="TransactionTimeout">1200</attribute>

Note:

- For clustered JBoss Application Server, the corresponding file is located at JBOSS_HOME\server\all\conf\jboss-service.xml.

- JBoss Application Server clustered environments are not supported in Oracle Identity Manager release 9.1.0. See "Certified Components" in Oracle Identity Manager Release Notes for information about certified components.

7.8 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. See 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.9 Encrypting Oracle Identity Manager Database Password in the xell-ds.xml File for JBoss Application Server

By default, JBoss Application Server does not encrypt data source passwords, as described in the JBoss document at

http://wiki.jboss.org/wiki/Wiki.jsp?page=EncryptingDataSourcePasswords

This section describes how to encrypt the Oracle Identity Manager database password in JBoss Application Server deployments. Specifically, you must perform the following steps to manually encrypt a password, and then modify the xell-ds.xml and login-config.xml files so that they can access the encrypted form of the password instead of the clear text version:

Note:

For a clustered installation, repeat this procedure on all the nodes of the cluster.

Open a console window and navigate to the JBOSS_HOME directory.

Run one of the following commands to encrypt the Oracle Identity Manager database password. In this command, replace password with the actual password that you want to encrypt.

UNIX/Linux

java -cp "JBOSS_HOME/lib/jboss-jmx.jar:lib/jboss-common.jar:server/ default/lib/jboss-jca.jar:server/default/lib/jbosssx.jar"org.jboss.resource.security.SecureIdentityLoginModule password

Microsoft Windows

java -cp "JBOSS_HOME/lib/jboss-jmx.jar;lib/jboss-common.jar;server/ default/lib/jboss-jca.jar;server/default/lib/jbosssx.jar" org.jboss.resource.security.SecureIdentityLoginModule password

The command you run in the previous step returns an encoded form of the password you specify. For example, the password Welcome1 is encoded as 3146f9cc50afd6a6df8592078de921bc. Highlight and copy the encoded password.
Open the JBOSS_HOME/server/default/deploy/xell-ds.xml file in a text editor.
Delete the <user-name> and <password> elements from the <local-tx-datasource> element.
Add the following <security-domain> element to the end of the <local-tx-datasource> element:
```
<security-domain>EncryptDBPassword</security-domain>
```
Delete the <xa-datasource-property name="User"> and <xa-datasource-property name="Password"> elements from the <xa-datasource> element.
Add the following <security-domain> element to the end of the <xa-datasource> element:
```
<security-domain>EncryptXADBPassword</security-domain>
```
Save and close the JBOSS_HOME/server/default/deploy/xell-ds.xml file.
Open the JBOSS_HOME/server/default/conf/login-config.xml file in a text editor.

Add the following elements to the <application-policy> element:

Note:

Replace datasource_username with the datasource user name and encoded_password with the encoded password you copy in Step 3.

<application-policy name = "EncryptDBPassword">
 <authentication>
  <login-module code = "org.jboss.resource.security.SecureIdentityLoginModule" flag = "required">
   <module-option name = "username">datasource_username</module-option>
   <module-option name = "password">encoded_password</module-option>
   <module-option name = "managedConnectionFactoryName">jboss.jca:service=LocalTxCM,name=jdbc/xlDS</module-option>
  </login-module>
 </authentication>
</application-policy>

<application-policy name = "EncryptXADBPassword">
 <authentication>
  <login-module code = "org.jboss.resource.security.SecureIdentityLoginModule" flag = "required">
   <module-option name = "username">datasource_username</module-option>
   <module-option name = "password">encoded_password</module-option>
   <module-option name = "managedConnectionFactoryName">jboss.jca:service=XATxCM,name=jdbc/xlXADS</module-option>
  </login-module>
 </authentication>
</application-policy>

Save and close the JBOSS_HOME/server/default/deploy/login-config.xml file.

7.10 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 must 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.

7.11 Tuning JDBC Connection Pools

To implement tuning for the JDBC connection pools used by Oracle Identity Manager, open JBOSS_HOME/server/default/deploy/xell-ds.xml file and implement the following changes:

Note:

- For a clustered installation of Oracle Identity Manager on JBoss Application Server, the xell-ds.xml file can be located at JBOSS_HOME/server/all/farm.

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

For jdbc/xlDS pool, insert the following before the line </local-tx-datasource>:

<min-pool-size>30</min-pool-size>
<max-pool-size>50</max-pool-size>
<blocking-timeout-millis>15000</blocking-timeout-millis>
<idle-timeout-minutes>15</idle-timeout-minutes>

For jdbc/xlXADS pool, insert the code mentioned in step 1 before the line </xa-datasource>.
Restart JBoss Application Server.