Migrating a Version 2.2 Policy Agent to Version 3.0

In this scenario, you have upgraded an Access Manager 7.1 or Access Manager 7 2005Q4 deployment to OpenSSO Enterprise 8.0 and you also want to migrate an existing version 2.2 policy agent to version 3.0. After you migrate a version 2.2 agent, the agent can use the new version 3.0 agent features.

Before you can migrate a version 2.2 agent, a corresponding version 3.0 agent must exist. Some version 3.0 agents are available as patch releases. To determine the available version 3.0 agents, check the agent guides in the following documentation collection: http://docs.sun.com/coll/1767.1.

To migrate a version 2.2 policy agent to version 3.0, the version 3.0 agentadmin program includes the new --migrate option. The --migrate option performs these functions for a 2.2 agent:

• Migrates the agent's binary files

• Updates the agent's container configuration

• Converts the agent's AMAgent.properties file to the new version 3.0 OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties files

• Creates new deployment directories for migrated 3.0 agents, starting with Agent_001. The program does not create a one-to-one mapping of directories. For example, if the 2.2 agents have the Agent_001 and Agent_003 directories (Agent_002 was removed), the migrated 3.0 agents will have the Agent_001 and Agent_002 directories.

The agentadmin program does not modify the version 2.2 agent deployment directory files in case you need these files after you migrate.

Migrating a version 2.2 agent involves these general steps:

1. On the server where the version 2.2 agent is installed, run the version 3.0 agentadmin program with the --migrate option.

   To get the version 3.0 agentadmin program, you must download the version 3.0 agent that corresponds to the version 2.2 agent you are migrating. For example, if you are migrating the version 2.2 Apache HTTP Server agent, download the corresponding version 3.0 Apache HTTP Server agent.

2. On the OpenSSO Enterprise server, run the ssoadm utility to create the new version 3.0 agent configuration in the OpenSSO Enterprise centralized agent configuration repository.

   You must use the ssoadm utility from the openssoAdminTools.zip file on the OpenSSO Enterprise server. For information, see Chapter 6, Installing the OpenSSO Enterprise Utilities and Scripts, in Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide.

In the following procedure, the migrated version 3.0 agent instance uses a new agent profile named Migratedv3.0Agent in the examples. The old version 2.2 and new version 3.0 agent profile passwords are the same. If you need to change the password for the new version 3.0 agent profile, refer to the respective policy agent 3.0 guide.

To Migrate a Version 2.2 Agent

1. Login to the server where the version 2.2 agent is installed.

   To migrate the agent, you must have write permission to the version 2.2 agent's web container files and directories.

2. If necessary, set your JAVA_HOME environment variable to point to an installed JDK version 1.5 or later.

3. Stop the web container instance for the version 2.2 agent.

4. Create a directory to download and unzip the version 3.0 agent. For example: /opt/v30agent

5. Download and unzip the version 3.0 agent that corresponds to the version 2.2 agent you are migrating.

   The version 3.0 agents are available from the Sun Downloads site under View by Category, Identity Management, and then Policy Agents: http://www.sun.com/download/index.jsp

6. Change to the version 3.0 agent's /bin directory.

   For example, if you downloaded and unzipped the version 3.0 Apache HTTP Server 2.0.x agent in the /opt/v30agent directory:

   cd /opt/v30agent/web_agents/apache_agent/bin

7. Run the version 3.0 agentadmin program with the --migrate option. For example:

   ./agentadmin --migrate

8. When the agentadmin program prompts you, enter the path to the version 2.2 agent's deployment directory. For example:

   /opt/v22agent/web_agents/apache_agent

   In this example, /opt/v22agent is the directory where you downloaded and unzipped the version 2.2 agent.

   The agentadmin program migrates the version 2.2 agent.

9. Copy the Agent_nnn/config/OpenSSOAgentConfiguration.properties file to the /bin directory where ssoadm is installed on the OpenSSO Enterprise server.

   Agent_nnn is the policy agent instance. For example: Agent_001 or Agent_002

10. In OpenSSOAgentConfiguration.properties, add the un-encrypted version 2.2 agent profile password at the end of the file, as follows:

    userpassword=un-encrypted-v2.2–agent-profile-password

11. On OpenSSO Enterprise server, create a password file for the OpenSSO Enterprise administrator (amadmin).

    This password file is an ASCII text file with only one line specifying the amadmin password in plain text. For example: /tmp/amadminpw

12. On OpenSSO Enterprise server, run ssoadm to create a new agent configuration in the OpenSSO Enterprise centralized agent configuration repository. For example:

    cd tools-zip-root/opensso/bin
    ./ssoadm create-agent -b Migratedv3.0Agent -t WebAgent -u amadmin 
    -f /tmp/amadminpw -D ./OpenSSOAgentConfiguration.properties

    In this example:

    • tools-zip-root is the directory where you unzipped the openssoAdminTools.zip file.

    • Migratedv3.0Agent is the version 3.0 agent profile name.

    • WebAgent is the agent type for web agents. For a Java EE agent, the agent type is J2EEAgent.

    • /tmp/amadminpw is the path to the amadmin password file.

    Caution: After you run ssoadm, you might want to delete OpenSSOAgentConfiguration.properties from the /bin directory. This file contains sensitive information, including as the agent profile password, and the original file is maintained on the server where the agent is installed.

13. Restart the web container instance for the migrated agent.

Next Steps

After you migrate the agent, you can manage the new 3.0 agent configuration using the OpenSSO Enterprise Administration Console or the ssoadm utility.