Upgrading to OIM 11.1.2.3: an overview

In this post I’m going to give an overview of the steps involved in upgrading to Oracle Identity Manager 11.1.2.3. This is just a high-level overview, with pointers to the documentation you need to read to get the detailed steps.

Classification of OIM environments

For the purpose of OIM upgrade, environments can be classified as follows:

  • LCM vs non-LCM: an LCM environment is installed using the LCM (Lifecycle Management) provisioning tools shipped in 11.1.2.x and later. All other environments are non-LCM environments. You might also hear LCM environments described as automated install environments and non-LCM environments described as manual install environments
  • HA vs single instance: a HA (high availability) environment has multiple OIM servers in a cluster. A single instance environment contains only a single OIM
  • integrated vs non-integrated: an integrated environment contains OIM, OAM (and optionally OAAM as well). The three products are integrated with each other using the documented integration approach. LDAP Synch is used to synchronise users in the OIM database to a supported LDAP server, and OAM uses that LDAP server for authentication and to retrieve identity data. By contrast, a non-integrated environment contains OIM only.

These classifications are important in that they determine what are the supported versions for direct upgrade, and also the type of upgrade which must be performed (automated vs manual).

Supported versions for direct upgrade

Direct upgrade refers to going directly from a previous version of OIM to 11.1.2.3.0. If your version of OIM is not supported for direct upgrade, you will need to first upgrade to an intermediate older version, and then upgrade from there to 11.1.2.3.0.

We support direct upgrade from:

  • 11gR2 patchset 2 (11.1.2.2.x aka R2PS2) – any bundle patch
  • 11gR2 patchset 1 (11.1.2.1.x aka R2PS1) – any bundle patch – non-integrated environments only
  • 11gR2 base release (11.1.2.0.x aka R2) – any bundle patch – non-HA/integrated environments only
  • 11gR1 patchset 2 (11.1.1.7.x) – any bundle patch – non-HA/integrated environments only
  • 11gR1 patchset 1 (11.1.1.5.x) – any bundle patch – non-integrated environments only

As you can see, the set of starting points for direct upgrade is broader for single instance non-integrated environments than for HA and/or integrated environments. What should you do if you have a HA and/or integrated environment, on a version for which direct upgrade is only supported for non-integrated or non-HA environments? In that case, you will need to upgrade to an intermediate version first.

Likewise, what if you are running an older version not in the above list? Upgrade is still possible, but you will first need to upgrade to an intermediate version:

  • 11gR1 base release (11.1.1.3.x) – direct upgrade to 11.1.2.3.0 is not supported. Upgrade to 11.1.1.5.0 first, and then you can upgrade to 11.1.2.3.x from there.
  • 9.1.0.1 and 9.1.0.2 releases (any BP) – upgrade to 11.1.1.2.0 first, and then from there to 11.1.2.3.0
  • all older versions of OIM (including 9.1.0.0, 9.0.x and 8.x and earlier) – upgrade to OIM 9.1.0.2 first

If you are starting from a particularly old version, you may want to consider installing a fresh OIM 11.1.2.3.0, and performing a migration to that new environment rather than an in-place upgrade. This has the advantage that the old and new environments can run side-by-side for an intermediate period, enabling connectors to be progressively transferred from one to the other. There can be additional work involved, however, in ensuring that these two OIMs remain in synch. Hence, whether this is the right approach for you depends heavily on the details of your existing environment (how many connectors are involved, how many customisations, etc.)

Upgrade Advisor

My Oracle Support provides an upgrade advisor which provides a skeleton for an upgrade project for an integrated OIM-OAM environment: Upgrade to 11gR2 PS3 (11.1.2.3) : Advisor for Integrated OIM / OAM Environments (Doc ID 2019069.2). While this advisor covers an integrated OIM-OAM environment, much of its content is also relevant to the upgrade of OIM-only environments. The great thing about this advisor, is as well as giving a high-level overview of the technical steps involved, it also provides a framework for an actual upgrade project, including important phases such as planning and testing. Following that framework, you will perform initial upgrades of one or more test environments to confirm the upgrade steps work correctly, and perform user acceptance testing of those environments to ensure the upgraded environment works correctly. Development work may also be required to update any customisations you have performed to work in the new version (e.g. UI customisations, custom event handlers, custom connectors, etc.) Once the entire upgrade process has been validated in a non-production environment, you can carry out the upgrade in a production environment.

