Chapter 9 Access Manager

This chapter describes how to upgrade Access Manager software from previous Java ES releases to Java ES 5: Sun Java System Access Manager 7.1.

The chapter provides a general overview of Access Manager upgrade issues and procedures for the different upgrade paths supported by Java ES 5 (Release 5).

• Overview of Access Manager Upgrades

• Upgrading Java ES Release 5 Access Manager from Java ES Release 4

---

Note –

File locations in this chapter are specified with respect to a directory path referred to as AccessManager-base. At least part of this path might have been specified as an installation directory when Access Manager was initially installed. If not, the Java ES installer assigned a default value.

The default value of AccessManager-base is C:\Program Files\Sun\JavaES5\identity.

---

Overview of Access Manager Upgrades

The following sections describe general aspects of Access Manager that affect upgrading to Java ES release 5:

• About Java ES 5 Access Manager

• Access Manager Upgrade Roadmap

• Access Manager Data

• Access Manager Compatibility Issues

• Access Manager Dependencies

About Java ES 5 Access Manager

Java ES Release 5 Access Manager 7.1 is a minor release that contains several bugs fixes and RFE's to the Java ES 4 Access Manager 7.0 release. Access Manager 7.1 includes the Java ES Monitoring Framework, which creates are new shared component dependencies. No major changes occurred in terms of functionality. In order to maintain backward compatibility with other components in the Java ES Stack, Access Manager 7.1 can be run in the legacy mode.

Access Manager Upgrade Roadmap

The following table shows the supported Access Manager upgrade paths to Java ES Release 5.

Table 9–1 Upgrade Paths to Java ES Release 5: Sun Java System Access Manager 7.1

Java ES Release	Access Manager Release	General Approach	Reconfiguration Required
Release 4	Sun Java System Access Manager 7.0 2005Q4	Direct upgrade: Performed by doing a full installation and reconfiguration of Release 5	Configuration data Web container  Customized JavaServer PagesTM (JSPTM) for Access Manager console and authentication UI Directory schema

---

Note –

Before starting the upgrade process for Access Manager, the upgrade for Web container and Directory Server should have been completed.

---

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.

Table 9–2 Access Manager Data Usage

Type of Data	Location	Usage
Configuration data	AccessManager-base\config\AMConfig.properties AccessManager-base\config\serverconfig.xml Java Archive (JAR) files for authentication and customized modules AccessManager-base\lib	Configuration of Access Manager and its integration with a back-end data store
Web container configuration	Web Server:  server.policy and server.xml files in WebServer-base\https-hostname\config Application Server:  server.policy and domain.xml files in ApplicationServer-base\domain\domain1\config	Configuration of Access Manager web container instance
Customization data (Web container customized JSP files)	Admin Console:  AccessManager-base\web-src\applications Authentication UI:  AccessManager-base\web-src\services	Configuration of Access Manager administration interfaces
Directory schema Services configuration User data	Directory Server	Access Manager provides authentication and authorization services for end users, based on services configuration, user, and policy data that is stored in a directory
Dynamic application data	None	Access Manager does not persistently store application data such as session state

Access Manager Compatibility Issues

Release 5 Access Manager is backwardly compatible with Release 4 Access Manager. Note that Release 4 Access Manager was a major release that, except when configured to run in Legacy mode, broke compatibility with earlier releases. Likewise, Release 5 Access Manager, unless configured to run in Legacy mode, is not backwardly compatible with the Java ES 4 Access Manager running in Legacy mode.

Legacy mode is necessary to support other Java ES components, as well as older versions of Access Manager policy agents that 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 5 Legacy mode even when configured to run in Legacy mode.

Access Manager Dependencies

Access Manager dependencies on other Java ES components can affect the procedure for upgrading and reconfiguring 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, as listed inTable 1–7. 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 reconfigured 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.

Web Container Upgrade Scenarios

Access Manager can be deployed in a web container provided by either Web Server or Application Server. As a result, the upgrade of Access Manager to Release 5 can be complicated by the possibility of also having upgraded to Release 5 the web container in which it is deployed. In this regard, there are a number of web container upgrade scenarios possible, enumerated in the following table:

Table 9–3 Web Container Upgrade Scenarios for Access Manager Upgrade

Scenario	Web Container in which Access Manager is Originally Deployed	Web Container in which Access Manager is Deployed After Upgrade	Applicable Access Manager Upgrade Paths: Upgrades From
Scenario 1	Web Server 6.x	Web Server 7.0	Release 4
Scenario 2	Application Server 8.1	Application Server 8.2	Release 4

