test

Sun OpenSSO Enterprise Policy Agent 3.0 User's Guide for Web Agents

Chapter 3 Vital Installation Information for a Web Agent in Policy Agent 3.0

To facilitate the installation and configuration of a web agent in Policy Agent 3.0, essential information is provided in this chapter.

The information for this chapter is presented in the following sections:

Unpacking the Distribution Files of an Agent in Policy Agent 3.0

The distribution files for an agent in Policy Agent 3.0 are provided to you in a .zip file, regardless of the platform on which it is to be deployed. For more information, see the individual agent guide for the specific agent you are installing.

ProcedureTo Unpack the .zip File of an Agent in Policy Agent 3.0

You must download the respective agent binaries from the appropriate location. See the following download site http://wwws.sun.com/software/download.

Follow the steps described in this task to unpack an agent .zip file.

  1. Log in to the server where you want to install the agent.

  2. Create a directory in which to unzip the agent distribution file.

  3. Download and unzip the agent distribution file.

    In terms of unzipping the file, the following command is one possible method:

    unzip agent_download.zip

    where agent_download represents specific information about that specific agent.

Purpose of This Task

The preceding steps unpack the archive and provide you with the agent deliverables for Policy Agent 3.0.

Web Agent Directory Structure in Policy Agent 3.0

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 Web Agent Base Directory in Policy Agent 3.0

Unpacking the web agent binaries creates a directory named web_agents, within which an agent-specific directory is created. Therefore, this directory name is different for each agent. For example, sjsws_agent is the directory name applicable to Agent for Sun Java System Web Server.

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 3–1, which follows.

Example 3–1 Policy Agent Base Directory

The directory you choose in which to unpack the web agent binaries is referred to here as Agent-HomeDirectory. For illustration purposes, the following example uses Policy Agent 3.0 for Sun Java System Web Server 7.0 to demonstrate the path to the PolicyAgent-base. Be aware, that the directory sjsws_agent is only an example. This directory will vary from agent to agent:


Agent-HomeDirectory/web_agents/sjsws_agent

References in this book to the PolicyAgent-base directory are references to the preceding path.

Inside the Web Agent Base Directory in Policy Agent 3.0

After you finish installing an agent by issuing the agentadmin ---install command and interacting with the installer, you will need to access web 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 web agent is illustrated in Table 3–1.

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 this guide 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
Table 3–1 Example of Policy Agent Base Directory for a Web Agent

Directory Contents: Files and Subdirectories 

license.txt

etc

README

lib

bin

locale

config

installer-logs

data

Agent_001

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 Policy Agent 3.0.

installer-logs

This directory contains installation-related log files, for example log files created after you issue the agentadmin command.

Log information is stored in the installation log file after you install a web agent instance. The following is the location of this log file:

PolicyAgent-base/installer-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 – 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 web 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 a web 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.

Furthermore, the string “Agent” in Agent_00x is configurable. You can change this string by editing the following file: PolicyAgent-base/config/OpenSSOInstallerConfig.properties. Search for the following setting:

com.sun.identity.install.tools.product.shortname=Agent

After you successfully install the first instance of a web 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 web 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.

config

This directory contains the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file, which are specific to the agent instance. The OpenSSOAgentBootstrap.properties file applies regardless of the agent configuration: centralized in the OpenSSO Enterprise server or local to the agent. However, the OpenSSOAgentConfiguration.properties file is only meaningful when an agent instance is configured locally. In that scenario, the OpenSSOAgentConfiguration.properties file holds the key to the agent behavior at runtime.

Role of the agentadmin Program in Policy Agent 3.0

The agentadmin utility is the predominant install and configuration tool forPolicy Agent 3.0. The most basic of tasks, such as installation and uninstallation can be performed with this tool.

Note –

Installation and configuration tasks that can be performed with the agentadmin utility can also be performed with the OpenSSO Enterprise ssoadm utility. For more information, see Appendix D, Using the ssoadm Command-Line Utility With Agents.

The location of the agentadmin program is as follows:

PolicyAgent-base/bin

For information about the PolicyAgent-base directory, see Default Path and Directory Names.

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

Table 3–2 The agentadmin Program: Supported Options

Option 

Task Performed 

