Skip Headers
Oracle® Access Manager Upgrade Guide
10g (10.1.4.0.1)

Part Number B25354-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 About Automated Processes and Manual Tasks

This chapter introduces both the automated processes that are initiated when you start a component upgrade and manual tasks that you must perform. Topics include:

3.1 Supported Components and Applications

Both earlier releases and 10g (10.1.4.0.1) support the following components:

For information about system requirements and changes, see "Platform Support".

3.2 About the Automated In-Place Component Upgrade Process and Events

As mentioned earlier, you upgrade each component in place. This means that the newest product release is installed over an earlier product release in the same location. This discussion introduces the program-driven processes that occur during component upgrades.

You initiate a component upgrade using the corresponding Oracle Access Manager 10g (10.1.4.0.1) installer. During each component upgrade, the program controls the sequence of events and messages automatically. The component upgrade process requires very little input from you.

After you start an upgrade and specify the same (target) installation directory where the earlier (source) component resides, you are asked if you want to upgrade the earlier version of the component.


Note:

If the target installation directory for a 10g (10.1.4.0.1) component does not match the installed directory of the same earlier component, the component is installed (not upgraded).

When you accept the upgrade option, the source directory is renamed with the addition of a time stamp (yearmonthday_hourminutesecond). This time-stamped source directory contains earlier original files that are sometimes accessed to compare content or extract customized information.

Sample Time-Stamped Directory:

\IdentityServer_install_dir_20060422_141440\identity

After the source directory is renamed with a time stamp, the target directory is created and new files are extracted to the target. For example:

Sample Target Directory: \IdentityServer_install_dir\identity

New folders are created in the target directory as needed. While the directory structure for Oracle Access Manager release 6.5, release 7.0, and 10g (10.1.4.0.1) are the same, they differ from earlier releases. For details, see Appendix A, "Oracle Access Manager Directory Structure Changes".

You may choose to have individual events within the upgrade process performed automatically or with your confirmation, as described earlier in "Upgrade Event Modes".

Figure 3-1 and the process overview that follows it describe a typical component upgrade that is driven by each program (and the utilities that are called automatically during the process). At several points during the process, you are asked to provide specific input (such as a path name) or accept an automatic process, or simply acknowledge that you are ready to continue.

Figure 3-1 Automated Program-Driven Events During a Component Upgrade

Description of Figure 3-1 follows
Description of "Figure 3-1 Automated Program-Driven Events During a Component Upgrade "

During each component upgrade, additions and changes (from each major release to the next major release to release 10g (10.1.4.0.1)) are implemented As a result, the sequence of events and messages may repeat automatically until all changes between your starting release and 10g (10.1.4.0.1) are incorporated.


Note:

Process overviews, such as the one here, identify automated processes. After you initiate the process, you may be asked to accept or acknowledge certain events. Skipping or declining an event is sometimes an option.

Process overview: During an in-place component upgrade

  1. After you launch the 10g (10.1.4.0.1) component installer, and an earlier source directory is detected in the same location, you are asked if you want to upgrade. When you accept the upgrade, the source directory is renamed with a time stamp.

  2. The target directory is created and 10g (10.1.4.0.1) files are extracted into it. The English language is upgraded automatically. Other installed languages are upgraded when you include appropriate 10g (10.1.4.0.1) Language Packs for each installed language in the same directory as the 10g (10.1.4.0.1) component installer.


    Note:

    If you upgrade an existing multi-language implementation without 10g (10.1.4.0.1) Language Packs, you will lose multi-language functionality.

  3. A utility (obmigratenp) is called by the component installer to determine the release you are upgrading from as well as the release you are upgrading to. obmigratenp internally detects which features need to be upgraded for this particular component and which other utilities to use for those upgrades. When your installation includes multiple languages, obmigratenp migrates message catalogs.

  4. A utility (obmigratefiles) is called to upgrade earlier program and library files.

  5. A utility (obmigrateparamsg) is called to upgrade earlier message and parameter catalog files.

  6. Schema and Data Upgrades Only: Two utilities (obmigrateds and obmigratedata) are called automatically to initiate Oracle Access Manager schema and data upgrades for the master Identity Server (and master Policy Manager when your installation includes the Access System). During subsequent Identity Server (and Policy Manager) upgrades, the initial schema and data upgrade is detected and this portion of the process is skipped.

    Oracle recommends that you upgrade the Oracle Access Manager schema and data automatically, as described in Part II, "Upgrading the Schema and Data". Such upgrades use ldif files specific to your directory. Each ldif file includes only changes from one release of Oracle Access Manager to the next. As a result, the schema and data upgrade will repeat one time for each release from your starting release to 10g (10.1.4.0.1). For example, if you are upgrading from release 6.1.1, the schema and data upgrade occurs as follows:

    • From release 6.1.1. to release 6.5

    • From release 6.5 to release 7.0

    • From release 7.0 to 10g (10.1.4.0.1)

  7. Web Server Configuration Updates Only: A utility (obmigratews) is called to perform a selective Web server configuration file and filter upgrade, to accommodate changes for newer releases of Policy Manager, WebPass, and WebGate.

  8. A component-specific utility is selected and run to make changes to related registry entries for Windows, plug-ins, and other files. The component's configuration files are updated. For more information, see "Component-Specific Upgrades".

