Oracle® Access Manager Upgrade Guide 10g (10.1.4.0.1) Part Number B25354-01 |
|
|
View PDF |
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:
Both earlier releases and 10g (10.1.4.0.1) support the following components:
Identity Server (formerly known as the COREid Server), WebPass, Policy Manager (formerly known as the Access Manager component), Access Server, WebGate, and Software Developer Kit
Note: The Simple Network Management Protocol (SNMP) has not changed and does not require an upgrade. |
Oracle Access Manager applications, which are integral to components, include the Identity System Console, User Manager, Group Manager, Organization Manager, the Selector, the Access System Console, Policy Manager (formerly known as the Access Manager), and other applications
Integration components such as the Security Provider for WebLogic SSPI and Connector for WebSphere, as well as single sign-on (SSO), provisioning, portal and application server integrations are supported. Complete implementation details are described in the Oracle Access Manager Integration Guide..
For information about system requirements and changes, see "Platform Support".
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
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
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.
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. |
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.
A utility (obmigratefiles) is called to upgrade earlier program and library files.
A utility (obmigrateparamsg) is called to upgrade earlier message and parameter catalog files.
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)
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.
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:
\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:
During Identity Server data migration, error_output_fromversion_to_toversion_osd.ldif file is created in the IdentityServer_install_dir\identity\oblix\tools\migration_tools\obmigratedata directory.
During Policy Manager data migration, error_output_fromversion_to_toversion_psc.ldif file is created in the PolicyManager_install_dir\access\oblix\tools\migration_tools\obmigratedata directory
For details about using log files, see Appendix F, "Troubleshooting the Upgrade Process".
The following items are upgraded during component upgrades:
The Oracle Access Manager schema and configuration and policy data are upgraded only with the master Identity Server and Policy Manager installed for this purpose
Web server files and filters are upgraded only for Web components (WebPass, Policy Manager, WebGate)
Component-specific information, including component configuration files and system environment settings such as registry entries for Win32
Product and component names are changed as described in "Product and Component Name Changes"
Certain configuration files, including those for failover and the software developer kit (SDK) are upgraded as indicated in the following list:
Access Server: failover files
SDK Configuration: The upgrade is invoked automatically as the last step when upgrading the Identity Server (and integration components that rely on the Software Developer Kit libraries). Oracle recommends that you accept the automatic upgrade to preserve current configuration settings. Otherwise, you must reconfigure the SDK later using the configureAccessGate tool, as described in Chapter 11, "Upgrading Integration Components and an Independently Installed SDK".
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:
password.xml and .lst (.lst is converted to .xml for the Access System)
Starting with release 7.0 and continuing with 10g (10.1.4.0.1), the default certificate store format and name has changed to cert8.db from cert7.db. After the upgrade, the old certificate store is used. 10g (10.1.4.0.1) (and release 7.x) work with both the cert7.db (upgraded environments) and cert8.db (new installations) certificate store. See "Certificate Store and Localized Certificates".
For additional information, see the topics:
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.
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.
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".
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.
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".
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:
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:
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".
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".
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:
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".
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". |