As part of upgrading testing, it is strongly recommended you test your upgrade with a test environment which is as close to production as possible. Ideally, use a production clone environment with the same data as production. Of course, due to security/privacy concerns that is not always possible, but if not, one should at least aim to upgrade a test environment with similar volumes of data to production – a similar number of users, a similar number of roles and accounts per a user, etc. This is important for accurately estimating the time required for the upgrade and hence planning your production upgrade schedule.

Upgrade approaches

Starting in OIM 11.1.2.3 we offer two different approaches to upgrade, automated and manual:

  • Manual: For the majority of customers today this is the upgrade approach to use. In this approach you execute a sequence of steps to achieve the upgrade; while those individual steps automate many aspects of the upgrade process, the overall orchestration of the major steps is a task you have to perform manually. We support this method of upgrade for any prior version from which direct upgrade is supported.
  • Automated: If you installed OIM 11.1.2.2.x using the LCM provisioning tool, this is the upgrade method to choose. Performing a manual upgrade on an LCM environment is not supported – the LCM tools maintain their own records of your environment configuration in a file called topology.xml. If you attempt to manually upgrade your environment, the contents of your topology.xml file will get out of synch with your environment. If anyone later attempts to use any of the LCM tools (automated upgrade or automated patching) on your LCM environment, the LCM tools will fail due to the mismatch.

Manual Upgrade Steps

In this section I am going to outline the high-level steps involved in a manual upgrade. For details of these steps, please follow the Upgrade Advisor.

  1. Software upgrade – upgrade the binaries of the Oracle Home. This consists of upgrading the Oracle WebLogic Server software to version 10.3.6 (if not already at that version), upgrading the Oracle SOA Suite software to version 11.1.1.9.0, and upgrading the Oracle Identity and Access Management software to version 11.1.2.3.0. This step upgrades the software binaries on disk but does not upgrade the configuration nor does it make any changes to the database. In a HA environment, you will need to do this on all machines.
  2. Database schema upgrade – upgrade your database schemas to the 11.1.2.3.0 version. This includes upgrade the SOAINFRA, MDS, ORASDPM and OPSS schemas to version 11.1.1.9.0. This also requires creation of a new schema for BI Publisher (BIP).
  3. Middle-tier offline upgrade – this updates the configuration files in the OIM WebLogic domain; however, despite what a strict interpretation of its name might suggest, it also actually updates data in the database. The difference is the schema upgrade modifies the database schema (tables and columns), while this upgrade step modifies some of the data in the tables. The schema upgrade accesses the database directly at the SQL level, whereas this upgrade step accesses the database indirectly through higher level APIs. This is the first phase of the middle-tier upgrade which is run with all WebLogic servers down.
  4. Domain pack/unpack(HA environments only) the middle-tier offline upgrade step is run on a single node, now in this step the upgraded domain is replicated from that node to the other nodes by packing it up on the first node and then unpacking it on the other nodes.
  5. Middle-tier online upgrade – this is the second phase of the middle-tier upgrade which requires the SOA managed servers and the Admin Server to be running.
  6. BI Publisher scale-out(HA environments only) in previous releases the BI Publisher reporting tool was an optional component requiring a separate install; starting in OIM 11.1.2.3.0 it is now a bundled component. The previous upgrade steps will create a single BI Publisher managed server instance; if you want high-availability for BI Publisher, in this step you can scale it out by adding one or more additional BI Publisher managed servers.
  7. OIM Design Console upgrade – many OIM installs will include the Design Console, a Java GUI client used to perform advanced configuration and development tasks. In this step, the Design Console is upgraded; if you do not have it installed in your environment, you can skip this step.
  8. OIM Remote Manager upgrade – Remote Manager is a legacy component used by some of the OIM 9.x connectors. If you are not using any such connectors (e.g. you only have 11g connectors installed, or you have some 9.x connectors but your 9.x connectors don’t use Remote Manager), you do not need this component installed. If you have this component installed and require it, this step will upgrade it to a version compatible with OIM 11.1.2.3.0
  9. Post Upgrade Tasks – There are a number of steps to perform here, including certain config changes required (e.g. updating the URI of the Human Task Service Components in SOA with Oracle HTTP Server details). Note that there are additional steps required if you are upgrading from OIM 11gR1 (11.1.1.x) compared to upgrading from an earlier version of OIM 11gR2 (11.1.2.x.)
  10. Verify Upgrade – Validate the upgraded environment works correctly. Some basic tests can include that you can log in to both the OIM Self-Service (/identity) and System Administration (/sysadmin) consoles, that you can access BI Publisher and successfully run BI Publisher reports, and that Enterprise Manager shows Oracle Identity Manager components are running. You should also perform some more in-depth tests, such as creating/modifying/disabling/enabling/deleting a test user, and requesting provisioning of an application to a user, approving that provisioning, and checking that the application is provisioned successfully. (In a production environment, it is important to liase with your audit team before doing any such testing with a test user, since otherwise such a test user may be flagged during the audit process.)

