Chapter 4 The Relationship Between the Agent Profile and Web Agents in Policy Agent 2.2

This section describes how to create or update an agent profile in Access Manager Console and then how to make the corresponding changes in the web agent.

If you are only interested in resetting the shared secret in the web agent, 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.

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.

Creating an agent profile is not a requirement for web agents. You can use the default values and never change the agent user name or shared secret. However, in certain situations you might want to change these default values. Changing the default values of the agent user name and shared secret involves creating an agent profile using Access Manager Console.

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 in Sun Java System Access Manager 7 2005Q4 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 on Solaris Systems

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 Access Manager Console.

Go to the following directory:

PolicyAgent-base/SUNWam/agents/bin

Execute the following script in the command line:

# ./crypt_util agent-profile-password

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

Copy the output obtained after issuing the # ./crypt_util agent-profile-password command and paste it as the value for the following property:
```
com.sun.am.policy.am.password
```

Restart the deployment container and try accessing any resource protected by the agent.

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

To Update the Agent Profile Name and Agent Profile Password on Windows Systems

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 Access Manager Console.

Go to the following directory:
PolicyAgent-base\\bin

Execute the following script in the command line

cryptit agent-profile-password

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

Copy the output obtained after issuing the cryptit agent-profile-password command and paste it as the value for the following property:
```
com.sun.am.policy.am.password
```

Restart the deployment container and try accessing any resource protected by the agent.

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

To Update the Agent Profile Name and Agent Profile Password on Linux Systems

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 Access Manager Console.

Go to the following directory:
PolicyAgent-base/bin

Execute the following script in the command line:

crypt_util agent-profile-password

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

Copy the output obtained after issuing the crypt_util agent-profile-password command and paste it as the value for the following property:
```
com.sun.am.policy.am.password
```

Restart the deployment container and try accessing any resource protected by the agent.

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