|
| |
| Sun Java Enterprise System Upgrade Guide for HP-UX | |
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.
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 or Release 2 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. If Access Manager is upgraded to Release 4, then Delegated Administrator also must be upgraded to Release 4 to provision users for Messaging Server and Calendar Server. However, Messaging Server and Calendar Server do not, themselves, have to be upgraded to Release 4.
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). 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, Java ES Application Server, or third-party web containers (from Weblogic and WebSphere). 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. An ampre70upgrade script is provided for removing the Release 3 version and the Java ES installer is then used to install Release 4. Re-configuration of Access Manager is subsequently performed using the amconfig script, and directory schema is migrated using the amupgrade script.
- Upgrade Dependencies. While Access Manager has dependencies on a number of Java ES shared components (see Table 1-6), Release 4 Access Manager is compatible with the Release 3 versions of all these components. Upgrade of these components is therefore optional with respect to upgrade of Access Manager to Release 4.
In addition, Release 4 Access Manager is dependent upon Directory Server and Web Server (or Application Server or third-party web containers), as described in Access Manager Dependencies. However, these are soft upgrade dependencies; upgrade of these components is optional with respect to upgrade of Access Manager to Release 4.
- 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:
Upgrade Access Manager Dependencies
It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Java ES Release 4. However, because Access Manager does not require upgrading the Java ES Release 3 components upon on which it depends, this task is optional.
However, if you choose to upgrade all Access Manager dependencies, they should be upgraded in the following order, all before you upgrade Access Manager. You can skip any that might already have been upgraded.
- Shared Components. Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".
- Directory Server. Instructions for upgrading Directory Server to Release 4 are provided in Chapter 3, "Directory Server and Administration Server".
- Web Container Software. Instructions for upgrading Web Server or Application Server are provided in Chapter 5, "Web Server" and Chapter 8, "Application Server", respectively.
If web container software is not upgraded before Access Manager, the upgrade procedure (using the amconfig script) will configure and re-deploy Access Manager to the existing web container.
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 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:
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. Use the ampre70upgrade script.
- Use the Java ES Release 4 installer with the Configure Later option. Use the Java ES Release 4 installer with the Configure Later option.
- Undeploy Access Manager, re-configure, and re-deploy into a Web Container.. Use the amconfig script.
- Update the directory structure and schema. Use the amupgrade script.
These steps are each documented in the following procedures.
Upgrade Procedures
- Remove the Java ES Release 3 Version of Access Manager.
- Log in as root to the computer hosting Release 3 Access Manager.
- Change directory to the platform/Product/identity_svr/Tools directory in the Java ES Release 4 distribution.
- Obtain the values of the following parameters to be requested by the ampre70upgrade script:
Table 9-4 Configuration Parameters1: ampre70upgrade
Parameter
Value
Directory Server Host
Set the fully qualified name: hostname.domian
Directory Server Port
Specify a non-SSL port number1
Default: 389
Access Manager Administrator DN
Default:
uid=amadmin,ou=People,dc=iplanet,dc=com
Access Manager Administrator
Password
1The pre-upgrade process will not complete successfully if you specify a Directory Server SSL port such as the default SSL value of 636.
- Make sure that Directory Server is running or start it if it is not.
- Run the ampre70upgrade script.
./ampre70upgrade
The script backs up Access Manager configuration files and removes Release 3 packages.
- Install the Java ES Release 4 Version of Access Manager.
- Run the Java ES installer on the computer hosting Release 3 Access Manager.
- Select Access Manager from the selection panel.
If a “Conflict” message appears on the screen, it means the Installer has found Access Manager configuration information from the previous version, which is expected. Re-configuration will be performed in subsequent steps. You can ignore this “Conflict” message and proceed.
- Specify the same installation directory in which Release 3 was installed.
- Select the Configure Later option.
- Quit the Java ES installer when installation is complete.
- Upgrade mobile access software.
Access Manager mobile access software needs to be upgraded by patching the Release 3 version. The patches needed are shown in the following table:
Table 9-5 Patches1 to Upgrade Access Manager Mobile Access software
Description
Patch id
Mobile Access software
121724-01
Access Manager locale
121929-01
1Patch revision numbers are the minimum required for upgrade to Java ES Release 4. If newer revisions become available, use the newer ones instead of those shown in the table.
- Obtain the required patches using the patch numbers from Table 9-5.
Patches can be downloaded from:
- Log in as superuser.
su root
- Apply the patches.
swinstall -f patchlocation <patch_ID>
- 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 Release 3 Access Manager Configuration Information.
Then, copy the customized JSP files to the correct directories. For example, on HP-UX systems:
- 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).
- Undeploy Access Manager, re-configure, and re-deploy into a Web Container.
Configure Access Manager for your specific web container by running the amconfig script. The amconfig script (and the associated amsamplesilent template input file) resides in the following directory:
AccessManager-base/bin
For information about the amconfig script and the amsamplesilent template file, see the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).
Perform the following steps to re-configure and re-deploy Access Manager to the web container:
- If you choose to upgrade your web container software, as described in Upgrade Access Manager Dependencies, make sure the upgrade is complete.
- Check that Directory Server and the appropriate web container are running.
- Create an amconfig input file based on the amsamplesilent template input file:
cp amsamplesilent config-file
- 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.
- Run amconfig to undeploy Access Manager
Set the value of DEPLOY_LEVEL in config-file to 26.
cd /AccessManager-base/bin
./amconfig -s AccessManager-base/bin/config-file
- Run amconfig to reconfigure Access Manager and deploy into web container.
Set the value of DEPLOY_LEVEL in config-file to 1.
cd /AccessManager-base/bin
./amconfig -s AccessManager-base/bin/config-file
- 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 script, which is installed in the following directory:
AccessManager_base/identity/upgrade/scripts
- Obtain the values of the following parameters to be requested by the amupgrade script:
- Run the amupgrade script.
cd AccessManager-base/upgrade/scripts
export SHLIB_PATH=/opt/sun/private/lib:AccessManager-base/lib
./amupgrade
If the upgrade is successful, the script displays “Upgrade completed.”
- Check the following upgrade log file for information about the directory schema extensions:
HP-UX: opt/sun/install/logs
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 are available under the “Service Configuration” tab.
- Review the status of the upgrade by checking the following upgrade log files in the /var/opt/sun/install/logs directory:
Sun Java Enterprise System installer:
- Review Access Manager trouble shooting files for errors.
The files are located at /var/opt/sun/identity/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.
Multiple Instance Upgrades: Release 3 and Release 4 Co-existence
In some deployment architectures Access Manager is deployed on multiple computer systems to provide for high availability and scalability. The Access Manager instances access the same Directory Server. It is often desirable to upgrade the Access Manager instances sequentially without interrupting service. This section discusses the procedure for performing such rolling upgrades.
The procedure for upgrading Access Manager from Release 3 includes a step for migrating directory schema to support Release 4. Release 3 Access Manager does not support Release 4 directory schema, however Release 4 Access Manager does support Release 3 directory schema.
Java ES Release 4 Access Manager and Release 3 Access Manager instances can coexist and run concurrently against the same Directory Server only if the directory schema has not yet been migrated to Release 4. Therefore, in rolling upgrades, the directory schema should not be migrated to Release 4 until all Access Manager instances have been first upgraded to Release 4.
In performing rolling upgrades, upgrade each instance of Access Manager as described in Upgrading Access Manager, except for Step 6. When all instances have been upgraded, then that step can be performed.
Access Manager SDK-only Upgrades
In some deployment architectures, the Access Manager SDK component is installed on one or more computer systems without installing other Access Manager components on those computers. Access Manager SDK serves as a remote interface to Access Manager and must be re-configured for the same operational mode as Access Manager: Legacy or Realm. As a remote interface to Access Manager, the SDK does not need to be configured to access Directory Server.
If Access Manager SDK is being used to support a web component, such as Portal Server or Communications Express, which depends upon web container services, Access Manager SDK must be configured for the corresponding web container. However, Access Manager SDK can also support non-web components, and no web container is needed.
The procedure for upgrading Access Manager SDK is a subset of the procedure for the full Access Manager upgrade, based on the above characteristics.
This section describes how to perform an Access Manager SDK-only upgrade from Java ES Release 3 to Java ES Release 4:
Pre-Upgrade Tasks
The pre-upgrade tasks for Access Manager SDK are the same as for the full Access Manager upgrade, but exclude those related to Directory Server and administration tool customizations. The pre-upgrade tasks needed for Access Manager SDK are the following:
Upgrading Access Manager SDK
The upgrade procedures for Access Manager SDK are the same as for the full Access Manager upgrade, but exclude those related to administration tool customizations and migrating directory schema.
- Remove the Java ES Release 3 version of Access Manager SDK.
Follow the instructions in “Remove the Java ES Release 3 Version of Access Manager.” on page 209, except remove only Access Manager SDK.
- Install Java ES Release 4 version of Access Manager SDK.
Follow the instructions in “Install the Java ES Release 4 Version of Access Manager.” on page 210, except install only Access Manager SDK.
- Re-configure Access Manager SDK.
Follow the instructions in “Undeploy Access Manager, re-configure, and re-deploy into a Web Container.” on page 212, except set the DIRECTORY_MODE=5 and the DEPLOY_LEVEL parameter as follows:
Verifying the Access Manager SDK Upgrade
There are three ways you can verify a successful Access Manager SDK upgrade:
Upgrade Rollback
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.