--- title: Prepare for installation description: Consider the following before you install: component: web-agents version: 2025.11 page_id: web-agents:installation-guide:pre-installation canonical_url: https://docs.pingidentity.com/web-agents/2025.11/installation-guide/pre-installation.html section_ids: before-install: Before you install pre-SSL-configuration: OpenSSL libraries downloading-agent: Download and unzip Web Agent preinstall-tasks: Pre-installation tasks create-agent-profiles: Create agent profiles create-agent-profile: Create an agent profile for a single agent instance create-agent-profile-mult-instances: Create an agent profile for multiple agent instances when post data preservation is enabled create-agent-group: Create an agent profile group agent-group-inherit: Inherit properties from an agent profile group authenticate_agents_to_the_identity_provider: Authenticate agents to the identity provider authenticate-agent-idc: Authenticate agents to Advanced Identity Cloud authenticate-agent-am: Authenticate agents to AM create-agent-tree: Create an Agent authentication tree check-agents-can-connect: Check agents can connect to the identity provider --- # Prepare for installation ## Before you install Consider the following before you install: * Install AM and Web Agent in different servers. * Make sure AM is running so that you can contact AM from the agent web server. * Install the web server before you install the agent. * Make sure OpenSSL or the Windows Secure Channel API (Schannel) is available before installing the agent. Unix-based agents support OpenSSL. Windows-based agents support OpenSSL and Schannel. Learn more about SSL requirements in [SSL requirements](https://docs.pingidentity.com/web-agents/release-notes/requirements.html#ssl_requirements) and required OpenSSL libraries in [OpenSSL libraries](#pre-SSL-configuration). * Install only one Web Agent for each web server and configure as many agent instances as necessary. * For environments with load balancers or reverse proxies, consider the communication between the agent and AM servers, and between the agent and the client. Configure both AM and the environment **before** you install the agent. Learn more in [Configure load balancers and reverse proxies](../user-guide/load-balancers-proxies.html). ### OpenSSL libraries Before installing, make sure the OpenSSL libraries are located or referenced as follows: | Operating System | OpenSSL 1.1.1 Library | OpenSSL 3.x Library | Location or Variable | | ----------------- | ------------------------------------------------- | --------------------------------------------- | ---------------------------------------- | | Windows 32-bit | * `libcrypto-1_1.dll` * `libssl-1_1.dll` | - `libcrypto-3.dll` - `libssl-3.dll` | `%SYSTEM32%` | | Windows 64-bit(1) | * `libcrypto-1_1.dll` * `libssl-1_1.dll` | - `libcrypto-3.dll` - `libssl-3.dll` | `\windows\syswow64` | | | * `libcrypto-1_1-x64.dll` * `libssl-1_1-x64.dll` | - `libcrypto-3-x64.dll` - `libssl-3-x64.dll` | `%SYSTEM32%` | | Linux | * `libcrypto.so.1.1`(2) * `libssl.so.1.1`(2) | - `libcrypto.so.3`(2) - `libssl.so.3`(2) | `$LD_LIBRARY_PATH` `$LD_LIBRARY_PATH_64` | | AIX | * `libcrypto.a`(3) * `libssl.a`(4) | - `libcrypto.a`(3) - `libssl.a`(4) | `$LIBPATH` | (1) Windows 64-bit servers require both 32-bit and 64-bit OpenSSL libraries.\ (2) The unversioned file (`libcrypto.so` or `libssl.so`) is used if the versioned file is not found.\ (3) The `libcrypto.so` file is bundled in this library archive.\ (4) The `libssl.so` file is bundled in this library archive. ## Download and unzip Web Agent Go to the [Ping Identity Download Center](https://backstage.pingidentity.com/downloads) and download an agent based on your architecture, and operating system requirements. Verify the checksum of the downloaded file against the checksum posted on the download page. Unzip the file in the directory where you plan to store the agent configuration and log files. The following directories are extracted: **Installation directories** | Directory | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bin/` | The installation and configuration program `agentadmin`. | | `config/` | Configuration templates used by the `agentadmin` command during installation. | | `instances/` | Configuration files, and audit and debug logs for individual instances of the agents. The directory is empty when first extracted. Make sure the directory path, including the parent path, doesn't exceed 260 characters. | | `legal/` | Licensing information including third-party licenses. | | `lib/` | Shared libraries used by the agent. | | `log/` | Log files written during installation. The directory is empty when first extracted.When the agent is running, the directory can contain the following files:- The `system_n.log` file, where the agent logs information related to agent tasks running in the background. Web Agent timestamps events in coordinated universal time (UTC). - (IIS and ISAPI agents only) The backup of the site and application configuration files created after running the `agentadmin -g` command. - (IIS and ISAPI agents only) Files related to the agent caches. | | `pdp-cache/` | POST data preservation cache. The agent stores POST data preservation files temporarily. To change the directory, configure [POST Data Storage Directory](../properties-reference/org.forgerock.agents.config.postdata.preserve.dir.html). | ## Pre-installation tasks 1. In AM, add an agent profile as described in [Create agent profiles](#create-agent-profiles). The example in this guide uses an agent profile in the top-level realm, with the following values: * Agent ID: `web-agent` * Agent URL: `http://www.example.com:80` * Server URL: `https://am.example.com:8443/am` * Password: `password` 2. In AM, add a policy set and policy as described in [Policies](https://docs.pingidentity.com/pingam/8/am-authorization/policies.html) in AM's *Authorization guide*. The example in this guide uses a policy set and policy in the top-level realm, with the following values: * Policy set: * Name: `PEP` * Resource Types: `URL` * Policy: * Name: `PEP-policy` * Resource Type: `URL` * Resource pattern: `*://*:*/*` * Resource value: `*://*:*/*` * Actions tab: Allow HTTP `GET` and `POST` * Subjects tab: All Authenticated Users. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you use your own policy set instead of the default policy set, `iPlanetAMWebAgentService`, update the following properties in the agent profile:* [Policy Set](../properties-reference/org.forgerock.openam.agents.config.policy.evaluation.application.html) * [Policy Evaluation Realm](../properties-reference/org.forgerock.openam.agents.config.policy.evaluation.realm.html) | 3. Configure AM to protect the CDSSO cookie from hijacking. For more information, refer to [Restrict tokens for CDSSO session cookies](https://docs.pingidentity.com/pingam/8/security/enable-cdsso-cookie-hijacking-protection.html) in AM's *Security guide*. 4. Create a text file for the agent password, and protect it. For example, use commands similar to these, but use a strong password and store it in a secure place: * Unix * Windows ``` $ cat > /secure-directory/pwd.txt password CTRL+D $ chmod 400 /secure-directory/pwd.txt ``` ``` C:> type > pwd.txt password CTRL+Z ``` In Windows Explorer, right-click the password file, select Read-Only, and then click OK. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example, by using a password manager. | 5. If either of the following is true, set up the required environment variables: * AM is configured to perform client authentication * The agent web server is configured to validate AM's server certificate Learn more in [Environment variables](../user-guide/configure-envvars.html). ## Create agent profiles Use Web Agent profiles to connect to and communicate with Advanced Identity Cloud or AM. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can find additional details about creating an agent profile in Advanced Identity Cloud in [Create an agent profile in Advanced Identity Cloud](../identity-cloud-guide/installation.html#create-agent-profile). | ### Create an agent profile for a single agent instance This section describes how to create an agent profile in the AM admin UI. Alternatively, create agent profiles by using the `/realm-config/agents/WebAgent/{id}` endpoint in the REST API. Learn more in [REST API explorer](https://docs.pingidentity.com/pingam/8/am-rest/about-api-explorer.html) in AM's *REST guide*. 1. In the AM admin UI, select Realms > *Realm Name* > Applications > Agents > Web, and add an agent using the following hints: * Agent ID The ID of the agent profile. This ID resembles a username and is used during the agent installation. For example, `MyAgent`. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------- | | | When AM is not available, the related error message contains the agent profile name. Consider this in your choice of agent profile name. | * Agent URL The URL where the agent resides. Learn more in [Example installation for this guide](preface.html#preface-examples). In [centralized configuration mode](../user-guide/glossary.html#def-central-configuration-mode), the Agent URL populates the agent profile for services, such as notifications. * Server URL The full URL to an authorization server, such as AM. Learn more in [Example installation for this guide](preface.html#preface-examples). If the authorization server is deployed in a site configuration (behind a load balancer), enter the site URL. In [centralized configuration mode](../user-guide/glossary.html#def-central-configuration-mode), the Server URL populates the agent profile for use with login, logout, naming, and cross-domain SSO. * Password The password the agent uses to authenticate to an authorization server, such as AM. Use this password when installing an agent. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Although the agent accepts any password length and content, you are strongly encouraged to generate secure passwords. This can be achieved in various ways, for example, by using a password manager. | 2. (Optional - From AM 7.5) Use AM's secret service to manage the agent profile password. If AM finds a matching secret in a secret store, it uses that secret instead of the agent password configured in Step 1. 1. In the agent profile page, set a label for the agent password in Secret Label Identifier. AM uses the identifier to generate a secret label for the agent. The secret label has the format `am.application.agents.identifier.secret`, where *identifier* is the Secret Label Identifier. The Secret Label Identifier can contain only characters `a-z`, `A-Z`, `0-9`, and periods (`.`). It can't start or end with a period. 2. Select Secret Stores and configure a secret store. 3. Map the label to the secret. Learn more in AM's [Map and rotate secrets](https://docs.pingidentity.com/pingam/8/security/secret-mapping.html). Note the following points for using AM's secret service: * Set a Secret Label Identifier that clearly identifies the agent. * If you update the Secret Label Identifier: * If no other agent shares that secret mapping, AM updates any corresponding secret mapping for the previous identifier. * If another agent shares that secret mapping, AM creates a new secret mapping for the updated identifier and copies its aliases from the previously shared secret mapping. * If you delete the Secret Label Identifier, AM deletes any corresponding secret mapping for the previous identifier, provided no other agent shares that secret mapping. * When you rotate a secret, update the corresponding mapping. ### Create an agent profile for multiple agent instances when post data preservation is enabled By default, the POST data preservation load balancer cookie name and value is set by the agent profile. Therefore, each agent instance behind a load balancer requires its own agent profile. In scalable environments, such as deployments with load balancing, or environments that run Kubernetes, resources are dynamically created and destroyed. To facilitate the rapid creation and destruction of agent instances when post data preservation is enabled, set the POST data preservation configuration in `agent.conf` to map one agent profile to multiple agent instances. The configuration in `agent.conf` overrides the configuration in AM for the following properties: * [POST Data Sticky Load Balancing Mode](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.mode.html) * [POST Data Sticky Load Balancing Value](../properties-reference/com.sun.identity.agents.config.postdata.preserve.stickysession.value.html) You can find an example in [Map one agent profile to multiple agent instances when POST data preservation is enabled](../user-guide/load-balancers-proxies.html#lb-POST-data-12all). ### Create an agent profile group Use agent profile groups when you set up multiple agents, and want to inherit settings from the group. 1. In the AM admin UI, go to Realms > *Realm Name* > Applications > Agents > Web. 2. Select the Groups tab, and add a group with the following settings: * Group ID: A name for the profile group. * Server URL: The URL of the AM server in which to store the profile. ### Inherit properties from an agent profile group 1. Set up an agent profile and agent profile group, as described in [Create an agent profile for a single agent instance](#create-agent-profile) and [Create an agent profile group](#create-agent-group). 2. In the AM admin UI, select your agent profile. 3. On the Global tab, select Group, and select a group from the drop-down menu. The agent profile is added to the group. 4. For each setting in the Global tab, select or deselect the [icon: lock, set=fa]icon: * [icon: lock, set=fa]: Inherit this setting from the group * [icon: unlock, set=fa]: Do not inherit this setting from the group ## Authenticate agents to the identity provider ### Authenticate agents to Advanced Identity Cloud Advanced Identity Cloud provides a [journey](https://docs.pingidentity.com/pingoneaic/realms/journeys.html) called `Agent`. The `Agent` journey validates the agent credentials with an [Agent Data Store Decision](https://docs.pingidentity.com/auth-node-ref/latest/agent-data-store-decision.html) node. All Web Agent, Java Agent and PingGateway profiles use the `Agent` tree. Don't change its configuration. ### Authenticate agents to AM * AM 8 and later AM 8 and later provide an [authentication tree](https://docs.pingidentity.com/pingam/8/am-authentication/authn-introduction-authn.html#default-trees) called `Agent` (unless you upgrade from an earlier version using the file-based configuration). The `Agent` tree validates the agent credentials with an [Agent Data Store Decision](https://docs.pingidentity.com/auth-node-ref/8/agent-data-store-decision.html) node. All Web Agent, Java Agent and PingGateway profiles use the `Agent` tree. Don't change its configuration. * AM 7.2, 7.3, 7.4, and 7.5 With earlier versions of AM, you have the choice of authenticating to AM using the `Agent` tree (default) or the deprecated authentication module. To change how the agent authenticates to AM, set the [Agent Authentication Mode](../properties-reference/com.forgerock.agents.config.agent.auth.mode.html) property. If you use the `Agent` tree, you must create it as explained in the following section. #### Create an `Agent` authentication tree The `Agent` tree must pass the agent credentials to the Agent Data Store Decision node. When you define a tree in AM, that same tree is used for all instances of Web Agent, Java Agent and PingGateway. Consider this point if you change the tree configuration. 1. On the Realms page of the AM admin UI, choose the realm in which to create the authentication tree. 2. On the Realm Overview page, click Authentication > Trees > Create tree. 3. Create a tree named `Agent`. The authentication tree designer is displayed, with the `Start` entry point connected to the `Failure` exit point, and a `Success` node. The authentication tree designer provides the following features on the toolbar: | Button | Usage | | -------------------------------------------------------- | ------------------------------------------------------------------- | | ![Trees auto layout](_images/icon-trees-auto-layout.png) | Lay out and align nodes according to the order they are connected. | | ![Trees full screen](_images/icon-trees-full-screen.png) | Toggle the designer window between normal and full-screen layout. | | ![Trees delete node](_images/icon-trees-delete-node.png) | Remove the selected node. The `Start` entry point can't be deleted. | 4. Using the Filter bar, find and then drag the following nodes from the Components panel into the designer area: * [Zero Page Login Collector](https://docs.pingidentity.com/auth-node-ref/8/zero-page-login-collector.html) node to check whether the agent credentials are provided in the incoming authentication request and use their values in the following nodes. This node is required for compatibility with Java Agent and Web Agent. * [Page](https://docs.pingidentity.com/auth-node-ref/8/page.html) node to collect the agent credentials if they aren't provided in the incoming authentication request and use their values in the following nodes. * [Agent Data Store Decision](https://docs.pingidentity.com/auth-node-ref/8/agent-data-store-decision.html) node to verify that the agent credentials match the registered Web Agent profile. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Many nodes can be configured in the panel on the right side of the page. Unless otherwise stated, don't configure the nodes and use only the default values. | 5. Drag the following nodes from the Components panel into the Page node: * Username Collector node, to prompt the user to enter their username * Password Collector node,to prompt the user to enter their password 6. Connect the nodes as follows and save the tree: ![A tree that can be used to authenticate an agent to AM.](_images/agenttree-am.png) ## Check agents can connect to the identity provider You can authenticate as the agent you created a profile for in Advanced Identity Cloud or AM to check the agent can connect successfully. A successful connection proves the agent can connect to Advanced Identity Cloud or AM, their credentials are correct, and a valid agent profile exists. Authenticate as follows: ```none $ curl \ --request POST \ --header "X-OpenAM-Username: agent-id" \ (1) --header "X-OpenAM-Password: password" \ (2) --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=2.1" \ 'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?auth-service' (3) ``` | | | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1** | Replace *agent-id* with the ID of the agent profile you created. | | **2** | Replace *password* with the agent password. | | **3** | Replace *auth-service* with either `authIndexType=module&authIndexValue=Application` or `authIndexType=service&authIndexValue=Agent` depending on whether you [authenticate](#authenticate-agent-idc) using the default non-configurable authentication module or a journey called `Agent`. | If authentication is successful, the response includes the `tokenId` that corresponds to the agent session and the URL to which the agent would normally be redirected. For example: ```json { "tokenId":"AQIC5wM...​TU3OQ*", "successUrl":"/am/console", "realm":"/alpha" } ```