2 Installing the Oracle Role Manager Integration Library

This chapter provides information you should know and the steps to perform before installing the Oracle Role Manager Integration Library with Oracle Identity Manager in your environment for the first time.

Note:

If you have a previous installation of Oracle Role Manager Integration Library, see Chapter 3, "Upgrading the Oracle Role Manager Integration Library."

This chapter includes the following sections:

Verifying Requirements
Before You Start
Overview of Installation and Deployment steps
Distributing the Oracle Role Manager Integration Library Software
Configuring the Commons Logging Level
The Integration Library Files and Directories
Determining the Release Number of the Integration Library

2.1 Verifying Requirements

Table 2-1 lists the requirements for the three supported configurations of Oracle Role Manager Integration Library 10.1.4.2 with Oracle Identity Manager 9.1.0.2. For detailed requirements, such as JDK certification, see Oracle Role Manager Release Notes.

Table 2-1 Supported Configurations

Oracle Role Manager	Oracle Identity Manager
Oracle Role Manager release 10.1.4.2 on JBoss 4.2.3.	Oracle Identity Manager release 9.1.0.2 on JBoss 4.2.3.

Oracle Role Manager release 10.1.4.2 on WebSphere 6.1.0.21.	Oracle Identity Manager release 9.1.0.2 on WebSphere 6.1.0.21

Oracle Role Manager release 10.1.4.2 on WebLogic 10.3.	Oracle Identity Manager release 9.1.0.2 on WebLogic 10.3

2.2 Before You Start

Before you begin the deployment of the Oracle Role Manager Integration Library the following prerequisites must be met:

Oracle Role Manager
- Oracle Role Manager has been installed and the standard model has been deployed following the instructions in Oracle Role Manager Installation Guide.
- The database instance for Oracle Role Manager has been started.
- Oracle Role Manager has been successfully deployed on the application server.
- The application server for Oracle Role Manager is not running.
Oracle Identity Manager
- You have WRITE permission on the directories specified for deployment and appropriate permissions on the parent directories for subdirectories to be created.
- You have access to file system on the Oracle Identity Manager host.
- You know the Oracle Identity Manager administrator user name and password to access both the Design Console and the Administrative and User Console.
- The application server for Oracle Identity Manager is on the same host as the Oracle Identity Manager installation directory.

If any of these prerequisites are not met, see Oracle Role Manager Installation Guide and Oracle Identity Manager Installation Guide for more information.

Note:

It is recommended that Oracle Role Manager and Oracle Identity Manager are deployed on separate hosts to avoid port conflicts.

2.3 Overview of Installation and Deployment steps

The following list outlines the high-level steps of installing, configuring, and deploying Oracle Role Manager with the Integration Library.

Ensure that all the prerequisites and requirements are met as described in Section 2.1 and Section 2.2.
Prepare Oracle Role Manager with the Integration Library configuration and business model.
Prepare Oracle Identity Manager for the integration (modify startup command, import configuration, create the Oracle Role Manager user, and create a system property).
Prepare the Oracle Identity Manager application server for deployment and deploy the Integration Library application.
Test the installation and configuration using procedures in Chapter 10 (user and role reconciliation, group membership reconciliation, and approval role resolution).

2.4 Distributing the Oracle Role Manager Integration Library Software

Distribute the Oracle Role Manager Integration Library software onto the application server host where Oracle Identity Manager is deployed as described in this section.

Certain files must be distributed into Oracle Identity Manager directories, as described in this section. For a detailed description of the individual files in the Integration Library, see Section 2.6.

Note:

The Integration Library must be installed on the same host as Oracle Identity Manager.

Note:

If you have a clustered server configuration, the Integration Library software files must be distributed on all managed nodes.

Note:

If you are configuring the Integration Library on WebLogic, and plan to use the automated configuration scripts, perform only the first two steps in the following procedure. The JAR files and class files will be automatically copied as part of the automated configuration.

To access and distribute the software:

On the Oracle Role Manager installation host, navigate to ORM_HOME/Integration_Library.
Copy the contents of the Integration_Library directory to a directory that will become the ORMINT_HOME root directory on the Oracle Identity Manager application server.

