Chapter 2 Vital Installation Information for a J2EE Agent in Policy Agent 2.2

To make the installation process of a J2EE agent in Policy Agent 2.2 simple, essential information required for the installation is provided in this chapter.

This chapter applies to all the J2EE agents in the Policy Agent 2.2 release. However, throughout this chapter, when a specific J2EE agent is used for example purposes, such as in a command, only one J2EE agent is shown, Policy Agent 2.2 for Sun Java System Application Server 8.1. These examples are provided to illustrate general format. Replace J2EE agent specific information where necessary.

When you are comfortable with the information presented in this chapter, move on to the installation as described in Chapter 3, Installing the IBM WebSphere Portal Server 6.0 Policy Agent.

In simple terms, this chapter provides information to help you with the following:

• Getting the J2EE agent distribution files on the machine that hosts the deployment container. The J2EE agent is going to protect the content on that deployment container.

• Issuing install-related commands using the agentadmin program. The agentadmin program is a command-line utility that you will use to install and configure the agent. You should know the supported command options besides the more common --install option.

• Locating the various J2EE agent files after you get them onto the deployment container.

• Configuring the J2EE agent with Access Manager 6.3 Patch 1 or greater, if such backward compatibility is desired.

• Creating a J2EE agent profile.

The information referred to in the preceding list is described in the following sections of this chapter:

• Format of the IBM WebSphere Portal Server 6.0 Distribution File

• Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2

• J2EE Agent Directory Structure in Policy Agent 2.2

• Configuring a J2EE Agent With Access Manager 6 2005Q1 (6.3)

• Creating a J2EE Agent Profile

Format of the IBM WebSphere Portal Server 6.0 Distribution File

The distribution file for the IBM WebSphere Portal Server 6.0 agent is a .zip archive named websphere_v60portal_agent.zip. After you download the file, unzip it using the appropriate utility or command for your platform. For example, on Solaris systems:

unzip websphere_v60portal_agent.zip

For more information see, Preparing to Install the IBM WebSphere Portal Server 6.0 Agent.

Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2

The agentadmin program is a required install and configuration tool for the 2.2 release of J2EE agents. The most basic of tasks, such as installation and uninstallation can only be performed with this tool.

The location of the agentadmin program is as follows:

PolicyAgent-base/bin

The following information about agentadmin program demonstrates the scope of this utility:

• All agent installation and uninstallation is achieved with the agentadmin command.

• All tasks performed by the agentadmin program, except those involving uninstallation, require the acceptance of a license agreement. This agreement is only presented the first time you use the program.

• The following table lists options that can be used with the agentadmin command and gives a brief description of the specific task performed with each option.

  A detailed explanation of each option follows the table.

In this section, the options described are the agentadmin program options that apply to all J2EE agents. Options that only apply to specific J2EE agents are relatively uncommon and are described where necessary within the corresponding J2EE agent guide.

agentadmin --install

This section demonstrates the format and use of the agentadmin command with the --install option.

Example 2–1 Command Format: agentadmin --install

The following example illustrates the format of the agentadmin command with the --install option:

./agentadmin --install [--useResponse] [--saveResponse] filename

The following arguments are supported with the agentadmin command when using the --install option:

--saveResponse

Use this argument to save all supplied responses to a state file, or response file, represented as filename in command examples. The response file, or state file, can then be used for silent installations.

--useResponse

Use this argument to install a J2EE agent in silent mode as all installer prompts are answered with responses previously saved to a response file, represented as filename in command examples. When this argument is used, the installer runs in non-interactive mode. At which time, user interaction is not required.

filename

Use this argument to specify the name of a file that will be created as part of the processing of this command. This file stores your responses when this argument is used in conjunction with the --saveResponse argument and provides your responses when this argument is used in conjunction with the --useResponse argument.

Example 2–2 Command Usage: agentadmin --install

When you issue the agentadmin command, you can choose the --install option. With the --install option, you can choose the --saveResponse argument, which requires a file name be provided. The following example illustrates this command when the file name is myfile:

./agentadmin --install --saveResponse myfile

Once the installer has executed the preceding command successfully, the responses are stored in a state file that can be used for later runs of the installer.

If desired, you can modify the state file and configure the second installation with a different set of configuration parameters.

Then you can issue another command that uses the ./agentadmin --install command and the name of the file that you just created with the --saveResponse argument. The difference between the previous command and this command is that this command uses the --useResponse argument instead of the --saveResponse argument. The following example illustrates this command:

./agentadmin --install --useResponse myfile

With this command, the installation prompts run the installer in silent mode, registering all debug messages in the install logs directory.

agentadmin --uninstall

This section demonstrates the format and use of the agentadmin command with the --uninstall option.

Example 2–3 Command Format: agentadmin --uninstall

The following example illustrates the format of the agentadmin command with the --uninstall option:

./agentadmin --uninstall [--useResponse] [--saveResponse] filename

The following arguments are supported with the agentadmin command when using the --uninstall option:

--saveResponse

Use this argument to save all supplied responses to a state file, or response file, represented as filename in command examples. The response file, or state file, can then be used for silent uninstallations.

--useResponse

Use this argument to uninstall a J2EE agent in silent mode as all uninstaller prompts are answered with responses previously saved to a response file, represented as filename in command examples. When this argument is used, the uninstaller runs in non-interactive mode. At which time, user interaction is not required.

filename

Use this argument to specify the name of a file that will be created as part of the processing of this command. This file stores your responses when this argument is used in conjunction with the --saveResponse argument and provides your responses when this argument is used in conjunction with the --useResponse argument.

Example 2–4 Command Usage: agentadmin --uninstall

When you issue the agentadmin command, you can choose the --uninstall option. With the --uninstall option, you can choose the --saveResponse argument, which requires a file name be provided. The following example illustrates this command where the file name is myfile:

./agentadmin --uninstall --saveResponse myfile

Once the uninstaller has executed the preceding command successfully, the responses are stored in a state file that can be used for later runs of the uninstaller.

If desired, you can modify the state file and configure the second uninstallation with a different set of configuration parameters.

Then you can issue another command that uses the ./agentadmin --uninstall command and the name of the file that you just created with the --saveResponse argument. The difference between the previous command and this command is that this command uses the --useResponse argument instead of the --saveResponse argument. The following example illustrates this command:

./agentadmin --uninstall --useResponse myfile

With this command, the uninstallation prompts run the uninstaller in silent mode, registering all debug messages in the install logs directory.

agentadmin --listAgents

This section demonstrates the format and use of the agentadmin command with the --listAgents option.

Example 2–5 Command Format: agentadmin --listAgents

The following example illustrates the format of the agentadmin command with the --listAgents option:

./agentadmin --listAgents

No arguments are currently supported with the agentadmin command when using the --listAgents option.

Example 2–6 Command Usage: agentadmin --listAgents

Issuing the agentadmin command with the --listAgents option provides you with information about all the configured J2EE agents on that machine. For example, if two J2EE agents were configured on Sun Java System Application Server 8.1, the following text demonstrates the type of output that would result from issuing this command:

The following agents are configured on this Application Server.

The following are the details for agent Agent_001 :-
Application Server Config Directory:
/var/opt/SUNWappserver/domains/domain1/config
Application Server Instance name: server1

The following are the details for agent Agent_002 :-
Application Server Config Directory:
/var/opt/SUNWappserver/domains/domain1/config
Application Server Instance name: server2

This example shows that two instances of the agent are configured: one for server1 and one for server2. Notice that the agentadmin program provides unique names, such as Agent_001 and Agent_002, to all the J2EE agents that protect the same instance of a deployment container, in this case Application Server 8.1. Each name uniquely identifies the J2EE agent instance.

agentadmin --agentInfo

This section demonstrates the format and use of the agentadmin command with the --agentInfo option.