You must be careful when upgrading Access Manager (for example when using the amconfig.bat) to provide values appropriate to the upgrade scenario in Table 9–3that applies, especially when there is a major version upgrade of the web container.

Upgrading Java ES Release 5 Access Manager from Java ES Release 4

This section includes information about upgrading Access Manager from Java ES 4 to Java ES 5. The section covers the following topics:

• Introduction to Upgrading Access Manager

• Access Manager Upgrade

• Coexistence of Release 5 with Earlier Directory Data

Introduction to Upgrading Access Manager

When upgrading Java ES Release 4 Access Manager to Release 5, consider the following aspects of the upgrade process:

• General Upgrade Approach. The upgrade is performed by installing Release 5. Reconfiguration of Access Manager is subsequently performed using the amconfig.bat file, and directory schema is migrated using the amupgrade.bat file.

• Upgrade Dependencies. Access Manager has dependencies on a number of Java ES shared components and other products, as listed in Table 1–7.

  In addition, Release 5 Access Manager is dependent upon Directory Server, Web Server, or Application Server, as described in Access Manager Dependencies. Because these are soft upgrade dependencies, upgrade of these components is optional with respect to upgrade of Access Manager to Release 5.

• Backward Compatibility. Release 5 Access Manager is compatible with Release 4. Access Manager 7.1 will continue to work with Release 4 Access Manager configuration for existing features. New features that access new configuration data required upgrading of Access Manager data. These features include Java ES monitoring and feature improvements in authentication, policy, and delegation.

• Upgrade Rollback. No utility exists for rolling back the Access Manager upgrade. Do not to uninstall Release 4 Access Manager. In order to restore Release 4 Access Manager, you should manually backup the Directory Server data. The best approach to rollback is to create a parallel installation using backed-up configuration files, and testing this parallel installation before performing the upgrade. This process enable you to revert to the parallel installation if necessary.

Access Manager Upgrade

This section describes how to perform a Access Manager upgrade from Java ES 4 to Java ES 5. The section covers the following topics:

• Pre-Upgrade Tasks

• To Upgrade Access Manager

• To Verify the Access Manager Upgrade

• Post-Upgrade Tasks

Pre-Upgrade Tasks

Before you upgrade Access Manager, perform the procedures described in the following sections:

• Upgrading Access Manager Dependencies

• Backing Up Directory Server Data

• Back Up Release 4 Access Manager Configuration Information

• To Verify Current Version Information

Upgrading Access Manager Dependencies

All Java ES components on a computer system and in a computing environment should be upgraded to Java ES Release 5. Access Manager has hard upgrade dependencies on only a couple of shared components.

If you choose to upgrade Access Manager product component dependencies, you should do so in the order below,skipping any components that might already have been upgraded, before you upgrade Access Manager. Upgrade of shared components is normally achieved automatically by the Java ES installer.

1. Shared Components. All shared components required by Access Manager are upgraded automatically by the Java ES installer when you perform an upgrade of Access Manager to Release 5.

2. Directory Server (optional). Instructions for upgrading Directory Server to Release 5 are provided in Chapter 2, Directory Server.

   Make sure that the Release 5 Directory Server uses the same port as of Release 4 Directory Server.

3. Web Container Software (optional). Instructions for upgrading Web Server or Application Server are provided in Chapter 4, Web Server and Chapter 6, Application Server respectively.

   If web container software is not upgraded before Access Manager, the upgrade procedure will configure and redeploy Access Manager to the existing web container.

   Make sure that the Release 5 web container uses the same port as of Release 4 web container.

Backing 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.

Back Up Release 4 Access Manager Configuration Information

Because the reconfiguration of Release 5 Access Manager software requires the reconfiguration of the Release 4 version, you should back up configuration files to a known location. The following Web container configuration files should be backed up:

• For Web Server: server.policy and server.xml files located in WebServer-base\https-hostname\config

• For Application Server: server.policy and domain.xml files located in ApplicationServer-base\domain\domain1\config

To Verify Current Version Information

Type the following command.

AccessManager-base\bin\amadmin --version

The outputs that indicate the Access Manager version are:

Release 5

Access Manager 7.1

Release 4

Access Manager 7 2005Q4

To Upgrade Access Manager

Before You Begin

• Obtain Access Manager administrator user ID and password, LDAP user ID and password, and Directory Manager name and password for the Directory Server instance that Access Manager is using.

