| Oracle® Identity Manager Installation Guide for WebSphere Release 9.0.3.1 Part Number B32462-02 |
|
|
View PDF |
| Oracle® Identity Manager Installation Guide for WebSphere Release 9.0.3.1 Part Number B32462-02 |
|
|
View PDF |
After installing Oracle Identity Manager, perform the post-installation tasks documented in this chapter that are appropriate for your deployment before using the application. Depending on your Oracle Identity Manager deployment, you may choose not to perform some of these tasks.
The following are the post-installation tasks documented in this chapter:
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:
Open the server.xml file in the following directory:
<WEBSPHERE_HOME>/config/cells/<cell name>/nodes/<node name>/servers/server1/
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"/>
Save and close the file.
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, as described in the following sections.
To use a nondefault HTTP port:
Select Environment, select Virtual Host, select default_host, then select Host Alias.
Click New.
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.Change the <ApplicationURL> tag in xlclient\config\xlconfig.xml to the correct HTTP port.
Restart the application server you used to install Oracle Identity Manager.
To use a nondefault naming service port:
To find the naming service port, use the WebSphere Administrative Console.
Click Server, select Application Server, select <server_name>, 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.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.
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.
Note:
In the following procedure, the name of the nondefault server is xlServer.To configure WebSphere on a nondefault server (named something other than server1):
Open the server.xml file in the following directory:
<WEBSPHERE_HOME>\config\cells\<cellname>\nodes\<nodename>\servers\server1\
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.Start the servers using the following command with arguments:
startServer <servername> –username xelsysadm -password xelsysadm
Note:
If you used a user name or password other than xelsysadm for WebSphere, enter those here.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 to 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:
Navigate to the following location:
<WEBSPHERE_HOME>\config\cells\<cell_name>
Open the file integral-jms-authorizations.xml in a text editor.
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.Add the line <userid>xelsysadm</userid>, so that it looks like the following:
<queue-admin-userids> <userid>xelsysadm</userid> </queue-admin-userids>
Save your changes.
Restart the server.
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. 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:
Launch the WebSphere administrative console.
Click Servers on the left pane and navigate to Application Servers, select <Server_Name>.
On the Configuration tab, scroll to the Additional Properties section, then select Message Listener Service, and click Listener Ports.
Click MessageHandlerMDB_JMSPort.
Modify maximum retries from 5 to a greater value.
Click OK and then click Save.
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:
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:
Open a command prompt on the Oracle Identity Manager host computer.
Navigate to the <XL_HOME>\xellerate\config directory.
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 |
|---|---|
|
|
Location of the Java directory associated with the application server |
|
|
New password for the keystore |
|
|
Keystore whose password you are changing (.xlkeystore for the Oracle Identity Manager server or .xldatabasekey for the database) |
|
|
JKS for .xlkeystore and JCEKS for .xldatabasekey |
Launch a plain-text editor, then open the following file:
<XL_HOME>\xellerate\config\xlconfig.xml
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>
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.
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
Oracle Identity Manager uses log4j for logging. Logging levels are 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—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.
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 <XL_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 <XL_HOME>\xellerate\config\log.properties file as described in the following procedure.
To configure log levels:
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.
Set the general value to the desired log level.
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
Save your changes.
Restart your application server so that the changes take effect.
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:
Stop the application server gracefully.
Launch a plain-text editor and open the following file:
<XL_HOME>\xellerate\config\xlconfig.xml
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>
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
Change your application server and web server configuration to enable Single Sign-On by referring to your application and web server vendor documentation.
Restart the application server.
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 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:
Start the WebSphere Administrative Console, expand Security and User Registries, and then click Custom. The Custom Properties page appears.
On the Custom Properties page, click New and define a property named customAuthentication. When you define the property, specify the name of a custom authentication class that implements com.ibm.websphere.security.UserRegistry, and also provide any required initialization parameters.
Restart the WebSphere application server.
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 configure Oracle Identity Manager to access a protected JNDI namespace, perform the following steps:
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>
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>