Example 2–7 Command Format: agentadmin --agentInfo

The following example illustrates the format of the agentadmin command with the --agentInfo option:

./agentadmin --agentInfo AgentInstance-Dir

The following argument is supported with the agentadmin command when using the --agentInfo option:

AgentInstance-Dir

Use this option to specify which agent instance directory, therefore which agent instance such as Agent_002, you are requesting information about.

Example 2–8 Command Usage: agentadmin --agentInfo

Issuing the agentadmin command with the --agentInfo option provides you with information on the J2EE agent instance that you name in the command. For example, if you want information about a J2EE agent instance named Agent_002 configured on Sun Java System Application Server 8.1, you can issue the command illustrated in the following example to obtain the type of output that follows:

./agentadmin --agentInfo Agent_002

The following are the details for agent Agent_002 :-
Application Server Config Directory:
/var/opt/SUNWappserver/domains/domain1/config
Application Server Instance name: server2

In the preceding example, notice that information is provided only for the agent instance, Agent_002, named in the command.

agentadmin --version

This section demonstrates the format and use of the agentadmin command with the --version option.

Example 2–9 Command Format: agentadmin --version

The following example illustrates the format of the agentadmin command with the --version option:

./agentadmin --version

No arguments are currently supported with the agentadmin command when using the --version option.

Example 2–10 Command Usage: agentadmin --version

Issuing the agentadmin command with the --version option provides you with version information for the configured J2EE agents on that machine. For example, if a J2EE agent were configured on Sun Java System Application Server 8.1, the following text demonstrates the type of output that would result from issuing this command:

--------------------------------------------------------------------------
Sun Java(TM) System Access Manager Policy Agent for:
Sun Java(TM) System Application Server 8.1
--------------------------------------------------------------------------
Version: 2.2
Build Number: 05
AM 70 Client SDK Version: 20050810.2
AM 63 Client SDK Version: 20050914.1
Date: 2005-09-15 15:04 PDT
Build Platform: machinename

In the preceding example, notice that the Version field shows the major version number. The Build Number shows the minor version number. The Date field provides the date and time the agent was built, while the Build Platform field provides information about the platform on which the agent was built. The Client SDK versions signify the Access Manager–related client SDK versions that were shipped with the agent.

agentadmin --encrypt

This section demonstrates the format and use of the agentadmin command with the --encrypt option.

Example 2–11 Command Format: agentadmin --encrypt

The following example illustrates the format of the agentadmin command with the --encrypt option.

./agentadmin --encrypt AgentInstance-Dir fullpassfile

The following arguments are supported with the agentadmin command when using the --encrypt option:

AgentInstance-Dir

Use this option to specify which agent instance directory, therefore which agent instance such as Agent_002, for which the given password file will be encrypted. Encryption functionality requires that an encryption key for a J2EE agent instance be present in the AMAgent.properties configuration file of that specific J2EE agent instance.

fullpassfile

Use this option to specify the full path to the password file that will be encrypted.

The password file should be created as a J2EE agent pre-installation task. For more information, see Preparing to Install the IBM WebSphere Portal Server 6.0 Agent

Example 2–12 Command Usage: agentadmin --encrypt

Issuing the agentadmin command with the --encrypt option enables you to change the password for an existing agent profile in Access Manager after the agent is installed.

For example, issuing the following command encrypts the password file, pwfile1 for the J2EE agent instance directory Agent_001:

./agentadmin --encrypt Agent_001 pwfile1

The following is an example of an encrypted value:

ASEWEJIowNBJHTv1UGD324kmT==

Each agent uses a unique agent ID and password to communicate with Access Manager. Once the agent profile for a specific agent has been created in Access Manager, the installer enters the Policy Agent profile name and encrypted password in the respective J2EE agent AMAgent.properties configuration file for the agent instance. If you choose a new password for the Policy Agent profile, encrypt it and enter that encrypted password in the J2EE agent AMAgent.properties configuration file with the following property:

com.iplanet.am.service.secret

agentadmin --getEncryptKey

This section demonstrates the format and use of the agentadmin command with the --getEncryptKey option.

Example 2–13 Command Format: agentadmin --getEncryptKey

The following example illustrates the format of the agentadmin command with the --getEncryptKey option:

./agentadmin --getEncryptKey

No arguments are currently supported with the agentadmin command when using the --getEncryptKey option.

Example 2–14 Command Usage: agentadmin --getEncryptKey

This option may be used in conjunction with the --encrypt option to encrypt and decrypt sensitive information in the J2EE agent AMAgent.properties configuration file. Issuing the agentadmin command with the --getEncryptKey option generates a new encryption key for the J2EE agent.

For example, the following text demonstrates the type of output that would result from issuing this command:

./agentadmin -getEncryptKey


Agent Encryption Key : k1441g4EejuOgsPlFOSg+m6P5x7/G9rb

The encryption key is stored in the J2EE agent AMAgent.properties configuration file. Therefore, once you generate a new encryption key, use it to replace the value of the property that is currently used to store the encryption key. The following property in the J2EE agent AMAgent.properties configuration file stores the encryption key:

com.sun.identity.client.encryptionKey

For example, using the encryption key example provided previously, updating the encryption key value in the J2EE agent AMAgent.properties configuration file could appear as follows:

com.sun.identity.client.encryptionKey = k1441g4EejuOgsPlFOSg+m6P5x7/G9rb

Once you have updated the J2EE agent AMAgent.properties configuration file with the new encryption key, issue the agentadmin --encrypt command to actually encrypt a password. The --encrypt option uses the encryption key in its processing.

agentadmin --uninstallAll

This section demonstrates the format and use of the agentadmin command with the --uninstallAll option.

Example 2–15 Command Format: agentadmin --uninstallAll

The following example illustrates the format of the agentadmin command with the --uninstallAll option:

./agentadmin --uninstallAll

No arguments are currently supported with the agentadmin command when using the --uninstallAll option.

Example 2–16 Command Usage: agentadmin --uninstallAll

Issuing the agentadmin command with the --uninstallAll option runs the agent uninstaller in an iterative mode, enabling you to remove select J2EE agent instances or all J2EE agent instances. You can exit the recursive uninstallation process at any time.

The advantage of this option is that you do not have to remember the details of each installation-related configuration. The agentadmin program provides you with an easy method for displaying every instance of a J2EE agent. You can then decide, case by case, to remove a J2EE agent instance or not.

agentadmin --getUuid

This section demonstrates the format and use of the agentadmin command with the --getUuid option.

Example 2–17 Command Format: agentadmin --getUuid

The following example illustrates the format of the agentadmin command with the --getUuid option:

./agentadmin --getUuid userName IdType realmName

The following arguments are supported with the agentadmin command when using the --getUuid option:

userName

Use this first parameter of the --getUuid option to specify the name associated with the identity type. The identity type is represented in this example as the IdType parameter. Therefore, if the identity type is for a user, this userName parameter would be the name of that user.

IdType

Use this second parameter to specify a valid identity type. The following are examples of valid identity types: user, role, group, filtered role, agent, and such.

realmName

Use this third parameter to specify the name of the default organization of the Access Manager installation.

For example, if the ID of the user is manager, the identity type is role, and the realm name is dc=example,dc=com, the following would be the universal ID:

id=manager,ou=role,dc=example,dc=com

The universal ID concept is only valid starting with Access Manager 7.1. Do not use this option with earlier versions of Access Manager, such as version 6.3. If the application is deployed with Access Manager 6.3 principals or roles, replace the role-to-principal mappings with the distinguished name (DN) of the user in Access Manager 6.3.

Example 2–18 Command Usage: agentadmin --getUuid

In Access Manager 7.1, issuing the agentadmin command with the --getUuid option retrieves the universal ID of any identity type in Access Manager 7.1.