Automated Upgrade Steps

For detail on the automated upgrade steps, please see the IAM 11.1.2.3 Upgrade Guide, Part II. It contains both single instance environment steps (chapter 4) and HA environment steps (chapter 5). We support upgrade for both OIM only environments and OIM-OAM-OUD integrated environments. For single node Linux installs only, we support isolated upgrade of an OIM-OAM-OUD integrated environment. Using isolated upgrade, you can upgrade OIM to 11.1.2.3 while leaving OAM and OUD at the 11.1.2.2 versions (or, conversely, you could upgrade OAM or OUD to 11.1.2.3 while leaving OIM at version 11.1.2.2). For more details on isolated upgrade, see section 2.3, Isolated Upgrade Overview and section 4.6, Performing Isolated Upgrade for OIM-OAM Integrated with Oracle Unified Directory (OUD) Topology on a Single Node.

I’m going to summarise the steps involved in a Single Node OIM Only install below. For the full steps, see section 4.3, Upgrading Oracle Identity Manager (OIM) Only Topology on a Single Node.

  1. Validate the environment – review the documentation and ensure that you are at a supported starting point for this install. Validate the contents of your /etc/hosts file meets the automated installer’s requirements.
  2. Download and install the automated upgrade tool – download Patch 21419345 from My Oracle Support (requires a valid Oracle Support contract). Inside the downloaded ZIP file p21419345_111170_Generic.zip there is another ZIP file idmUpgrade.zip. Unzip that later ZIP anywhere on your OIM server machine; it contains the tool for the automated upgrade of OIM (and OAM) from 11.1.2.2 to 11.1.2.3.
  3. Configure environment variables – configure the environment variables required for automated upgrade by following the steps in section 6.4, Setting the Required Environment Variables Necessary for Upgrade. Some of these variables are required on all platforms (JAVA_HOME, PERL5LIB, PATH). There are also platform specific environment variables required on certain platforms only (Solaris, AIX and HP/UX).
  4. Configure the upgrade.properties file – the upgrade.properties file drives the entire upgrade process. You must configure it following the steps in section 6.7, Updating the upgrade.properties File
  5. Perform the pre-validation checks – run preValidate.pl following the steps in section 4.3.5, Performing Pre-Validation Checks on OIMHOST and section 6.8, Performing Pre-Validation Checks Using preValidate.pl Script
  6. BIP Schema Creation – this step is required on Solaris, AIX and HP/UX only; you will need to run the RCU from a Linux or Windows host to create the BI Publisher schema. See section 4.3.6, Creating BIP Schema for OIM Upgrade (Only on Solaris, IBM AIX, and HP Itanium Platforms) and section 6.9, Creating BIP Schema for Oracle Identity Manager Upgrade on Solaris, IBM AIX, and HP Itanium Platforms. Skip this step on Linux; on Linux, the automated upgrade tool will perform this step for you.
  7. Stop all servers – run $IAM_TOP/config/scripts/stopall.sh to shut down all WebLogic and OHS instances associated with WebLogic
  8. Take a full backup – take a full backup of both the filesystem and database schemas before proceeding with the upgrade. That way, you can roll back in case of upgrade failure by restoring those backups.
  9. Perform the upgrade – run the idmUpgrade.pl script to actually perform the upgrade. See section 4.3.9, Upgrading Binaries and Configuration on OIMHOST and section 6.10, Upgrading Oracle Identity and Access Management Binaries and Configuration Using idmUpgrade.pl script for the full details of this step.
  10. Perform post-validation checks – run the script postValidate.pl, following the instructions in step section 4.3.10, Performing Post-Validation Checks on OIMHOST and section 6.11, Performing Post-Validation Checks Using postValidate.pl Script. This step helps validate that the outcome of the upgrade was successful.
  11. Manual validation – review the upgrade tool log files for any errors or warnings (see section 4.3.11, Verifying the Upgrade). It is also recommended to carry out some basic tests by hand, e.g. confirm you can log in to the consoles – see my recommendations under the Verify Upgrade heading in Manual Upgrade Steps above.

