Chapter 5 Relationship Between the Agent Profile and Web Agents

This section describes how to create or update an agent profile in the Access Manager Console, including:

Note –

If you are interested only in resetting the shared secret in the web agent and not the agent profile name, see Resetting the Shared Secret Password. However, first read the introductory paragraphs that follow in this section to become acquainted with the process and terminology related to the credentials used by web agents to authenticate with Access Manager. A common reason to reset only the shared secret is that it was entered incorrectly when prompted for during the installation of the web agent.

Overview of a Web Agent Profile

A web agent uses a user name and password as credentials to authenticate with Access Manager. You can use the default values for these credentials or you can create an agent profile in Access Manager Console and use those credentials. In web agents, the term for the default user name is agent user name. The default value of the agent user name is UrlAccessAgent. The term for the default password is shared secret. The default value of the shared secret is the password of the Access Manager internal LDAP authentication user. This user is commonly referred to as amldapuser.

Web agents can function using the default agent profile (UrlAccessAgent), but creating a different agent profile in the Access Manager Console provides greater security. You must also create a different agent profile if Access manager is configured for cross domain single sign-on (CDSSO).

The terms used for the credentials are different once you create them in the agent profile. Agent user name is then called agent profile name. Shared secret is then called agent profile password. After you create the agent profile, you must assign the values of the agent profile name and the agent profile password to the correct properties in the web agent AMAgent.properties configuration file.

Creating or Updating a Web Agent Profile

The instructions that follow in this section explain how to change both the agent profile name and the agent profile password on the Access Manager side.

Since the agent profile is created and updated in Access Manager Console, 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 chapter. 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 or Update an Agent Profile in Access Manager

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

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

Select the Subjects tab.

Select the Agent tab.

Click New.

Enter values for the following fields:

ID. Enter the agent profile 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. Do not use the web agent default value of UrlAccessAgent.

Password. Enter the agent profile password.

Do not use the web agent default value of this password. The web agent default value of this password is the password of the internal LDAP authentication user, commonly referred to as amldapuser.

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.

Click Create.

The list of agents appears.

(Optional) If you desire, add a description to your newly created agent profile:
1. Click the name of your newly created agent profile in 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.

Updating the Agent Profile Name and the Agent Profile Password in Web Agents

After you have changed the agent profile in Access Manager Console, assign the values for the agent profile name and the agent profile password to the corresponding properties in the web agent AMAgent.properties configuration file. This process involves the following:

Adding the agent profile name to the following property in the web agent AMAgent.properties configuration file: com.sun.am.policy.am.username
Encrypting the agent profile password (shared secret) using the encryption utility
Adding the encrypted agent profile password (shared secret) to the following property in the web agent AMAgent.properties configuration file: com.sun.am.policy.am.password

The procedures specified in the preceding list are detailed in the platform-specific task descriptions that follow. Implement the steps according to the platform on which the web agent is installed.

To Update the Agent Profile Name and Agent Profile Password

Update the following property in the web agent AMAgent.properties configuration file:
```
com.sun.am.policy.am.username
```
Replace the value of this property with the agent profile name you just updated in the Access Manager Console.

Go to the following directory:

PolicyAgent-base/bin

Encrypt the new password. For example, on Solaris systems:

# ./crypt_util agent-profile-password

where agent-profile-password represents the agent profile password you just updated in the Access Manager Console.

Windows systems: Use the cryptit script to encrypt the password.

Copy the output from the crypt_util command and paste it as the value for the following property:
```
com.sun.am.policy.am.password
```

Restart the Apache HTTP Server 2.2 web container and try to access a resource protected by the agent.

If the agent is redirected to Access Manager, this indicates the above steps were executed properly.