--install

Installs a new agent instance 

--custom-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 IDs 

--version

Displays the version information 

--encrypt

Encrypts a given string 

--getEncryptKey

Generates an Agent Encryption key 

--uninstallAll

Uninstalls all agent instances 

--migrate

Migrates agent to a newer version 

--usage

Displays the usage message 

--help

Displays a brief help message 

agentadmin --install

This section demonstrates the format and use of the agentadmin command with the --install option. The --install option is very similar to the --custom-install option. However, when you install an agent using the agentadmin --install command, the installer provides you with a minimal number of prompts and uses default values for the other options. For example, with the --custom-install option, you can create the agent profile during agent installation. You do not have this option with the --install option.

Example 3–2 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 an 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 3–3 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 --custom-install

This section demonstrates the format and use of the agentadmin command with the --custom-install option. The --custom-install option is very similar to the --install option. However, when you install an agent using the agentadmin --custom-install command, the installer provides you with a greater number of prompts, and therefore allows you to select a greater number of settings. The --install option, on the other hand, selects default values for many options. For example, with the --custom-install option, you can create the agent profile during agent installation. You do not have this option with the --install option.

Note –

The arguments available with the --custom-install option, as listed in the next section, are the same as for the --install option.

Example 3–4 Command Format: agentadmin --custom-install

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


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

The following arguments are supported with the agentadmin command when using the --custom-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 an 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 3–5 Command Usage: agentadmin --custom-install

When you issue the agentadmin command, you can choose the --custom-install option. With the --custom-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 --custom-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 --custom-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 --custom-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 3–6 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 an 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 3–7 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 3–8 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 3–9 Command Usage: agentadmin --listAgents

Issuing the agentadmin command with the --listAgents option provides you with information about all the configured agents on that deployment container.

agentadmin --agentInfo

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

Example 3–10 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 3–11 Command Usage: agentadmin --agentInfo

Issuing the agentadmin command with the --agentInfo option provides you with information on the specific agent instance that you name in the command. For example, if you want information about an agent instance named Agent_002, you can issue the command illustrated in the following example:


./agentadmin --agentInfo Agent_002

agentadmin --version

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

Example 3–12 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 3–13 Command Usage: agentadmin --version

Issuing the agentadmin command with the --version option provides you with version information for the configured agents on that deployment container. For example, the agentadmin --version command provides the version of the agent, such as 3.0 and the build date of the agent.

agentadmin --encrypt

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

Example 3–14 Command Format: agentadmin --encrypt

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


./agentadmin --encrypt AgentInstance-Dir agentpasswordfile

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 be available for an agent instance. Therefore, a default encryption key can be assigned by the agent during agent installation. You can also assign an encryption key yourself. The encryption key is stored in the OpenSSOAgentBootstrap.properties file. For example:

am.encryption.pwd = EphgFHmF6X3XmMjYGCUtYHSYA9C7qQlk
agentpasswordfile

Use this option to specify the full path to the password file that contains a clear text agent password to be encrypted.

The password file should be created as an agent pre-installation task.

Example 3–15 Command Usage: agentadmin --encrypt

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

For example, issuing the following command encrypts the password file, pwfile1 for the 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 OpenSSO Enterprise. Once the agent profile for a specific agent has been created in OpenSSO Enterprise, the installer assigns the Policy Agent profile name and encrypted password in the respective agent instance. If you choose a new password for the Policy Agent profile, encrypt it and enter that encrypted password in the OpenSSOAgentBootstrap.properties as the value for 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 3–16 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 3–17 Command Usage: agentadmin --getEncryptKey

This option may be used in conjunction with the --encrypt option to encrypt and decrypt sensitive information in the OpenSSOAgentBootstrap.properties file. Issuing the agentadmin command with the --getEncryptKey option generates a new encryption key for the 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 OpenSSOAgentBootstrap.properties 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 OpenSSOAgentBootstrap.properties file stores the encryption key:

com.sun.identity.agents.config.key

For example, using the encryption key example provided previously, updating the encryption key value for the applicable agent property could appear as follows:

com.sun.identity.agents.config.key = k1441g4EejuOgsPlFOSg+m6P5x7/G9rb