During each component upgrade, one or more log files may be produced to inform you if any problem should arise. If a log file is created, a message during the upgrade process indicates the name and location of the file. In general, you can find upgrade log files in:

Log File Path:

\Component_install_dir\identity|access\oblix\tools\migration_tools\toolname.log

where \Component_install_dir is the directory where the specific component is installed; identity|access represents the system to which the component belongs (Identity System or Access System, respectively); and toolname represents the name of the utility that produced the log.

Each log file contains information about a particular activity that occurs during the component upgrade. For example, a separate log file may be generated for file upgrades, or message and parameter upgrades, or the Oracle Access Manager schema upgrade to name a few. For information about specific log files and their content, see Appendix B, "Upgrade Process and Utilities".

In addition, the log files here are created to inform you of any ldap specific errors:

For details about using log files, see Appendix F, "Troubleshooting the Upgrade Process".

3.3 Upgraded Items

The following items are upgraded during component upgrades:


Note:

Only supported components are upgraded. For more information, see "Support Deprecated".

3.4 Preserved Items

Any names assigned by an administrator during product installation and configuration are retained during an upgrade (not changed). Therefore if you have named a service "COREid Identity Server" or "NetPoint Identity Server" these names will be the same in the upgraded environment.

Earlier authentication schemes and policy domains assigned by administrators are also retained during the upgrade. After the upgrade, these names are still available.

The items in the following list are preserved in the time-stamped directory and copied into the new target directory:

For additional information, see the topics:

3.4.1 Directory Server Failover

Starting with the Access System release 6.5, directory profiles are created during Policy Manager setup and are used by the Access System to access user directory data. These profiles replace the UserDB.lst and GroupDB.lst files and the UserDBFailover.lst and GroupDBFailover.lst configuration files that were used in earlier releases of the Access System.

During the Access System upgrade from release 6.1.1, new directory profiles are created based on the UserDB.lst and GroupDB.lst files and the UserDBFailover.lst and GroupDBFailover.lst configuration files.

Your earlier implementation may also include failover between an Identity Server and the directory server. The Identity Server failover configuration has resided in the directory server profiles since release 5.2. As a result, during the Identity Server upgrade there is no migration of parameters from failover configuration files to directory profiles. Although the schema itself has changed, migration of these changes is performed automatically during the upgrade.

3.4.1.1 Impact of the Upgrade on Directory Server Failover

Starting with release 6.5, the Access System began partially using directory profiles and database instances for accessing user data. Directory profiles replace the UserDB.lst, GroupDB.lst, UserDBFailover.lst, and GroupDBFailover.lst configuration files that were used in earlier Access System releases. During the incremental upgrade to release 6.5, directory profiles for the Access Server are automatically created and replace certain earlier configuration files where:

  • Primary directory server information was stored in: AccessServer_install_dir/access/oblix/config/UserDB.lst and GroupDB.lst

  • Information for all the failover and load-balancing directory servers (primary and secondary) was stored in: AccessServer_install_dir/access/oblix/config/UserDBFailover.lst and GroupDBFailover.lst

When creating the Directory Server Profile for the Policy Manager, directory server credentials are read from PolicyManager_install_dir/access/oblix/config/userDB.lst.


Note:

If the configuration tree is in the user directory server and under the user node, then the configuration directory profile is not created. Otherwise, a configuration directory profile is created using directory server information from PolicyManager_install_dir/oblix/config/ldap/configdb.lst and marked for use only by the Policy Manager.

Profiles are not created for Policy Manager failover servers. In the case of release 6.1, if the policy tree was on a separate directory server a profile for policy data existed.