In a single node OIM-OAM-OUD integrated topology, the steps are basically the same. The main differences are:

  • The upgrade.properties file contains additional settings for an integrated topology, beyond those you need to specify for an OIM only topology
  • The scripts, preValidate.pl, idmUpgrade.pl, and postValidate.pl, take a -node argument specifying which component they are acting upon (i.e. -node OIM for OIM, and -node WEBTIER for OHS). In an integrated environment, you need to run these scripts further times, specifying -node DIRECTORY for OUD and -node OAM for OAM.
  • To run the preValidate.pl script against OUD, you need to copy a couple of files (libnnz11.so, libclntsh.so.11.1) from your WebLogic or OHS installation directories to the upgrade tool directory. The upgrade tool requires these libraries to validate OUD, but they are not bundled with the upgrade tool (since they are platform-specific, but the upgrade tool is platform-generic.)
  • If you have OAAM (Oracle Adaptive Access Manager) installed in your OIM-OAM-OUD integrated environment, there are some extra steps related to OAAM. See section 4.5.1, Completing the Prerequisites, point (3), and also section 4.5.11.1, Adding the JAVA System Property if you have Configured OAAM and section 6.13.1, Adding the Java System Property for Oracle Adaptive Access Manager

In a HA environment, whether OIM only or OIM-OAM-OUD, these are the basic differences:

  • Since you now have multiple hosts, you need to make the upgrade tool (which includes the upgrade.properties file) available on every host; make sure it is available at the same filesystem path on each machine. You need to make sure that the upgrade.properties file is in synch between them.
  • In a single instance install, idmUpgrade.pl was run using -mode both, which upgraded both binaries and configuration in one go. In a HA environment, you need to run to perform these two phases separately, first with -mode binary and then again with -mode config. This is because you must complete the binary upgrade on all nodes before commencing the configuration upgrade.
  • Many of the steps, i.e. preValidate.pl, stopall.sh, idmUpgrade.pl, postValidate.pl, must now be run multiple times, once per each relevant host. However, this can vary somewhat depending on your filesystem architecture; if your software binaries are on shared storage (e.g. NFS), then you only need to run the binary upgrade on one host for each component (e.g. on OIMHOST1 only), whereas if you are using local storage the binary upgrade step needs to happen once per each host (i.e. on both OIMHOST1 and on OIMHOST2).
  • HA environments have some additional steps required (e.g. updating the OHS configuration for BI Publisher.) In an integrated OIM-OAM-OUD environment, there are some additional post-upgrade steps specific to OAM and OAAM.

Resources

Here are some resources for further study on the OIM upgrade process. Two of these resources (the upgrade advisor and the documentation) I have already mentioned above:

Add Your Comment