Once you have updated the OpenSSOAgentBootstrap.properties 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 3–18 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 3–19 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 agent instances or all agent instances on that deployment container. 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 an agent on a deployment container. You can then decide, case by case, to remove an agent instance or not.

agentadmin --migrate

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

Example 3–20 Command Format: agentadmin --migrate

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


./agentadmin --migrate

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

Example 3–21 Command Usage: agentadmin --migrate

Issuing the agentadmin command with the --migrate option allows you to update an agent in the Policy Agent software set to a newer version of that same agent.

For example, you can migrate Policy Agent 2.2 to Policy Agent 3.0. The agentadmin --migrate command allows you to migrate the agent's binary files, update the agent's deployment container configuration, and convert the agent's AMAgent.properties file to the property files used for the 3.0 version: the OpenSSOAgentBootstrap.properties file and the OpenSSOAgentConfiguration.properties file.

agentadmin --usage

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

Example 3–22 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 3–23 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.
--custom-install: Installs a new Agent instance
--uninstall: Uninstalls an existing Agent instance.
--version: Displays the version information.
--uninstallAll: Uninstalls all the agent instances.
--migrate: migrate agent to newer one
--listAgents: Displays details of all the configured agents.
--agentInfo: Displays details of the agent corresponding to the specified
agent ID.
--encrypt: Encrypts a given string.
--getEncryptKey: Generates an Agent Encryption key.
--usage: Display the usage message.
--help: Displays a brief help message.

agentadmin --help

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

Example 3–24 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 3–25 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.

Policy Agent 3.0: Web Agent Properties

The web agent properties changed names from the 2.2 release to the 3.0 release. This section lists those name changes. Furthermore, when applicable, this section provides the property label used with the property names. In prior releases, only property names were used for the properties. However, in Policy Agent 3.0 you can centralize the properties on the OpenSSO Enterprise Console, where labels are more useful.

Web Agent Properties in the OpenSSOAgentBootstrap.properties File

The properties listed in the table that follows can be configured by accessing the OpenSSOAgentBootstrap.properties file. This properties file, which is new for the 3.0 release, resides locally on the system where the agent is installed and stores the properties required for the agent to start up and initialize itself.

The properties listed in the web agent OpenSSOAgentBootstrap.properties file are either new for 3.0 or their property names have changed as indicated in the table. Labels are not assigned for the properties in this file.

Former Web Agent Property Name 

Web Agent 3.0 Property Name 

com.sun.am.naming.url

com.sun.identity.agents.config.naming.url

com.sun.am.log.level

com.sun.identity.agents.config.debug.level

com.sun.am.policy.agents.config.local.log.file

com.sun.identity.agents.config.local.logfile

com.sun.am.policy.am.username

com.sun.identity.agents.config.username

com.sun.am.policy.am.password

com.sun.identity.agents.config.password

com.sun.am.sslcert.dir

com.sun.identity.agents.config.sslcert.dir

com.sun.am.certdb.prefix

com.sun.identity.agents.config.certdb.prefix

com.sun.am.certdb.password

com.sun.identity.agents.config.certdb.password

com.sun.am.auth.certificate.alias

com.sun.identity.agents.config.certificate.alias

com.sun.am.trust_server_certs

com.sun.identity.agents.config.trust.server.certs

com.sun.am.receive_timeout

com.sun.identity.agents.config.receive.timeout

com.sun.am.connect_timeout

com.sun.identity.agents.config.connect.timeout

com.sun.am.tcp_nodelay.enable

com.sun.identity.agents.config.tcp.nodelay.enable

New 

com.sun.identity.agents.config.organization.name

New 

com.sun.identity.agents.config.key

New 

com.sun.identity.agents.config.debug.file

New 

com.sun.identity.agents.config.forward.proxy.host

New 

com.sun.identity.agents.config.forward.proxy.port

New 

com.sun.identity.agents.config.forward.proxy.user

New 

com.sun.identity.agents.config.forward.proxy.password

New 

com.sun.identity.agents.config.profilename

Web Agent Properties Available Using the OpenSSO Enterprise Console or Other Methods

This section does not describe the agent properties. For a description of the agent properties, see the following link: http://wikis.sun.com/display/OpenSSO/agent3properties