After upgrading the Identity System and Access System, it is a good idea to validate your failover and load balancing configurations and to test that these are still operating as expected. For details, see discussions in:

See also "Connection Pool Details" next.

3.4.2 Connection Pool Details

As described in the Oracle Access Manager Deployment Guide, the number of connections opened to the directory is specified by the Initial Connections parameter in the Database Instance Profile. More connections are opened, as needed, until they equal the number specified by Maximum Connections parameter in the database instance profile. Connections remain open until the Identity or Access Server shuts down or the directory server stops responding. Those connections are then pooled and used by the Identity and Access Server.


Note:

Starting with Oracle Access Manager release 7.0, connection pooling was consolidated to support failover across the entire system. The directory connection pool does not depend on directory type.

There may be some impact when upgrading the Access System, depending on the earlier configuration of Oracle Access Manager to each directory server used. For details, see "Confirming Access System Failover and Load Balancing".

See also the previous discussion on "Directory Server Failover".

3.4.2.1 Impact of the Upgrade on Connection Pools

There may be some impact when upgrading, depending on the earlier configuration of Oracle Access Manager to each directory server used. For instance:

  • Identity System Connection Pools: There is no impact. Initial Connections and Maximum Connections specified in the database instance profile are retained and will operate as they did previously.

  • Access System Connection Pools Before release 6.5: Values for the Initial Connections and Maximum Connections in the UserDB.lst and UserDBFailover.lst may not be retained. After upgrading Access System components, it is a good idea to verify the values in the database instance profile of the newly created directory server profile.

  • On NDS: For concurrent authentication requests on NDS directory servers, Oracle recommends that you increase the connection pool size to something higher than the default (1) for the user directory profile using the System Console.

3.4.3 Encryption Schemes and the Shared Secret

The shared secret encryption algorithm is an Oracle Access Manager-wide setting. It affects all encrypted cookies. For example, the ObSSOCookie cookie is encrypted using a configurable encryption scheme known as a shared secret. During the upgrade, the earlier encryption scheme is retained.

In release 7.0.4 and earlier, WebGates/AccessGates handled encryption and decryption using the shared secret value. Starting in 10g (10.1.4.0.1), however, the Access Server handles encryption/decryption. As a result, the shared secret is no longer needed on WebGate.

Oracle recommends that you upgrade earlier WebGates. However, earlier WebGates may coexist with 10g (10.1.4.0.1) Access Servers when specific conditions are met. For more information on encryption schemes, the shared secret, Access Servers, and WebGates in Chapter 4, "System Behavior and Backward Compatibility".

3.5 Items that You Must Manually Upgrade

The following discussions outline items that require you to perform manual upgrade tasks to ensure compatibility and proper operation with release 10g (10.1.4.0.1):

In addition to the topics in the preceding list, see details in:

3.5.1 Auditing and Access Reporting

Oracle Access Manager 10g (10.1.4.0.1) supports the Unicode standard. To support all the languages available with Oracle Access Manager 10g (10.1.4.0.1), the definitions of auditing and reporting tables have changed. Simply upgrading or altering existing database instances and tables is not supported and could result in permanent truncation and loss of existing data.

After upgrading the Identity System (and Access System), you need to create a new database instance to operate with 10g (10.1.4.0.1). To upload the new Audit table schema to support the auditing of 10g (10.1.4.0.1) UTF-8 data and writing this data to the new SQL Server instance, you must create a new oblix_audit_events table. This schema upgrade includes datatype changes within Audit table columns. Next you need to create tables for the reporting application (oblix_rpt_as_reports, oblix_rpt_as_resources, and oblix_rpt_as_users) in 10g (10.1.4.0.1).

To query or generate any report that requires data from both the old and new database, you need to import data from the original instance into the new instance before you start auditing with 10g (10.1.4.0.1). This is an optional step that may or may not be needed in your environment.


Note:

Retain the earlier database to preserve the original data. Importing earlier data may result in some data loss through truncation. However, if you do not import old data before you start auditing, you cannot generate any report that requires the data from both the old and new database.

The steps you need to perform, even when you have an English only environment, depend on the type of database you are using. For details, see:

3.5.2 C++ Programs

You will need to recompile C++ programs created with the Software Developer Kit and Oracle Access Manager APIs following that upgrade, for the reasons stated in "Plug-ins".


Note:

Oracle recommends that you begin migrating your earlier customizations in a test environment well before you begin upgrading components. This will help reduce system downtime when upgrading your production environment and redeploying customizations.