Note:
You may want to create and name the root directory such as C:\ORMINT_HOME for convenience. To avoid confusion, this guide refers to this directory in uppercase italic as with other home directory variables.
Make a note of the root directory for application server configuration later in this guide. For more information, see the application server configuration sections.
On the Oracle Identity Manager host, copy the following files into OIM_HOME/xellerate/EventHandlers:
```
ORMINT_HOME/oimlib/OIM-IntegrationSupport.jar
ORMINT_HOME/oimlib/OIM-IntegrationTransport.jar
```

Copy the following files into OIM_HOME/xellerate/JavaTasks:

ORMINT_HOME/oimlib/OIM-Integration.jar
ORMINT_HOME/lib/server_api_14.jar
ORMINT_HOME/lib/websphere_stubs.jar (For WebSphere only)

Copy the following files into OIM_HOME/xellerate/ScheduleTask.

ORMINT_HOME/oimlib/ScheduledAccessPoliciesReconciliation.class
ORMINT_HOME/oimlib/ScheduledEntitlementReconciliation.class
ORMINT_HOME/oimlib/ScheduledFullEntitlementReconciliation.class
ORMINT_HOME/oimlib/ScheduledFullUserReconciliation.class
ORMINT_HOME/oimlib/ScheduledIntegrationTask.class
ORMINT_HOME/oimlib/ScheduledQuickEntitlementReconciliation.class
ORMINT_HOME/oimlib/ScheduledQuickUserReconciliation.class
ORMINT_HOME/oimlib/ScheduledRoleReconciliation.class
ORMINT_HOME/oimlib/ScheduledUserGroupsCleanup.class
ORMINT_HOME/oimlib/ScheduledUserGroupsReconciliation.class
ORMINT_HOME/oimlib/ScheduledUserReconciliation.class

2.5 Configuring the Commons Logging Level

It can be helpful to enable logging for the Integration Library application on the application server. This optional procedure sets the logging level to use when logging is enabled in the application server. The procedures for enabling logging in the application server can be found in the appropriate application server configuration sections later in this document.

Note:

If you have a clustered server configuration, this procedure must be followed for each managed server.

To set up commons logging for the Integration Library:

On the Oracle Identity Manager host, navigate to ORMINT_HOME/config.
Open the logging.properties file with a text editor.
Add the Integration Library log level to the file. For example:
```
oracle.iam.rm.imframework.level=FINEST
```
Save and close the logging.properties file.

2.6 The Integration Library Files and Directories

Table 2-2 describes the files required by the Integration Library. It is recommended that you familiarize yourself with these files as several of them must be copied to different locations or edited for configuration.

Table 2-2 Oracle Role Manager Integration Library Files