The properties listed in the various tables that follow can be configured using any of the three following methods, depending on how agent is deployed:

The property names have changed for the 3.0 release as indicated in the various tables that follow in this section. Labels are associated with most of these properties, as indicated. The labels are most useful when using the Console.

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.am.login.url

com.sun.identity.agents.config.login.url

Label: OpenSSO Login URL

com.sun.am.cookie.name

com.sun.identity.agents.config.cookie.name

Label: Cookie Name

com.sun.am.cookie.secure

com.sun.identity.agents.config.cookie.secure

Label: Cookie Security

com.sun.am.policy.agents.config.local.log.rotate

com.sun.identity.agents.config.local.log.rotate

Label: Rotate Local Audit Log

com.sun.am.policy.agents.config.local.log.size

com.sun.identity.agents.config.local.log.size

Label: Local Audit Log Rotation Size

com.sun.am.policy.agents.config.audit.accesstype

com.sun.identity.agents.config.audit.accesstype

Label: Audit Access Types

com.sun.am.policy.agents.config.remote.log

com.sun.identity.agents.config.remote.logfile

Label: Remote Log Filename

com.sun.am.notification.enable

com.sun.identity.agents.config.notification.enable

Label: Enable Notifications

com.sun.am.policy.am.url_comparison.case_ignore

com.sun.identity.agents.config.url.comparison.case.ignore

Label: URL Comparison Case Sensitivity Check

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.am.polling.interval

com.sun.identity.agents.config.policy.cache.polling.interval

Label: Policy Cache Polling Period

com.sun.am.sso.polling.period

com.sun.identity.agents.config.sso.cache.polling.interval

Label: SSO Cache Polling Period

com.sun.am.policy.am.userid.param

com.sun.identity.agents.config.userid.param

Label: User ID Parameter

com.sun.am.policy.am.userid.param.type

com.sun.identity.agents.config.userid.param.type

Label: User ID Parameter Type

com.sun.am.policy.agents.config.profile.attribute.fetch.mode

com.sun.identity.agents.config.profile.attribute.fetch.mode

Label: Profile Attribute Fetch Mode

com.sun.am.policy.agents.config.profile.attribute.map

com.sun.identity.agents.config.profile.attribute.mapping

Label: Profile Attribute Mapping

com.sun.am.policy.agents.config.session.attribute.fetch.mode

com.sun.identity.agents.config.session.attribute.fetch.mode

Label: Session Attribute Fetch Mode

com.sun.am.policy.agents.config.session.attribute.map

com.sun.identity.agents.config.session.attribute.mapping

Label: Session Attribute Mapping

com.sun.am.policy.agents.config.response.attribute.fetch.mode

com.sun.identity.agents.config.response.attribute.fetch.mode

Label: Response Attribute Fetch Mode

com.sun.am.policy.agents.config.response.attribute.map

com.sun.identity.agents.config.response.attribute.mapping

Label: Response Attribute Mapping

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.load_balancer.enable

com.sun.identity.agents.config.load.balancer.enable

Label: Load Balancer Setup

com.sun.am.policy.agents.config.agenturi.prefix

com.sun.identity.agents.config.agenturi.prefix

Label: Agent Deployment URI Prefix

com.sun.am.policy.agents.config.locale

com.sun.identity.agents.config.locale

Label: Agent Locale

com.sun.am.policy.agents.config.do_sso_only

com.sun.identity.agents.config.sso.only

Label: SSO Only

com.sun.am.policy.agents.config.accessdenied.url

com.sun.identity.agents.config.access.denied.url

Label: Resources Access Denied URL

com.sun.am.policy.agents.config.fqdn.check.enable

com.sun.identity.agents.config.fqdn.check.enable

Label: FQDN Check

com.sun.am.policy.agents.config.fqdn.default

com.sun.identity.agents.config.fqdn.default

Label: FQDN Default

com.sun.am.policy.agents.config.fqdn.map

com.sun.identity.agents.config.fqdn.mapping

Label: FQDN Virtual Host Map

com.sun.am.policy.agents.config.cookie.reset.enable

com.sun.identity.agents.config.cookie.reset.enable

Label: Cookie Reset