For more information, see Chapter 4, "System Behavior and Backward Compatibility", Chapter 12, "Upgrading Your Identity System Customizations", and Chapter 13, "Upgrading Your Access System Customizations".

3.5.3 Challenge and Response Attributes Must Appear on a Panel

In earlier releases, the challenge phrase and response attributes were allowed on different panels of Profile pages. In 10g (10.1.4.0.1), however, both the challenge phrase and response attributes must be on the same panel. In 10g (10.1.4.0.1), challenge phrases and responses are displayed one after the other even though these are not configured one after the other in the panel.

For details about combining challenge and response attributes on a single panel, see "Combining Challenge and Response Attributes on a Panel".

3.5.4 Customized Styles

Default product stylesheets are periodically updated by Oracle to instantiate improvements. For example, to support multiple languages, the location of java scripts, stylesheets, and images changed starting with Oracle Access Manager release 6.5. The directory structure introduced with release 6.5 continues with 10g (10.1.4.0.1).

Upgraded functionality depends, in part, on stylesheet files in the new release \style0 and \shared directories.


Note:

If files in your earlier Oracle Access Manager \style0 directory were customized, you must manually edit the newer version files in \style0 and \shared directories after the upgrade.

It is important to understand the new file hierarchy and stylesheet structure before you can successfully migrate custom images and stylesheets to 10g (10.1.4.0.1). If you simply copy the old stylesheets, images, JavaScript files, and related items to the new release, Oracle Access Manager may experience problems.

The following files must be processed manually after the upgrade:

  • XSL stylesheets

  • Images (.gifs for Oracle Access Manager)

  • JavaScript Files


Note:

Oracle recommends that you begin migrating your earlier customizations in a test environment well before you begin upgrading components. This will help reduce system downtime when upgrading your production environment and redeploying customizations.

For details, see Chapter 12, "Upgrading Your Identity System Customizations". For details about the Oracle Access Manager directory structure, see Appendix A, "Oracle Access Manager Directory Structure Changes".

3.5.5 Plug-ins

Plug-in behavior has changed in recent releases. Following are important details that you need to be aware of with regard to custom plug-ins.

All earlier plug-ins send and receive data using Latin-1 encoding. Starting with 10g (10.1.4.0.1), Oracle Access Manager components and plug-ins send and receive data in UTF-8 format. Identity and Access Servers that are upgraded to 10g (10.1.4.0.1) provide backward compatibility with earlier plug-ins using Latin-1 encoding automatically. However, to send and receive internationalized data, earlier plug-ins should be redesigned to communicate using UTF-8 encoding. This includes Identity Event plug-ins and custom authentication and authorization plug-ins. For more information about globalization, see Chapter 4, "System Behavior and Backward Compatibility".

Starting with Oracle Access Manager release 7.0, components on Solaris and Linux are compiled using the GCC v3.3.2 C++ compiler to address multi-threading issues encountered with earlier compiler releases. This means that after the upgrade, you must recompile custom plug-ins from release 5.x or 6.x using GCC v3.3.2 C++ compiler. This includes Identity Event plug-ins and custom authentication and authorization plug-ins. You must use the GCC v3.3.2 compiler, regardless of the one that may be provided by your Operating System.


Note:

Release 7.0 plug-ins as well as earlier plug-ins implemented as executables or those using a scripting language (such as perl) do not require recompiling after the upgrade. However, to send and receive internationalized data, earlier plug-ins should be redesigned to communicate using UTF-8 encoding.

Identity Event API Plug-Ins: Some plug-ins are copied during the upgrade; however, Identity Event API plug-ins are not. After the upgrade you must move earlier Identity Event plug-ins. These plug-ins may also need to be re-compiled or re-designed. For more information, see "Migrating Custom Identity Event Plug-Ins".

Authentication and Authorization Plug-Ins: After the Access System upgrade, see "Recompiling and Redesigning Custom Authentication and Authorization Plug-Ins". Also, the Oracle Access Manager Access Administration Guide provides more information about:

  • Adding customized plug-ins and parameters to an authentication scheme to be used for any of the scheme's steps

  • Installing a custom authorization plug-in on application servers that you want to protect and creating custom schemes that include custom plug-ins to perform different (or additional) tasks from those of the default scheme


Note:

Oracle recommends that you begin migrating your earlier customizations in a test environment well before you begin upgrading components. This will help reduce system downtime when upgrading your production environment and redeploying customizations. For more information, see "Customization Upgrade Planning".