Use the correct universal ID generated by this command in a deployment descriptor that is application container specific.

agentadmin --usage

This section demonstrates the format and use of the agentadmin command with the --usage option.

Example 2–19 Command Format: agentadmin --usage

The following example illustrates the format of the agentadmin command with the --usage option:

./agentadmin --usage

No arguments are currently supported with the agentadmin command when using the --usage option.

Example 2–20 Command Usage: agentadmin --usage

Issuing the agentadmin command with the --usage option provides you with a list of the options available with the agentadmin program and a short explanation of each option. The following text is the output you receive after issuing this command:

./agentadmin --usage 

Usage: agentadmin <option> [<arguments>]

The available options are:
--install: Installs a new Agent instance.
--uninstall: Uninstalls an existing Agent instance.	
--listAgents: Displays details of all the configured agents.
--agentInfo: Displays details of the agent corresponding to the specified agent ID.
--version: Displays the version information.	
--encrypt: Encrypts a given string.
--getEncryptKey: Generates an Agent Encryption key.
--uninstallAll: Uninstalls all the agent instances.
--getUuid: Retrieves a universal ID for valid identity types.
--usage: Display the usage message.
--help: Displays a brief help message. 

The preceding output serves as the content for the table of agentadmin options, introduced at the beginning of this section.

agentadmin --help

This section demonstrates the format and use of the agentadmin command with the --help option.

Example 2–21 Command Format: agentadmin --help

The following example illustrates the format of the agentadmin command with the --help option:

./agentadmin --help

No arguments are currently supported with the agentadmin command when using the --help option.

Example 2–22 Command Usage: agentadmin --help

Issuing the agentadmin command with the --help option provides similar results to issuing the agentadmin command with the --usage option. Both commands provide the same explanations for the options they list. With the --usage option, all agentadmin command options are explained. With the --help option, explanations are not provided for the --usage option or for the --help option itself.

A another difference is that the --help option also provides information about the format of each option while the --usage option does not.

J2EE Agent Directory Structure in Policy Agent 2.2

The Policy Agent installation directory is referred to as the Policy Agent base directory (or PolicyAgent-base in code examples). The location of this directory and its internal structure are important facts that are described in this section.

Location of the J2EE Agent Base Directory in Policy Agent 2.2

Unzipping the J2EE agent binaries creates a directory named j2ee_agents, within which an agent-specific directory is created. For example, if the J2EE agent being installed is Policy Agent 2.2 for Sun Java System Application Server 8.1, the directory created is named am_as81_agent. For other J2EE agents, the directory name is slightly different, but the naming format is the same. To see the preceding directory name specific to the J2EE agent you are using, see Example 3–1.

This agent-specific directory is the Policy Agent base directory, referred to throughout this guide as the PolicyAgent-base directory. For the full path to the PolicyAgent-base directory, see Example 2–23.

Example 2–23 Policy Agent Base Directory

The directory you choose in which to unzip the J2EE agent binaries is referred to here as Agent_Home. The following path is an example of the location for the PolicyAgent-base directory for the IBM WebSphere Portal Server 6.0 agent:

Agent_Home/j2ee_agents/websphere_v60portal_agent

For other J2EE agents, the directory names are different, but the naming format is the same. To see the preceding path name specific to the J2EE agent you are using, see Example 3–1. References in this book to the PolicyAgent-base directory are references to the preceding path.

Inside the J2EE Agent Base Directory in Policy Agent 2.2

After you finish installing an agent by issuing the agentadmin ---install command and interacting with the installer, you must access J2EE agent files in order to configure and otherwise work with the product. Within the Policy Agent base directory are various subdirectories that contain all agent configuration and log files. The structure of the Policy Agent base directory for a J2EE agent is illustrated in Table 2–2.

The list that follows the table provides information about many of the items in the example Policy Agent base directory. The Policy Agent base directory is represented in code examples as PolicyAgent-base. The full path to any item in this directory is as follows:

PolicyAgent-base/item-name

where item-name represents the name of a file or subdirectory. For example, the full path to the bin directory is as follows:

PolicyAgent-base/bin

The preceding example of PolicyAgent-base lists files and directories you are likely to find in this directory. The notable items in this directory are summarized in the list that follows:

bin

This directory contains the agentadmin script for the agent bits. You will use this script a great deal. For details about the tasks performed with this script, see Role of the agentadmin Program in a J2EE Agent for Policy Agent 2.2.

etc

This directory contains the agentapp file (specifically, the agentapp.war or agentapp.ear file), which has to be deployed after installation is complete. This application helps the agent perform certain housekeeping tasks.

logs

This directory contains various log files, including log files created when you issue the agentadmin command.

This directory also contains the installation log file. For the 2.2 release of Policy Agent, log information is stored in the installation log file after you install a J2EE agent instance. The following is the location of this log file:

PolicyAgent-base/logs/audit/install.log

lib

The lib directory has a list of all the agent libraries that are used by the installer as well as the agent run time.

locale

This directory has all the agent installer information as well as agent run time specific locale information pertaining to the specific agent.

data

This directory has all the installer specific data.

---

Caution –

Do not edit any of the files in the data directory under any circumstance. If this directory or any of its content loses data integrity, the agentadmin program cannot function normally.

---

Agent_001

The full path for this directory is as follows:

PolicyAgent-base/AgentInstance-Dir

where AgentInstance-Dir refers to an agent instance directory, which in this case is Agent_001.

---

Note –

This directory does not exist until you successfully install the first instance of a J2EE agent. Once you have successfully executed one run of the agentadmin --install command, an agent specific directory, Agent_00x is created in the Policy Agent base directory. This directory is uniquely tied to an instance of the deployment container, such as an application server instance. Depending on the number of times the agentadmin --install command is run, the number that replaces the x in the Agent_00x directory name will vary.

---

After you successfully install the first instance of a J2EE agent, an agent instance directory named Agent_001 appears in the Policy Agent base directory. The path to this directory is as follows:

PolicyAgent-base/Agent_001

The next installation of the agent creates an agent instance directory named Agent_002. The directories for uninstalled agents are not automatically removed. Therefore, if Agent_001 and Agent_002 are uninstalled, the next agent instance directory is Agent_003.

Agent instance directories contain directories named config and logs.

---

Note –

When a J2EE agent is uninstalled, the config directory is removed from the agent instance directory but the logs directory still exists.

---

The following table is an example of the contents of an agent instance, such as Agent_001, directory.

Example of an Agent Instance (Agent_001) Directory
logs config

logs

Two subdirectories exist within this directory as follows:

audit

This directory contains the local audit trail for the agent instance.

debug

This directory has all the agent-specific debug information. When the agent runs in full debug mode, this directory stores all the debug files that are generated by the agent code.

---

Note –

Agent-specific debug information is not stored in this directory when the J2EE agent and Access Manager are installed on the same deployment container. However, the J2EE agent and Access Manager must both support the same deployment container for this coexistence scenario to apply. When this coexistence applies, the debug information is stored in the following Access Manager directory:

/var/opt/SUNWam/debug

---

config

This directory contains the J2EE agent AMAgent.properties configuration file that is specific to the agent instance. Each J2EE agent can be configured by a unique instance of the J2EE agent AMAgent.properties configuration file. This file holds the key to the agent behavior at runtime.

Configuring a J2EE Agent With Access Manager 6 2005Q1 (6.3)

Policy Agent 2.2 was released with Access Manager 7 and is designed to take advantage of functionality present in this release. However, J2EE agents in the Policy Agent 2.2 release can be configured to run with Access Manager 6.3 Patch 1 or greater.

Certain features that Policy Agent 2.2 takes advantage of in Access Manager 7.1 are not available in Access Manager 6.3, such as “composite advices”and “policy-based response attributes.”