com.sun.am.policy.agents.config.cookie.reset.list

com.sun.identity.agents.config.cookie.reset

Label: Cookies Reset Name List

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.agents.config.cookie.domain.list

com.sun.identity.agents.config.cookie.domain

Label: Cookies Domain List

com.sun.am.policy.agents.config.anonymous_user

com.sun.identity.agents.config.anonymous.user.id

Label: Anonymous User Default Value

com.sun.am.policy.agents.config.anonymous_user.enable

com.sun.identity.agents.config.anonymous.user.enable

Label: Anonymous User

com.sun.am.policy.agents.config.notenforced_list

com.sun.identity.agents.config.notenforced.url

Label: Not Enforced URLs

com.sun.am.policy.agents.config.notenforced_list.invert

com.sun.identity.agents.config.notenforced.url.invert

Label: Invert Check for Not Enforced URLs

com.sun.am.policy.agents.config.notenforced_client_ip_list

com.sun.identity.agents.config.notenforced.ip

Label: Not Enforced Client IP List

com.sun.am.policy.agents.config.ignore_policy_evaluation_if_notenforced

com.sun.identity.agents.config.notenforced.url.attributes.enable

Label: Fetch Attributes for Notenforced URLs

com.sun.am.policy.agents.config.postdata.preserve.enable

com.sun.identity.agents.config.postdata.preserve.enable

Label: POST Data Preservation

com.sun.am.policy.agents.config.postcache.entry.lifetime

com.sun.identity.agents.config.postcache.entry.lifetime

Label: POST Data Entries Cache Period

com.sun.am.policy.agents.config.client_ip_validation.enable

com.sun.identity.agents.config.client.ip.validation.enable

Label: Client IP Validation

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.agents.config.profile.attribute.cookie.prefix

com.sun.identity.agents.config.profile.attribute.cookie.prefix

Label: Profile Attributes Cookie Prefix

com.sun.am.policy.agents.config.profile.attribute.cookie.maxage

com.sun.identity.agents.config.profile.attribute.cookie.maxage

Label: Profile Attributes Cookie Maxage

com.sun.am.policy.agents.config.cdsso.enable

com.sun.identity.agents.config.cdsso.enable

Label: Cross Domain SSO

com.sun.am.policy.agents.config.cdcservlet.url

com.sun.identity.agents.config.cdsso.cdcservlet.url

Label: CDSSO Servlet URL

com.sun.am.policy.agents.config.logout.url

com.sun.identity.agents.config.logout.url

Label: OpenSSO Logout URL

com.sun.am.policy.agents.config.logout.cookie.reset.list

com.sun.identity.agents.config.logout.cookie.reset

Label: Logout Cookies List for Reset

com.sun.am.policy.am.fetch_from_root_resource

com.sun.identity.agents.config.fetch.from.root.resource

Label: Fetch Policies from Root Resource

com.sun.am.policy.agents.config.get_client_host_name

com.sun.identity.agents.config.get.client.host.name

Label: Retrieve Client Hostname

com.sun.am.policy.agents.config.convert_mbyte.enable

com.sun.identity.agents.config.convert.mbyte.enable

Label: Native Encoding of Profile Attributes

com.sun.am.policy.agents.config.encode_url_special_chars.enable

com.sun.identity.agents.config.encode.url.special.chars.enable

Label: Encode URL's Special Characters

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.agents.config.ignore_path_info

com.sun.identity.agents.config.ignore.path.info

Label: Ignore Path Info in Request URL

com.sun.am.policy.agents.config.override_protocol

com.sun.identity.agents.config.override.protocol

Label: Override Request URL Protocol

com.sun.am.policy.agents.config.override_host

com.sun.identity.agents.config.override.host

Label: Override Request URL Host

com.sun.am.policy.agents.config.override_port

com.sun.identity.agents.config.override.port

Label: Override Request URL Port

com.sun.am.policy.agents.config.override_notification.url

com.sun.identity.agents.config.override.notification.url

Label: Override Notification URL

com.sun.am.policy.agents.config.connection_timeout

com.sun.identity.agents.config.auth.connection.timeout

Label: Agent Connection Timeout

com.sun.am.ignore_server_check

com.sun.identity.agents.config.ignore.server.check

