7 Post-Install Configuration for Oracle Identity Manager Server and JBoss

After installing Oracle Identity Manager, you should considering performing the post-installation tasks documented in this chapter before using the application. Depending on your Oracle Identity Manager deployment, you may choose not to perform some of these tasks. The following is a list of the post-installation tasks documented in this chapter:

• Reserving JBoss Ports on Windows Installations

• Changing Keystore Passwords

• Setting Log Levels

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

• Configuring Multiple JBoss Installations to Use a Single Database

• Configuring Custom Authentication

Note:

The examples in this chapter are Windows-based, however the post-installation tasks apply to UNIX and Linux as well.

Reserving JBoss Ports on Windows Installations

Perform the following steps to reserve the necessary ports for JBoss on Windows installations:

1. Select Run from the Windows Start menu. The Run dialog box displays.

2. Enter regedt32 in the Run dialog box and click the OK button. The Registry Editor window appears.

3. Navigate to the following registry key:

   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
   
   

4. 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 the Enter key.

5. Double-click the ReservedPorts value. The Edit Multi-String dialog box appears.

6. In the Edit Multi-String dialog box, enter 1098-1434 in the Value data box.

7. Click the OK button to close the Edit Multi-String dialog box, and then close the Registry Editor window.

Changing Keystore Passwords

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. Oracle recommends changing the keystore passwords for all production installations. You can use the keytool to change the keystore password for either keystore.

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
   
   

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

   Table 7-1 Command Options for keytool

   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 the Oracle Identity Manager server or .xldatabasekey for the database)
   -storetype <option>	JKS for .xlkeystore and JCEKS for .xldatabasekey

   
   

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

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.

   Note:

   On UNIX or Linux, you may also want to clear the shell's command history by using the following command:

   history -c

Setting Log Levels

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

By default, Oracle Identity Manager is configured to output at the Warning level—except for DDM, which is configured to output at the Debug level 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 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=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

Setting Log Levels for JBoss

The log4j.xml file is used for all logging with JBoss; 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 the Oracle Identity Manager server, 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:

1. Open the file <JBOSS_HOME>\server\default\conf\log4j.xml in a text editor.

2. Insert an element for the desired component.

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

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

See Also:

Oracle Identity Manager Best Practices Guide for additional 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 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. Launch a plain-text editor and open the following file:

   <XL_HOME>\xellerate\config\xlconfig.xml

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 your application server and web server configuration to enable Single Sign-On by referring to your application and web server vendor documentation.

6. Restart the application server.

Configuring Multiple JBoss Installations to Use a Single Database

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

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

1. Launch a plain-text editor, navigate to the directory <JBOSS_HOME>\server\default\deploy\jms, then open the file <database_name>-jdbc2-service.xml.

   Note that <database_name> refers to the common database used by multiple JBoss instances.

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

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

4. Save and close the file.

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:

1. Open the <XL_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>
   
   

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

3. Copy your custom authentication JAR file to the <JBOSS_HOME>/server/default/lib directory.

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 may 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. Open the <XL_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 element's value, 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>