• Before uninstalling all other Java ES components, back up the required data. For more information about backing up other components see the upgrade guides of the respective components.

1. Log in as administrator to the machine where Java ES 4 Access Manager is installed.

2. Manually backup the Access Manager DIT (Directory Server data).

3. Stop the following Java ES 4 services:

   • Web Server

   • Directory Server

   • Directory Proxy Server

   • Application Server

   • Instant Messaging

   • Calender Server

   • Messaging Server

4. Install the Java ES 5 Access Manager.

   For Java ES 5 Access Manager installation instructions, see the Sun Java Enterprise System 5 Installation Guide for Microsoft Windows.

   ---

   Note –

   Restart the machine after installing Java ES 5 Access Manager.

   ---

5. Re-customize JavaServer Pages for Access Manager.

   1. Re-apply the Release 4 customization to JavaServer Pages for the Access Manager Console and authentication user interface (UI) present in the Release 4 installation location.

   2. 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.

6. Configure Access Manager.

   Configure Access Manager for your specific web container by running the amconfig.bat file. The amconfig.bat file and the associated AMConfigurator.properties input file resides in the AccessManager-base\setup directory.

   For information about the amconfig.bat file and the AMConfigurator.properties file, see the Sun Java System Access Manager Administration Guide.

   Perform the steps to reconfigure and redeploy Access Manager to the web container as described in To Reconfigure and Redeploy Access Manager.

7. Update the directory structure and schema.

   Release 5 Access Manager coexists with the Release 4 directory structure, but the structure must be modified to support Release 5 capabilities. Update the Access Manager directory structure and schema to Release 5 by running the amupgrade.bat file, which is installed in the AccessManager-base\upgradedirectory.

   1. Obtain the values of the following parameters to be requested by the amupgrade.bat:

      Parameter	Value
      Directory Server Host	Set the fully qualified name: hostname.domain.
      Directory Server Port	Specify a non-SSL port number Default: 389.
      Directory Manager DN	Default: cn=Directory Manager.
      Directory Manager Password
      Access Manager Administrator User ID Default: amadmin	Default: amadmin.
      Access Manager Administrator Password
      Enable Realm Mode	Y/N: Yes means Realm Mode is enabled and services data is migrated to new Realm tree. No (default) means services data remain in Legacy Mode.

   2. Run the AccessManager-base\upgrade\amupgrade.bat file.

      If the upgrade is successful, the script displays “Upgrade completed.”

   3. Check the following upgrade log file for information about the directory schema extensions:

      AccessManager-base\setup\AccessManager_upgrade_num.log

8. Enable the components disabled during reconfiguration of Access Manager.

9. Start Access Manager.

   Restart the web container in which Access Manager is deployed.

To Reconfigure and Redeploy Access Manager

1. If you chose to upgrade your web container software, as described in Upgrading Access Manager Dependencies, make sure the upgrade is complete

2. Make sure that the administrative instance of your web container is running, and is in a mode supported by the amconfig.bat file, as indicated in the table below:

   Web Container	Supported Mode	Default Port Number
   Application Server (8.x): Java ES 4 and 5	SSL (secure)   non-SSL	4849
   Web Server (7.0):  Java ES 5	SSL (secure)	8989
   Web Server (6.x): Java ES 4	non-SSL	8888

3. If the web container is running in SSL mode, make sure that the container's SSL certificates have not expired and are still valid.

4. If Access Manager is deployed in Release 5 Web Server, disable all Java ES components depending on Access Manager that are running in the same instance as Access Manager.

   These components would likely be components such as Portal Server or Sun Java Communications Suite; Communications Express, Instant Messaging, or Delegated Administrator. The procedure is as follows:

   1. Log in as administrator at https://host:8989

   2. Go to Edit Virtual Server.

   3. Select the Web Applications tab.

   4. Select all Access Manager dependent applications.

   5. Click Disable.

   6. Click Save.

   7. Click deployment pending | Deploy Config.

      The configuration change will propagate to the Web Server instance

5. Check that Directory Server and the appropriate web container are running.

