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 (Role Manager) Integration Library with Oracle Identity Manager (Identity Manager) in your environment.

This chapter includes the following sections:

Verifying Requirements
Before You Start
Overview of Installation and Deployment steps
Obtaining the Role Manager Integration Library Software
Distributing the Integration Library Software
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 Role Manager Integration Library with Oracle Identity Manager. 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.1.1 on JBoss 4.2.3.	Oracle Identity Manager release 9.1.0.1 on JBoss 4.2.3.
Oracle Role Manager release 10.1.4.1.1 on WebLogic 10.3.	Oracle Identity Manager release 9.1.0.1 on WebLogic 10.3

2.2 Before You Start

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

Role Manager
- 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 Role Manager has been started.
- Role Manager has been successfully deployed on the application server.
- The application server for Role Manager is not running.
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 Identity Manager host.
- You know the Identity Manager administrator user name and password to access both the Design Console and the Administrative and User Console.
- The application server for Identity Manager is on the same host as the Identity Manager installation directory.

If any of the Role Manager prerequisites are not met, see Oracle Role Manager Installation Guide for instructions.

Note:

It is recommended that Role Manager and 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 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.
Obtain and distribute the Role Manager Integration Library software files.
Prepare Role Manager with the Integration Library configuration and business model.
Prepare Identity Manager for the integration (modify startup command, import configuration, create the Role Manager user, and create a system property).
Prepare the Identity Manager application server for deployment and deploy the Integration Library application.
Test the installation and configuration using procedures in Chapter 7 (user and role reconciliation, group membership reconciliation, and approval role resolution).

2.4 Obtaining the Role Manager Integration Library Software

Copy the Role Manager Integration Library software onto the application server host where Identity Manager is deployed as described in the following procedure.

Note:

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

To obtain the software:

From the application server host where Identity Manager is deployed, go to the following address using a Web browser:
```
http://www.oracle.com/technology/software
```
Click Identity Management.
Accept the Oracle license terms.
Click the link next to Oracle Role Manager Integration Library and save the ORMIntegration_OIM.zip file to a temporary location.
Extract the contents of the zip file to the location to contain the root installation directory for the Integration Library.

Note:
When selecting the root directory, consider that the zip file by default creates the directory ORMINT_HOME into which the Integration Library files are extracted. For example, if you choose C:\, the files is be placed into C:\ORMINT_HOME.
The Integration Library expects to find its configuration and binary files in ORMINT_HOME. If you change the name of this directory, you must also change it in the application server configuration. For more information, see the application server configuration sections. To avoid confusion, this guide refers to this directory in uppercase italic as with other home directory variables.

For a detailed description of the individual files in the Integration Library, see Section 2.6.

2.5 Distributing the Integration Library Software

After you have extracted the files from the downloaded zip file, you must distribute some of those files into Identity Manager directories as described in this section.

Note:

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

To distribute the Integration Library software:

On the 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

Copy the following files into OIM_HOME/xellerate/ScheduleTask.

ORMINT_HOME/oimlib/ScheduledFullUserReconciliation.class
ORMINT_HOME/oimlib/ScheduledIntegrationTask.class
ORMINT_HOME/oimlib/ScheduledRoleReconciliation.class
ORMINT_HOME/oimlib/ScheduledUserReconciliation.class

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 many 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_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 new 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 Role Manager Integration Library functionality contained in the Identity Manager extension directories (JavaTasks, EventHandlers, and ScheduleTask). This file contains the editable prefix that is used to identify user groups in Identity Manager that correspond with roles in Role Manager. The default value is ORM followed by an underscore (`_`) that is added by the system.
oim_integration.car	Contains the extensions to the standard model (data model and business logic) necessary for the Integration Library to function with Identity Manager. This file is manually copied to ORM_HOME/config for deployment convenience.
oim_systemIdentity.car	Contains the configuration that once deployed, configures the oimSystem system identity for connections to the 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 Identity Manager c onfiguration needed to support the Integration Library. The settings in this file are manually imported into Identity Manager.
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 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 manually added as a shared library.
roleManagerIntegration_JBoss4.2.3.ear roleManagerIntegration_WebLogic10.3.ear	Responsible for the initial handling of messages arriving from 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 manually 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 manually added as a shared library.
xercesImpl.jar xml-apis.jar	Contains libraries needed to support J2EE 1.3 JAXP 1.1 for XML parsing. These files are manually added to the OIM_appserver/jdk/jre/lib/endorsed directory. NOTE: These files are needed only if Identity Manager is deployed on WebLogic. If Identity Manager is on JBoss, these files are not used.
oimlib/
OIM-Integration.jar	Contains the class files for handling approval role resolution between roles in Role Manager and user groups in Identity Manager. This file is manually 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 manually copied to OIM_HOME/xellerate/EventHandlers.
OIM-IntegrationTransport.jar	Contains the class files that support sending messages from the integration to Role Manager. This file is manually copied to OIM_HOME/xellerate/EventHandlers. For JBoss, this file is also copied to JBOSS_HOME/server/default/lib.
ScheduledFullUserReconciliation.class	Task for Full reconciliation of users including synchronous inspection of the Role Manager state. This file is manually copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledIntegrationTask.class	Base task used by all other Role Manager scheduled tasks. This file is manually copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledRoleReconciliation.class	Inspects the state of roles in Role Manager. This file is manually copied to OIM_HOME/xellerate/ScheduleTask.
ScheduledUserReconciliation.class	Sends all Identity Manager user records to 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 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.
RoleDeletion.xml RoleUsersAssignment.xml
pluginSchema/	Contains the XML schema definitions for interpreting payloads sent in messages from Role Manager. These definitions must exactly correspond with the schema of the business logic plug-ins in 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).
objectdeletion_1_0.xsd roleusersassignment_1_0.xsd
samples/
ormoimSample.xml	The file used to import a sample approval workflow into Identity Manager. This is used when testing the installation as described in Section 7.3, "Testing Approval Role Resolution."
samples/jboss/
oimorm-service.xml	Sample configuration for the JMS queues required to support the Role Manager Integration Library . The values in this file can be modified to reflect the actual deployment environment, including the JNDI location of Role Manager, for example, to change the message bean properties java.naming.provider.url attribute. For example, if the Role Manager application server is run on a host named Server_ORM, and the jnp bind address is 1099 as specified in the jboss-service.xml file where it is deployed, then the values for java.naming.provider.url should be: `jnp://Server_ORM:1099/queue jnp://Server_ORM:1099/ejb/orm` This file is manually copied to OIM_appserver/deploy. This file is only applicable to JBoss. Other application servers have other means for JMS queue configuration.
ormoim-service.xml	Configuration file for the JMS queues required to support the Integration Library on the Role Manager application server. This file is manually placed into the application server's deploy directory. The settings in this file may have to be modified to reflect your deployment environment, including the JNDI location of Identity Manager, for example, to change the message bean properties java.naming.provider.url attribute. For example, if the Identity Manager application server is run on a host named Server_OIM, and the jnp bind address is 1099 as specified in the jboss-service.xml file where it is deployed, then the values for java.naming.provider.url should be: `jnp://Server_OIM:1099/queue` This file is manually copied to ORM_appserver/deploy. Other application servers have other means 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 Role Manager event type to which messages sent from Role Manager to Identity Manager adhere.
imframework.imconfig_1_0.xsd	Schema of the Role Manager Integration Library configuration file (IMConfig.xml).
imframework.pluginconfig_1_0.xsd	Schema of the files in the Role Manager Integration Library pluginConfigDir directory.

2.7 Determining the Release Number of the Integration Library

Release information for the 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 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.