Label: Ignore Server Check

com.sun.am.poll_primary_server

com.sun.identity.agents.config.poll.primary.server

Label: Polling Period for Primary Server

com.sun.am.ignore.preferred_naming_url

com.sun.identity.agents.config.ignore.preferred.naming.url

Label: Ignore Preferred Naming URL in Naming Request

com.sun.am.policy.agents.config.proxy.override_host_port

com.sun.identity.agents.config.proxy.override.host.port

Label: Override Proxy Server's Host and Port

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.agents.config.domino.check_name_database

com.sun.identity.agents.config.domino.check.name.database

Label: Check User in Domino Database

com.sun.am.policy.agents.config.domino.ltpa.enable

com.sun.identity.agents.config.domino.ltpa.enable

Label: Use LTPA token

com.sun.am.policy.agents.config.domino.ltpa.cookie_name

com.sun.identity.agents.config.domino.ltpa.cookie.name

Label: LTPA Token Cookie Name

com.sun.am.policy.agents.config.domino.ltpa.config_name

com.sun.identity.agents.config.domino.ltpa.config.name

Label: LTPA Token Configuration Name

com.sun.am.policy.agents.config.domino.ltpa.org_name

com.sun.identity.agents.config.domino.ltpa.org.name

Label: LTPA Token Organization Name

com.sun.am.policy.agents.config.iis.auth_type

com.sun.identity.agents.config.iis.auth.type

Label: Authentication Type

com.sun.am.replaypasswd.key

com.sun.identity.agents.config.replaypasswd.key

Label: Replay Password Key

com.sun.am.policy.agents.config.iis.filter_priority

com.sun.identity.agents.config.iis.filter.priority

Label: Filter Priority

com.sun.am.policy.agents.config.iis.owa_enabled

com.sun.identity.agents.config.iis.owa.enable

Label: Filter configured with OWA

com.sun.am.policy.agents.config.iis.owa_enabled_change_protocol

com.sun.identity.agents.config.iis.owa.enable.change.protocol

Label: Change URL Protocol to https

Former Web Agent Property Name 

Web Agent 3.0 Property Name and Label 

com.sun.am.policy.agents.config.iis.owa_enabled_session_timeout_url

com.sun.identity.agents.config.iis.owa.enable.session.timeout.url

Label: Idle Session Timeout Page URL

NEW 

com.sun.identity.agents.config.repository.location

This product is available in OpenSSO Enterprise Console. However, only the label is provided, not the property name. 

Label: Location of Agent Configuration Repository

NEW 

com.sun.identity.agents.config.freeformproperties

Label: Custom Properties

NEW 

com.sun.identity.agents.config.polling.interval

Label: Configuration Reload Interval

NEW 

com.sun.identity.agents.config.cleanup.interval

Label: Configuration Cleanup Interval

Creating a Web Agent Profile in Policy Agent 3.0

Caution – Caution –

Creating a web agent profile in OpenSSO Enterprise Console is a required task that you can perform prior to installing the web agent or during installation. Though the installation of the web agent actually succeeds without performing this task, the lack of a valid agent profile in OpenSSO Enterprise prevents the web agent from authenticating or having any further communication with OpenSSO Enterprise server.

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

Creating a Web Agent Profile in Policy Agent 3.0

You can create agent profiles using any of the following methods:

ProcedureTo Create a Web Agent Profile in Policy Agent 3.0 Using OpenSSO Enterprise Console