You can configure a J2EE agent in the Policy Agent 2.2 release to communicate with Access Manager 6.3 Patch 1 or greater as described in the following tasks, which are divided into pre-installation, installation, and post-installation steps.

To Prepare to Install a J2EE Agent With Access Manager 6 2005Q1 (6.3)

Policy Agent 2.2 is only compatible with Access Manager 6.3 when Patch 1 or greater has been applied. Without the patch, the deployment will fail.

1. Ensure that the instance of Access Manager 6.3 you are using has been updated with a patch of level 1, at a minimum.

2. Create an agent profile in Access Manager 6.3 Console that matches the agent profile information provided during J2EE agent installation.

   For information about creating the agent profile in Access Manager 6.3, see information referring to the “agent object” in Sun Java System Access Manager 6 2005Q1 Administration Guide.

To Install a J2EE Agent With Access Manager 6 2005Q1 (6.3)

1. Install the J2EE agent, providing details for the Access Manager 6.3 Patch 1 or greater instance.

   For instructions on how to install the agent, see Chapter 3, Installing the IBM WebSphere Portal Server 6.0 Policy Agent.

To Configure a J2EE Agent With Access Manager 6.3

1. Change to the following directory:

   PolicyAgent-base/lib

2. Create a backup copy of the amclientsdk.jar file, giving the copy a name such as amclientsdk70.jar.

3. Copy the amclientsdk63.jar file to the lib directory and change the name from amclientsdk63.jar to something such as amclientsdk.jar.

   Full path to amclientsdk63.jar file:

   PolicyAgent-base/etc/amclientsdk63.jar

   Full path to lib directory:

   PolicyAgent-base/lib

Creating a J2EE Agent Profile

Creating a J2EE agent profile in Access Manager Console is a required task that you should perform prior to installing the J2EE agent. Though the installation of the J2EE agent actually succeeds without performing this task, the lack of a valid agent profile in Access Manager prevents the J2EE agent from authenticating or having any further communication with Access Manager.

J2EE agents work with Access Manager to protect resources. However, for security purposes these two software pieces can only interact with each other to maintain a session after the J2EE agent authenticates with Access Manager by supplying an agent profile name and password. During the installation of the J2EE agent, you must provide a valid agent profile name and the respective password to enable authentication attempts to succeed.

You create agent profiles in Access Manager Console, not by configuring J2EE agent software. Creating the agent profile is a required security-related task.

The agent profile is created and modified in Access Manager Console. Therefore, tasks related to the agent profile are discussed in Access Manager documentation. Nonetheless, tasks related to the agent profile are also described in this Policy Agent guide, specifically in this section. For related information about defining the Policy Agent profile in Access Manager Console, see the following section of the respective document: Agents Profile in Sun Java System Access Manager 7.1 Administration Guide.

To Create an Agent Profile

Perform the following tasks in Access Manager Console. The key steps of this task involve creating an agent ID and an agent password.

1. With the Access Control tab selected click the name of the realm for which you would like to create an agent profile.

2. Select the Subjects tab.

3. Select the Agent tab.

4. Click New.

5. Enter values for the following fields:

   ID. Enter the name or identity of the agent. This is the agent profile name, which is the name the agent uses to log into Access Manager. Multi-byte names are not accepted.

   Password. Enter the agent password. This password must be different than the password used by the agent during LDAP authentication.

   Password (confirm). Confirm the password.

   Device Status. Select the device status of the agent. The default status is Active. If set to Active, the agent will be able to authenticate to and communicate with Access Manager. If set to Inactive, the agent will not be able to authenticate to Access Manager.

6. Click Create.

   The list of agents appears.

7. (Optional) If you desire, add a description to the newly created agent profile:

   1. Click the name of the newly created agent profile from the agent list.

   2. In the Description field, enter a brief description of the agent.

      For example, you can enter the agent instance name or the name of the application it is protecting.

   3. Click Save.