File in Integration Library Home	Description
MANIFEST.MF	Contains version information for the deployed integration code.
readme.txt	Contains a pointer to this guide.
bin/
create_ear.bat create_bat.sh	Script that creates the Integration Library application EAR file that is bundled with JAR files from the local installation of Oracle Identity Manager.
create_keystore.bat create_keystore.sh	Script that creates the key store password and stores it to a file named keystore.store, creates a random symmetric key for that password and serializes it to a file named keystore.key, and creates a property file named keystore.properties and adds a single property whose value is a base64-encoded encrypted value of the key store password, encrypted using the symmetric key.
create_key_pair.bat create_key_pair.sh	Script that creates an asymmetric key pair for the provided alias and the certificate target file. It adds a property to keystore.properties called alias.password, for the provided alias whose value is a base64-encoded encrypted value of the alias password, encrypted using the symmetric key.
import_certificate.bat import_certificate.sh	Script that reads the public key (in X.509 format) from the provided certificate file, accesses the key store with the provided password, and adds the certificate to the key store with the provided alias.
config/
IMConfig.xml	Shared by the integration code handling incoming messages and the Oracle Role Manager Integration Library functionality contained in the Oracle Identity Manager extension directories (JavaTasks, EventHandlers, and ScheduleTask). This file contains the editable prefix that is used to identify user groups in Oracle Identity Manager that correspond with roles in Oracle Role Manager. The default value is either ORM_AR, ORM_BR, or ORM_IR followed by an underscore (`_`) that is added by the system. The XML schema definition that governs this file is oracle.iam.rm.imframework.imconfig_1_0.xsd located in ORMINT_HOME/schema.
jboss_config.car	Contains the configuration needed to support the attachment of authentication credentials in JMS messages from JBoss.
logging.properties	Used for setting the logging level for the Integration Library.
oim_integration.car	Contains the extensions to the standard model (data model and business logic) necessary for the Integration Library to function with Oracle Identity Manager. This file is manually copied to ORM_HOME/config for deployment convenience.
oim_systemIdentity.car	Contains the configuration that when deployed, configures the oimSystem system identity for connections to the Oracle Identity Manager system. This file is manually copied to ORM_HOME/config for deployment convenience.
oim_systemIdentity.dar	Contains the data that must be loaded to complete the creation of the oimSystem system identity. This file is manually copied to ORM_HOME/config for deployment convenience.
ormoimBase.xml	Contains the base Oracle Identity Manager c onfiguration needed to support the Integration Library. The settings in this file are manually imported into Oracle Identity Manager.
websphere_config.car	Contains the configuration needed to support the attachment of authentication credentials in JMS messages from WebSphere. This file is manually copied to ORM_HOME/config for deployment convenience.
lib/
commons-logging.jar	Contains logging libraries needed to support J2EE 1.3 logging. For WebLogic, this file is manually added as a shared library. NOTE: This file is needed only if Oracle Identity Manager is deployed on WebLogic.
orm_encryption.jar	Contains classes supporting PKI encryption/decryption and utilities for the management of public and private keys used for the encryption/decryption process. Contained classes are JDK 1.4 compatible. For JBoss, the file is manually copied to JBOSS_HOME/server/default/lib. For other application servers, this file is added as a shared library.
roleManagerIntegration_JBoss4.2.3.ear.template roleManagerIntegration_WebLogic10.3.ear.template roleManagerIntegration_WebSphere6.1.ear.template	Template used by the create_ear command. Responsible for the initial handling of messages arriving from Oracle Role Manager. This is a J2EE enterprise archive containing a message-driven bean (MDB) and support code. Its core functionality is extended by Java code and configurations deployed in the Integration Library plug-in directories. For JBoss, the file is manually copied to OIM_appserver/deploy as part of the deployment process. For other application servers, this file is deployed through the administrative console user interface.
server_api_14.jar	Contains additional shared libraries required for a deployment on an application server (a copy is also located in OIM_HOME/xellerate/JavaTasks). For JBoss, this file is manually copied to OIM_appserver/lib and OIM_HOME/xellerate/JavaTasks. For other application servers, this file is added as a shared library.
websphere_stubs.jar	Contains the generated stubs of the Role Manager public API, which is provided through an Enterprise Java Bean (EJB). Such stubs are required for remote invocation of EJBs. This file is manually added to the WebSphere application server configuration as a shared library. NOTE: This file is needed only if Identity Manager is deployed on WebSphere.
xercesImpl.jar xml-apis.jar	Contains libraries needed to support J2EE 1.3 JAXP 1.1 for XML parsing. If running the WebLogic configuration script, these files are automatically added to the OIM_appserver/jdk/jre/lib/endorsed directory. NOTE: These files are not needed if Oracle Identity Manager is deployed on JBoss.
oimlib/
OIM-Integration.jar	Contains the class files for handling approval role resolution between roles in Oracle Role Manager and user groups in Oracle Identity Manager. This file is copied to OIM_HOME/xellerate/JavaTasks.
OIM-IntegrationSupport.jar	Contains the class files that support the underlying integration framework (a copy is also located in `EventHandlers`). This file is copied to OIM_HOME/xellerate/EventHandlers.
OIM-IntegrationTransport.jar	Contains the class files that support sending messages from the integration to Oracle Role Manager. This file is copied to OIM_HOME/xellerate/EventHandlers. For JBoss, this file is also copied to JBOSS_HOME/server/default/lib.
ScheduledAccessPoliciesReconciliation.class	Task for reconciliation of Oracle Identity Manager access policies. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledEntitlementReconciliation.class	Base task used by the entitlement scheduled tasks. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledFullEntitlementReconciliation.class	Task for reconciliation of newly created, updated, and deleted Oracle Identity Manager entitlements. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledFullUserReconciliation.class	Task for Full reconciliation of users including synchronous inspection of the Oracle Role Manager state. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledIntegrationTask.class	Base task used by all other Oracle Role Manager scheduled tasks. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledQuickEntitlementReconciliation.class	Task for reconciliation of newly created and updated Oracle Identity Manager entitlements. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledQuickUserReconciliation.class	Task for reconciliation of new, updated, and deleted users based on an input timestamp. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledRoleReconciliation.class	Task to reconcile Oracle Role Manager roles and Oracle Identity Manager user groups. Cleans up any deleted user groups on Oracle Identity Manager where there is no corresponding role in Oracle Role Manager. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledUserGroupsCleanup.class	Task used as part of the upgrade process to remove user groups that were created as a part of Oracle Role Manager role updates. Because the current version of Oracle Role Manager has Entitlements instead of IT roles, this task also removes entitlements and user groups from the access policies that were created as a result of IT role updates in the previous version of Oracle Role Manager Integration Library. This file is copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledUserGroupsReconciliation.class	Task for one-time import of Oracle Identity Manager user groups. On running this task all Oracle Identity Manager user groups are created as Business Roles in Oracle Role Manager. This file is manually copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledUserReconciliation.class	Base task used by the user reconciliation scheduled tasks. Sends all Oracle Identity Manager user records to Oracle Role Manager except for system user records. This file is manually copied to OIM_HOME/xellerate/ScheduleTask.
pluginConfigdir/	Contains XML files of handler configurations that map message types for messages arriving from Oracle Role Manager to plug-in Java code that handles the messages. Also contains the XML schema definitions required to interpret the message payloads. Note: Integrators who add functionality to the integration can add their own XML files to this directory. A new XML handler configuration must be created for each additional message type.
ApprovalRequestHandler.xml ApproverRolePublishing.xml BusinessRolePublishing.xml ITRolePublishing.xml RoleDeletion.xml
pluginSchema/	Contains the XML schema definitions for interpreting payloads sent in messages from Oracle Role Manager. These definitions must exactly correspond with the schema of the business logic plug-ins in Oracle Role Manager used by the originators of the messages. Note: Integrators who add functionality to the integration can add their own XML schema files to this directory. The provided XSD files are (prepended by oracle.iam.rm.bizlogic to be fully qualified).
approvalrequest_1_0.xsd objectdeletion_1_0.xsd roleusersassignment_1_0.xsd
samples/
ormoimSample.xml	The file used to import a sample approval workflow into Oracle Identity Manager. This is used when testing the installation as described in Section 10.6, "Testing Approver Role Resolution."
samples/jboss/
oimorm-service.xml	Sample configuration for the JMS queues required to support the Oracle Role Manager Integration Library . Some values in this file can be modified to reflect the actual deployment environment, for example, to change the queue names if the default values were not used. This file is manually copied to OIM_appserver/deploy. This file is only applicable to JBoss. Other application servers provide a Web-based administration console to use for JMS queue configuration.
ormoim-service.xml	Configuration file for the JMS queues required to support the Integration Library on the Oracle Role Manager application server. Some values in this file can be modified to reflect the actual deployment environment, for example, to change the queue names if the default values were not used. This file is manually copied to ORM_appserver/deploy. Other application servers provide a Web-based administration console to use for JMS queue configuration.
schema/	Contains the standard XML schema used by the Integration Library. Unlike the three previous directories, there is no requirement to add new files to this directory when adding integration functionality. The schema file names are prepended with oracle.iam.rm to be fully qualified.
event.event_1_0.xsd	Description of the standard Oracle Role Manager event type to which messages sent from Oracle Role Manager to Oracle Identity Manager adhere.
imframework.imconfig_1_0.xsd	Schema of the Oracle Role Manager Integration Library configuration file (IMConfig.xml).
imframework.pluginconfig_1_0.xsd	Schema of the files in the Oracle Role Manager Integration Library pluginConfigdir directory.
tools/Weblogic_Automation	Contains the scripts used for automatic configuration of the Oracle Role Manager Integration Library on a single WebLogic deployment.

2.7 Determining the Release Number of the Integration Library

Release information for the Oracle Role Manager Integration Library is stored in a manifest file.

To find the release number:

On the command line, navigate to the directory where the Oracle Role Manager Integration Library software was installed:
View the contents of the MANIFEST.MF file.

In this file you can view the version number, build number, build label, and build date of the Integration Library.