This task applies when you want to create the web agent profile as a pre-installation task. Perform this task using OpenSSO Enterprise Console. The key steps of this task involve creating an agent name (ID) and an agent password.

  1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

    The OpenSSO Enterprise login page is available at a URL similar in format to the following:

    http://OpenssoHost.example.com:58080/opensso

  2. Click the Access Control tab.

  3. Click the name of the realm to which the agent will belong, such as the following: /(Top Level Realm).

  4. Click the Agents tab.

    The Web tab is selected by default.

  5. Click New in the agent section.

  6. Enter values for the following fields:

    Name: Enter the name or identity of the agent. This is the agent profile name, which is the name the agent uses to log into OpenSSO Enterprise. Multi-byte names are not accepted.

    Password: Enter the agent password. However, it must be the same password entered in the agent profile password file that is used by the agentadmin utility to install the agent.

    Re-Enter Password: Confirm the password.

    Configuration: For configuration, check the location of the agent configuration properties.

    • Local: Properties stored in the OpenSSOAgentConfiguration.properties file on the server where the agent is deployed.

    • Centralized: Properties stored in the OpenSSO Enterprise centralized data repository.

  7. In the Server URL field, enter the OpenSSO Enterprise server URL.

    For example: http://OpenssoHost.example.com:58080/opensso

  8. In the Agent URL field, enter the URL for the agent application.

    For example: http://agentHost.example.com:8090

  9. Click Create.

    The Console creates the agent profile and displays the Web Agent page again with a link to the new agent profile.

    To perform additional configuration of the agent, click this link to display the Edit agent page.

Creating an Agent Group and Enabling Agents to Inherit Properties From That Group

The Concept of agent groups is new in Policy Agent 3.0. You can create an agent group and then allow an agent to inherit specified properties from the group. The following tasks describe how to enable this type of property inheritance.

ProcedureTo Create a New Group

If desired, perform this task in the OpenSSO Enterprise Administration Console. This task applies to web agent groups.

Create a group if you want agents to inherit specific properties from the group. web agents can inherit properties from a web agent group.

  1. Click the Access Control tab.

  2. Click the name of the realm to which the group will belong.

  3. Click the Agents tab.

  4. If necessary, select the Web Agents tab.

  5. In the Group section, click New.

  6. In the Name field, enter the name for the new group name.

  7. In the Server URL field, enter the OpenSSO Enterprise server URL.

    For example, http://OpenssoHost.example.com:58080/opensso.

  8. Click Create.

    The Console creates the agent group and displays the web agent page again, with a link to the group.

    To do additional configuration of the group, click this link to display the Edit agent group page.

    The properties you can set to configure a group are the same as they are for an individual agent except that the Group, Password, and Password Confirm properties are not available at the group level.

    Note –

    Also, be aware that some group properties already have variable values assigned that in most cases should not be changed. The following is one example of such a value:

    @AGENT_PROTO@://@AGENT_HOST@:@AGENT_PORT@/amagent

ProcedureTo Enable a Web Agent to Inherit Properties From a Group

Before You Begin

The group from which you want an agent to inherit properties must be created first.

  1. Using a browser, navigate through OpenSSO Enterprise Console to the agent properties of the J2EE agent that you want to configure.

    For the steps to navigate to the J2EE agent properties, see To Navigate in the OpenSSO Enterprise 8.0 Console to the Web Agent Properties.

  2. With the Global tab selected, for the attribute labeled Group, select the name of the group from which you want the agent to inherit properties.

  3. Click Save.

    At the top of the page, the Inheritance Settings button becomes active.

  4. Click Inheritance Settings.

    A list of inheritance settings for the Global tab appear in alphabetical order.

  5. Select the properties that you want the agent to inherit from the group.

  6. Click Save.

Next Steps

This task just describes how to change the inheritance settings for properties listed in the Global tab. For the inheritance settings of properties listed in other tabs, such as Application, click the desired tab and edit the inheritance settings in the same manner described in the preceding steps.

About the Agent Authenticator in Policy Agent 3.0

An agent authenticator is a special type of agent that, once authenticated, can have access to agent profiles that have been selected for the agent authenticator to read. Therefore, the agent authenticator has read-only access to these other agents profiles. In this case, agent profiles refer to a broad range of “agent” types (Web, J2EE, WSP, Discovery, and so forth). These agent profiles must exist in the same realm as the agent authenticator.

Users who have the agent authenticator's credentials (user name and password) can read the agent profile data, but do not have the create, update, or delete permissions of the agent administrator.

An advantage of creating an agent authenticator is that you can configure the agent authenticator to have access (read-only access) to a variety of other agents. Therefore, using a single user name and password to access the agent authenticator, you then have access to all the agents to which the agent authenticator has access.

For more information about the agent authenticator see the following guides:

The two tasks that follow describe how to create an agent authenticator, assign one or more agent profiles to the agent authenticator, and then edit the respective bootstrap files to configure the agent instances that correspond to those agent profiles.

