|
| |
| Sun Java Enterprise System Upgrade Guide for Microsoft Windows | |
Chapter 9
Access ManagerThis chapter describes how to upgrade Access Manager software from previous Java ES versions to Java ES 2005Q4 (Release 4): Sun Java System Access Manager 7 2005Q4.
The chapter provides a general overview of Access Manager upgrade issues and procedures for the different upgrade paths supported by Java ES Release 4.
Overview of Access Manager UpgradesThis section describes the following general aspects of Access Manager that impact upgrading to Java ES 2005Q4 (Release 4):
About Java ES Release 4 Access Manager
Java ES Release 4 Access Manager has been enhanced in major ways. On the back end, the product has been re-architected to support multiple identity repositories, or user data stores. Thus Release 4 Access Manager supports not only an LDAP directory such as Directory Server, but other data storage protocols and formats as well. Release 4 Access Manager includes new interfaces and new services to support the integration of multiple identity repositories.
On the front end, a new Access Manager Console is used to configure the new Access Manager services and identity repositories.
The new functional capabilities and interfaces make Release 4 Access Manager a major new release. In order to provide backward compatibility, Release 4 can be run in legacy mode, which supports the Java ES components that depend on Release 3 Access Manager services (for more information, see “Compatibility Issues).
Access Manager Upgrade Roadmap
Table 9-1 shows the supported Access Manager upgrade paths to Java ES Release 4.
Note
Upgrade of Access Manager is recommended only if Access Manager only has to be upgraded and Directory Server is in Remote machine. Any other upgrade scenario is not supported.
Access Manager Data
Access Manager, like other Java ES components, makes use of various kinds of data that for any specific upgrade might need to be migrated to an upgraded version. The following table shows the type of data that could be impacted by an upgrade of Access Manager software.
Compatibility Issues
The new functional capabilities of Release 4 Access Manager involve the following new interfaces:
- Plug-ins for multiple back-end identity repositories
- New directory information tree structure for storing service configuration information so that authentication properties and authorization policies can be grouped into access control realms that can be associated with a user or group of users.
- New API for Access Manager clients
- New Access Manager Console user interface
Access Manager support for these new interfaces is enabled by configuring Access Manager to run in enhanced (Realm) mode. However, Realm mode is not compatible with the earlier Java ES Release 3 Access Manager. For example, directory data has to be migrated to support Realm mode operation. The
enhanced Access Manager Console is needed to support enhanced Access Manager services.
In addition, Realm mode does not support other Java ES components, such as Portal Server, Communications Express, Messaging Server, and others.
To support backward compatibility, Release 4 Access Manager can be configured to run in Legacy mode. With some minor exceptions (see Sun Java System Access Manager 7 2005Q4 Release Notes (http://docs.sun.com/doc/819-2134), Legacy mode is backwardly compatible with Release 3 Access Manager.
Legacy mode is necessary to support other Java ES components, as well as older versions of Access Manager policy agents, which cannot interoperate with Access Manager in Realm mode. This incompatibility is an important upgrade consideration, and means in most Java ES deployments, that Access Manager should be upgraded to Release 4 Legacy mode.
Even when configured to run in Legacy mode, however, Release 4 Access Manager is incompatible with Release 3 Delegated Administrator.
Access Manager Dependencies
Access Manager dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Access Manager software. Changes in Access Manager interfaces or functions, for example, could require upgraded version of components upon which Access Manager depends. The need to upgrade such components depends upon the specific upgrade path.
Access Manager has dependencies on the following Java ES components:
- Shared components. Access Manager has dependencies on specific Java ES shared components (see Table 1-6 on page 39). Access Manager upgrades might depend upon upgraded versions of these shared components.
- Web Container. Access Manager depends upon web container services, which can be provided either by Java ES Web Server and Java ES Application Server. Access Manager upgrades must therefore be re-configured for a web container instance. In addition, any customized JSPs for the Access Manager console or for the authentication UI need to be migrated to the upgraded Access Manager environment.
- Directory Server. Access Manager stores configuration data and also accesses user data stored in Directory Server. As a result, Access Manager upgrades might require extensions of directory schema.
Upgrading Access Manager from Java ES Release 3This section includes information about upgrading Access Manager from Java ES 2005Q1 (Release 3) to Java ES 2005Q4 (Release 4). The section covers the following topics:
Introduction
When upgrading Java ES Release 3 Access Manager to Release 4, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is performed by removing previous versions and newly installing Release 4.
- Upgrade Dependencies. Access Manager has dependencies on a number of Java ES shared components and other products. For upgrading Access Manager, all other products have to be uninstalled and re-installed.
- Backward Compatibility. Release 4 Access Manager is not compatible with Release 3, however it does support a compatible legacy mode (see Compatibility Issues).
- Upgrade Rollback. There is no utility for rolling back the Access Manager upgrade. In fact, the number of re-configurations required to roll back Access Manager to its original state make such a rollback impractical.
Full Access Manager Upgrade
This section describes how to perform a full Access Manager upgrade from Java ES Release 3 to Java ES Release 4:
Pre-Upgrade Tasks
Before you upgrade Access Manager, perform the procedures described in the following sections.
Verify Current Version Information
You can verify the current version of Access Manager using the following command:
Table 9-3 Access Manager Version Verification Outputs
Java ES Release
Access Manager Version Number
Release 3
6 2005Q1
Release 4
7 2005Q4
Upgrade Access Manager Dependencies
It is recommended that all Java ES components on a computer system (and in a computing environment) be reinstalled to Java ES Release 4.
Back Up Directory Server Data
The Access Manager upgrade process uses scripts that modify Directory Server schema. Therefore, before you upgrade Access Manager, back up your Directory Server data using the Directory Server Console or a command-line utility such as db2bak.
For more information about backing up Directory Server, see the Sun Java System Directory Server Administration Guide (http://docs.sun.com/doc/817-7613).
Back Up Release 3 Access Manager Configuration Information
Because the re-configuration of Release 4 Access Manager software requires the re-configuration of the Release 3 version, it is important to back up configuration files to a known location. The following files should be backed up:
Back Up Web Container Customized Files
If you have any web container customized files referenced by Access Manager, you should back them up. These customizations might include the following:
Tip
Make note of your customizations so you can re-apply them using the backed-up code after you upgrade Access Manager.
Back Up Release 3 Access Manager Log and Debug Files
For the purpose of analyzing system state information, it is a good idea to back up log and debug files so they are not lost. These files are at the following locations:
Obtain Required Configuration Information and Passwords
To upgrade Access Manager, you must provide specific configuration information, including:
Note
Before uninstalling all other Java ES components, backup the required data. For more information about backing up other components see the upgrade guides of the respective components.
Upgrading Access Manager
The upgrade of Access Manager software to Java ES Release 4 includes procedures for re-configuring Access Manager and for migrating Access Manager data.
Upgrade Summary
The procedure for upgrading Access Manager consists of the following steps:
- Remove the Java ES Release 3 Version of Access Manager and all other installed components. Use the Java ES uninstaller.
- Install the Java ES Release 4 Version of Access Manager. Use the Java ES Release 4 installer with the Configure Later option.
- Re-customize JSPs for Access Manager
- Unjar the upgrade.jar file
- Update the directory structure and schema. Use the amupgrade.bat.
These steps are each documented in the following procedures.
Upgrade Procedures
- Remove the Java ES Release 3 Version of Access Manager and other components.
- Install the Java ES Release 4 Version of Access Manager.
- Re-customize JSPs for Access Manager.
Re-apply the Release 3 customizations to JSPs for the Access Manager Console and authentication user interface (UI) that you saved under Back Up Web Container Customized Files.
- Copy the customized JSP files to the correct directories.
- Console: AccessManager-base\web-src\applications\console
- Authentication UI:
AccessManager-base\web-src\services\config\auth\default or AccessManager-base\web-src\services\config\auth\default_locale (where Locale is a locale indicator like ja)
For more information, see the Sun Java System Access Manager Developer’s Guide (http://docs.sun.com/doc/819-2139).
- Configuring Access Manager
Configure Access Manager for your specific web container by running the amconfig.bat. The amconfig.bat (and the associated AMConfigurator.properties input file) resides in the following directory:
AccessManager-base\setup
For information about the amconfig.bat and the AMConfigurator.properties file, see the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).
To configure and deploy Access Manager to the web container, set the configuration parameters in config-file.
All the parameters need to be set correctly. Some of the values can be migrated from the AMConfig.properties file and others are more specific to the upgrade procedure, as shown in the following table.
For other parameters, provide the same values that were used in the Release 3 configuration that you are upgrading, unless you are changing web container or passwords.
- Update the directory structure and schema.
Release 4 Access Manager co-exists with the Release 3 directory structure, but the structure must be modified to support Release 4 capabilities. Update the Access Manager directory structure and schema to Release 4 by running the amupgrade.bat, which is installed in the following directory:
AccessManager-base\upgrade\amupgrade.bat
- Obtain the values of the following parameters to be requested by the amupgrade.bat:
- Run the amupgrade.bat.
cd AccessManager-base\upgrade\amupgrade.bat
If the upgrade is successful, the script displays “Upgrade completed.”
- Check the following upgrade log file for information about the directory schema extensions:
<install-dir>\AccessManager\Setup\AccessManager_upgrade_*.log
Verifying the Access Manager Upgrade
After you finish the upgrade procedure, verify that it was successful as follows:
- Start Access Manager.
Start the web container in which Access Manager is deployed.
- Log in to the Access Manager console as amadmin using the following URL:
http://hostname.domain:port/amconsole
where hostname.domain:port is the fully qualified host name and port number of the web container you are using.
Verify that new Release 4 services referred to in “About Java ES Release 4 Access Manager” on page 200 are available under the “Service Configuration” tab.
- Review Access Manager trouble shooting files for errors.
The files are located at <install-dir>\AccessManager\debug
Post-Upgrade Tasks
If you are using the Security Assertion Markup Language (SAML) service, you must add and enable a SAML authentication module using the Access Manager console. For information on creating a SAML authentication module instance, refer to the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).
Rolling Back the Upgrade
No scripts are provided for rolling back Access Manager to its pre-upgrade state. The process must be performed manually using Access Manager data that was backed up as part of the pre-upgrade tasks (see Back Up Release 3 Access Manager Log and Debug Files). Rollback is too difficult to be practical.