3 Upgrading the Oracle Role Manager Integration Library

This chapter provides the steps to perform an upgrade of the Oracle Role Manager Integration Library with Oracle Identity Manager.

This chapter includes the following sections:

Before You Start
Upgrading the Oracle Role Manager Integration Library Software and Configuration
Resetting the oimSystem System User Privileges
Running the User Groups Cleanup Task

3.1 Before You Start

Before you begin the upgrade of the Oracle Role Manager Integration Library the following prerequisites steps must be completed:

Stop the application server for Oracle Identity Manager.
Stop the application server for Oracle Role Manager.
Upgrade Oracle Role Manager following the instructions in the Oracle Role Manager Installation Guide. This includes backing up the Oracle Role Manager application user and database owner users/schemas.

Note:
Ensure that when running the upgrade script, the oim_integration.car is in the path of configurations to upgrade. If the upgrade of Oracle Role Manager did not include the oim_integration.car, deploy it now following the steps in Section 5.1, "Deploying the Integration Library Configuration."
If you are using a version of Oracle Identity Manager prior to version 9.1.0.2, upgrade to version 9.1.0.2 following the instructions in the Oracle Identity Manager Installation Guide.
Configure role grant approval workflow as follows:
1. Complete the procedure described in Section 6.5, "Creating the Proxy User for Role Grant Approval Workflow."
2. Complete the procedure described in Section 6.8, "Assigning the Proxy User to the System Group."
3. Complete the procedure described in Section 6.10, "Configuring Role Grant Approval Workflow."

3.2 Upgrading the Oracle Role Manager Integration Library Software and Configuration

Certain files must be copied into the ORMINT_HOME and Oracle Identity Manager directories, as described in this section.

Note:

If you have a clustered server configuration, perform the steps in this procedure on all managed nodes.

To upgrade the software:

On the Oracle Identity Manager application server host, copy ORMINT_HOME to different location on the same host and rename it, for example, ORMINT_10141.

Make a note of this location. Files must be copied from this location to the upgraded ORMINT_HOME directory later in this procedure.
Make a note of the full path to ORMINT_HOME root directory so that you can use that exact path for the upgrade.
Delete ORMINT_HOME.
On the Oracle Role Manager installation host, navigate to ORM_HOME/Integration_Library.
Copy the Integration_Library directory to the Oracle Identity Manager application server host to replace the directory the ORMINT_HOME root directory.
Copy the following files from ORMINT_10141/bin to ORMINT_HOME/bin, where ORMINT_HOME is the new root directory and ORMINT_10141 is the directory copied in Step 1.
```
keystore.properties
keystore.key
keystore.store
oim_orm_cert
```
Note:
If the new ORMINT_HOME location is different than what was used for the previous version of the Integration Library, you must reconfigure the keystore_dir system property in the application server configuration to point to the new location. For more information, see the steps for your application server in Section 5.5, "Configuring Signed Messages (Encryption)."
Copy the following file from ORMINT_10141/config to ORMINT_HOME/config:
```
logging.properties
```

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 all of the class files from ORMINT_HOME/oimlib into OIM_HOME/xellerate/ScheduleTask.
Modify the IMConfig.xml file as follows:
1. Navigate to ORMINT_HOME/config.
2. Open the IMConfig.xml file for editing.
3. If your installation of Oracle Identity Manager does not use C:\OIM as the root directory, in the policies section, edit the oimRootdir policy to change C:\OIM to the appropriate root directory as follows:
```
<policy> 
  <parameters>
    <parameter>
      <id>oimRootdir/id>
      <string>C:\\oracle\oim</string>
    </parameter>
  </parameters>
</policy>
```
4. If your deployment is on WebLogic Server, in the policies section, edit the oimORMUser policy to change ormSystem to Internal as follows:
```
<policy> 
  <parameters>
    <parameter>
      <id>oimORMUser</id>
      <string>Internal</string>
    </parameter>
  </parameters>
</policy>
```
5. Save and close the IMConfig.xml file.
Re-import the base and sample configuration into Oracle Identity Manager as described in Section 6.6, "Importing the Prepared Configuration."
Redeploy the Integration Library application as described in one of the following sections, depending on your application server platform:

3.3 Resetting the oimSystem System User Privileges

After Oracle Role Manager is upgraded, there are three privileges that must be reset for the oimSystem system user: grant person, grant business role, and manage IT privilege.

To reset the oimSystem system user privileges:

On the Oracle Role Manager host, navigate to ORM_HOME/Integration_Library/config.

You should see the oim_systemIdentity.dar file.
Using a utility like WinZip or jar, extract the entire contents of oim_systemIdentity.dar into a temporary location, such as ORM_HOME/Integration_Library/config/oim_systemIdentity_upgrade.

In the temporary location, you should see the following five files:
```
load-request.xml
systemIdentity-orm.csv
systemRoleGrant-orm.csv
systemRole-orm.csv
systemRolePrivilegeMapping-orm.csv
```

Remove the following three files:

systemIdentity-orm.csv
systemRoleGrant-orm.csv
systemRole-orm.csv

Edit the load-request.xml file to change the values of load-script-id and procedure-id to the values shown in bold below. In addition, remove all resource-ref elements except the one named system_role_privilege_file.

The complete content of the file should be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<load-request xmlns="http://xmlns.oracle.com/iam/rm/loader/data/1_0"
        load-script-id="oim_systemrole_to_privilege_script"
        procedure-id="loadSystemRolePrivilegeMappings"
        ordering-mode="dependency-based-sequential">
        <parameters>
                <resource-ref name="system_role_privilege_file">
                        <resource-path>systemRolePrivilegeMapping-orm.csv</resource-path>
                </resource-ref>
        </parameters>
</load-request>

Edit the systemRolePrivilegeMapping-orm.csv file to contain only the following values:
```
grant,person,oimSystem
grant,businessRole,oimSystem
manage,itPrivilege,oimSystem
```
Using a utility like WinZip or jar, repackage the two files in the temporary location and create a file appended with the .dar extension, for example, oim_systemIdentity_upgrade.dar.
Load the new DAR file as follows:
1. Start the Oracle Role Manager application server.
2. From the Oracle Role Manager installation host, using a Web browser, go to the Oracle Role Manager Administrative Console. By default:
  
  WebLogic:   http://host:7001/ormconsole
  
  WebSphere:  http://host:9080/ormconsole
  
  JBoss:   http://host:8080/ormconsole
3. Enter the user name and password of the Oracle Role Manager administrator, then click Log In.
4. Click Upload.
5. Click Browse, and navigate to select the new DAR file created earlier, for example, oim_systemIdentity_upgrade.dar.
6. Click Load.
  
  You can click refresh to verify that all processes are finalized.

3.4 Running the User Groups Cleanup Task

The User Groups Cleanup task removes user groups that were created as a part of Oracle Role Manager IT role updates in older versions of Oracle Role Manager. The current version of Oracle Role Manager creates access policies for IT role updates. This should be run manually as part of the upgrade process.

To run the User Groups Cleanup Task

View an existing user group from Oracle Role Manager as follows:
1. In the Oracle Identity Manager Design Console, expand User Groups, then double-click Manage.
2. Search for and select any user group whose name begins with ORM_ and has role type as itRole.
  
  On the Details page of the selected user group, make note of the name for use later in this procedure.
Run the User Groups Cleanup task as follows:
1. In the Oracle Identity Manager Design Console (Oracle Identity Manager client), expand Administration, then double-click Task Scheduler.
2. Click the Lookup button, and then the Go to End button to go to the last defined task.
3. Click the left arrow button until you see the RoleManagerUserGroupsCleanup task.
4. Clear the Disabled box then click the Save button.
5. In the Status field, change the status to ACTIVE.
6. In the Start Time field, enter the timestamp of the current date and time plus one minute.
7. Click the Save button.
Search for the same user group viewed in Step 1 as follows:
1. In the Oracle Identity Manager Design Console, expand User Groups, then double-click Manage.
2. Search for the same user group viewed in Step 1.
  
  The group should not be present.