ProcedureTo Create an Agent Authenticator To Access Other Agent Profiles

This task details how to use OpenSSO Enterprise Console to create an agent authenticator.

Before You Begin

The instructions that follow start with the assumption that OpenSSO Enterprise server and at least one agent instance have been properly installed and configured.

  1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

  2. Click the Access Control tab.

  3. Click the name of the appropriate realm, such as the following: /(Top Level Realm).

  4. Click the Agents tab.

  5. Click on Agent Authenticator tab.

  6. Click the New button.

  7. Enter an agent authenticator name and password.

  8. Click the Create button.

  9. On the Agent Authenticator page, click the link for the newly created agent authenticator.

    The agent authenticator page is displayed. In the section labeled "Agent Profiles allowed to Read," two lists exist: Available and Selected. The Available list has all the available agents in the system, and the Selected list has all the agents whose configurations can be read by this agent authenticator.

  10. From the available list, select one or more agent profile names.

    The agent authenticator can access any of the various agent types. Select all the agent profiles to which you would like the agent authenticator to have access.

  11. Click Add to move the selected item from the Available list to the Selected list.

  12. Click Save.

ProcedureTo Enable the Agent Authenticator to Access Other Agent Instances

This task describes how to edit the bootstrap file of each agent instance that corresponds to an agent profile you added to the Selected list of the agent authenticator. Therefore, if you added four agents profiles (for example, a combination of J2EE agent and Web agent instances) to the agent authenticator, you must perform this task four times if you want each of those agent instances to be readable by the agent authenticator. In such a scenario, all four agent instances would then use the same user name and password to authenticate to OpenSSO Enterprise server.

Agents in Policy Agent 3.0 have the two following properties in the OpenSSOAgentBootstrap.properties file that enable the agent to communicate with OpenSSO Enterprise server:

The first property, the user name property, enables the agent to authenticate with the OpenSSO Enterprise server. The second property, the profile name property, enables the agent to retrieve its configuration data from the OpenSSO Enterprise server. By default, the value assigned to these two properties is the same. However, for the agent authenticator, these properties should have different values. Therefore, the user name property must be changed as indicated in this task.

  1. Stop the agent container.

  2. Edit the OpenSSOAgentBootstrap.properties file as described in the substeps that follow.

    The bootstrap file is located at the following location:

    PolicyAgent-base/AgentInstance-Dir/config

    For information about this location, see Table P–6

    1. Using your text editor of choice, open the OpenSSOAgentBootstrap.properties file.

    2. Change the value for the property named com.sun.identity.agents.config.username to the agent authenticator name.

      Therefore, the setting would be as such:

      com.sun.identity.agents.config.username = AgentAuthenticatorName

      where AgentAuthenticatorName represents the name provided for the agent authenticator.

    3. Change the value for the property named com.iplanet.am.service.secret to the agent authenticator password.

      Therefore, the setting would be as such:

      com.sun.identity.agents.config.password = EncryptedAgentAuthenticatorPassword

      where EncryptedAgentAuthenticatorPassword represents the encrypted version of the password provided for the agent authenticator as demonstrated previously in this task.

      Note –

      To encrypt the password, use the agentadmin --encrypt command as described in agentadmin --encrypt.

    4. Save and close the bootstrap file.

  3. Restart the agent container.

Web Agent Task Reference for Policy Agent 3.0

This section lists tasks that are often repeated when performing various web agent configurations. A task listed here might be referenced from various other sections of this guide.

ProcedureTo Navigate in the OpenSSO Enterprise 8.0 Console to the Web Agent Properties

  1. Log in to OpenSSO Enterprise Console as a user with AgentAdmin privileges, such as amadmin.

    The OpenSSO Enterprise login page is available at a URL similar in format to the following:

    http://OpenssoHost.example.com:58080/opensso

  2. Click the Access Control tab.

  3. Click the name of the realm to which the agent will belong, such as the following: /(Top Level Realm).

  4. Click the Agents tab.

    By default the Web tab is selected.

  5. Click the name of the agent you are attempting to access.

    After performing this step, by default, the Global tab is selected. You can start editing web agent properties, moving from tab to tab as necessary.