6. Set the configuration parameters in the AMConfigurator.properties file.

   Some of the parameter values can be migrated from the AMConfig.properties file and others are more specific to the upgrade procedure, as shown in the following table.

   Parameter	Value
   Upgrade Parameters
   DEPLOY_LEVEL	Set to 26 for undeploy  Set to 1 for reconfigure and deploy
   DIRECTORY_MODE	Set to 5 (Existing Upgrade)
   AM_REALM	Set to disabled. Because Realm Mode is disabled, Legacy Mode is therefore enabled
   JAVA_HOME	Set to the JDK Release 5 directory
   WEB_CONTAINER	Set to the value appropriate to the web container type you are using and fill out only the corresponding section of the configuration file.
   WS61_INSTANCE (If using Web Server as the web container)	Set to https-hostname.domain where the value above matches the instance name in install-dir\webserver The value is case-sensitive.
   AS81_INSTANCE (Using Application Server 8.x as the web container)	Set to Application Server.x instanceName Default: server
   AS81_INSTANCE _DIR (Using Application Server 8.x as the web container)	Set to Application Server.x domain directory for the instance Default: AppServer8Config-base\domains\domain1
   AS81_DOCS_DIR (Using Application Server 8.x as the web container)	Set to Application Server.x docroot directory for the instance Default: AppServer8Config-base\domains\domain1\docroot
   AS81_ADMIN_IS_SECURE  (Using Application Server 8.x as the web container)	Set to false Default: true
   Migrated from AMConfig.properties
   SERVER_PROTOCOL	com.iplanet.am.server.protocol
   SERVER_PORT	com.iplanet.am.server.port
   SERVER_HOST	com.iplanet.am.server.host
   DS_HOST	com.iplanet.am.directory.host
   DS_PORT	com.iplanet.am.directory.port
   ROOT_SUFFIX	com.iplanet.am.defaultOrg
   CONSOLE_DEPLOY_URI	com.iplanet.am.console.deploymentDescriptor
   SERVER_DEPLOY_URI	com.iplanet.am.services.deploymentDescriptor
   PASSWORD_DEPLOY_URI	com.sun.identity.password.deploymentDescriptor
   AM_ENC_PWD	am.encryption.pwd

   For other parameters, provide the same values that were used in the Release 4 configuration that you are upgrading, unless you are changing web container or passwords. For example, if you have upgraded Web Server to Release 5, provide the values from the following table.

   Parameter	Value
   WS_CONFIG	The name of the Web Server configuration: configName
   WS_INSTANCE	https-configName
   WS_HOME	WebServer7-base
   WS_PROTOCOL	http or https
   WS_HOST	Fully qualified host name on which Web Server instance is listening for connections
   WS_PORT	Port on which Web Server instance is listening for connections
   WS_ADMINPORT	Port on which Web Server administration instance is listening for connections
   WS_ADMIN	Web Server administrator user ID
   WS_ADMINPASSWORD	Web Server administrator password

7. Run AccessManager-base\setup\amconfig.bat to undeploy Access Manager.

   1. Set the value of DEPLOY_LEVEL to 26 in the AccessManaget-base\setup\AMConfigurator.properties file.

   2. Change to the setup directory.

      cd AccessManager-base\setup

   3. Run amconfig.bat file.

8. Run AccessManager-base\setup\amconfig.bat to reconfigure Access Manager and deploy into web container.

   1. Set the value of DEPLOY_LEVEL to 1 in the AccessManager-base\setup\AMConfigurator.properties file.

   2. Change to the setup directory.

      cd AccessManager-base\setup

   3. Run amconfig.bat file.

To Verify the Access Manager Upgrade

Type the following command.

AccessManager-base\bin\amadmin --version

The outputs that indicate the Access Manager version are:

Release 5

Access Manager 7.1

Release 4

Access Manager 7 2005Q4

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, see the Sun Java System Access Manager Administration Guide.

Coexistence of Release 5 with Earlier Directory Data

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.

---

Note –

Upgrading multiple instances of Access Manager installed on the same host system is not supported in the current release. If you have multiple instances on the same host, after you upgrade the main instance, you must then recreate the additional instances.

---

The procedure for upgrading Access Manager from Release 4 includes a step for updating directory schema to support Release 5. Release 4 Access Manager does not support Release 5 directory schema, however Release 5 Access Manager does support Release 4 directory schema.

Java ES Release 5 Access Manager and Release 4 Access Manager instances can coexist and run concurrently against the same Directory Server only if the directory schema has not yet been updated to Release 5. Therefore, in rolling upgrades, the directory schema should not be updated to Release 5 until all other steps in the upgrade procedure have first been performed for all Access Manager instances.

That is, in performing rolling upgrades, upgrade each instance of Access Manager as described Upgrading Java ES Release 5 Access Manager from Java ES Release 4, except for the step on updating directory structure and schema. When all instances have been upgraded, then that step can be performed.