--- title: Prepare for installation description: Consider the following: component: java-agents version: 2025.11 page_id: java-agents:installation-guide:pre-installation canonical_url: https://docs.pingidentity.com/java-agents/2025.11/installation-guide/pre-installation.html section_ids: before-install: Before you install downloading-agent: Download and unzip Java Agent preinstall-tasks: Preinstallation tasks configuring-agent-communication: Configure communication with AM servers proc-agents-secret-IDs-am65: "Configure AM secret labels for the agents' OAuth 2.0 provider" create-agent-profiles: Create agent profiles create-agent-profile: Create an agent profile for a single agent instance create-agent-group: Create an agent profile group and inherit settings 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 delegate-agent-profile-creation: Create agent administrators for a realm --- # Prepare for installation ## Before you install Consider the following: * Install AM and Java Agent in different containers. * Install the container before you install the agent. * Install only one Java Agent for each container. * Install a supported version of the Java runtime environment, as described in [Java requirements](https://docs.pingidentity.com/java-agents/release-notes/before-you-install.html#java-requirements). Set the `JAVA_HOME` environment variable accordingly. The agent installer requires Java. ```bash $ echo $JAVA_HOME /path/to/java ``` * 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). * If you want to install Java Agent with a FIPS 140-3 compliant security provider, you must perform certain steps before installing the agent. Learn more in [Integrate with Bouncy Castle FIPS provider](secure-connections.html#fips). ## Download and unzip Java 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: | Directory | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------- | | `bin` | The `agentadmin` installation and configuration program. Learn more from [agentadmin command](agentadmin.html). | | `config` | Configuration templates used by the `agentadmin` command during installation | | `data` | Not used | | `etc` | Configuration templates used during installation | | `installer-logs` | Location of log files written during installation | | `legal-notices` | Licensing information including third-party licenses | | `lib` | Shared libraries used by the agent | | `locale` | Property files used by the installation program | | `README` | README file containing platform and install information for the agent | ## Preinstallation tasks 1. 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 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 using a password manager or by using the command line tool [agentadmin --key](agentadmin.html#agentadmin-key). | 2. (Optional) Create a signing key for pre-authentication cookies and POST data preservation cookies. The key must be at least 64 characters long, but preferably 80. 1. Create the key with the [agentadmin --key](agentadmin.html#agentadmin-key) command: * Unix * Windows ``` $ agentadmin --key 80 ZRY...xXO ``` ``` C:> agentadmin --key 80 ZRY...xXO ``` 2. Write the key to a file: * Unix * Windows ``` $ cat > /secure-directory/signing-key.txt ZRY...xXO CTRL+D $ chmod 400 /secure-directory/signing-key.txt ``` ``` C:> type > /secure-directory/signing-key.txt ZRY...xXO CTRL+Z ``` In Windows Explorer, right-click the file, select Read-Only, and then click OK. 3. In AM, add an agent profile, as described in [Create agent profiles](#create-agent-profiles): The examples in this guide use an agent profile in the top-level realm, with the following values: * Agent ID: `java-agent` * Agent URL: `https://agent.example.com:443/app` * Server URL: `https://am.example.com:8443/am` * Password: `password` 4. In AM, add a policy set and policy, to protect resources with the agent, as described in [Policies](https://docs.pingidentity.com/pingam/8/authorization-guide/policies.html) in AM's *Authorization guide*. The examples in this guide use 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 create your own policy set instead of using the default policy set, `iPlanetAMWebAgentService`, update the following properties in the agent profile: * [Policy Set Map](../properties-reference/org.forgerock.agents.policy.set.map.html) * [Policy Evaluation Realm Map](../properties-reference/org.forgerock.agents.policy.evaluation.realm.map.html) 5. When you exchange **signed** OpenID Connect JWTs between AM and the agent, set up a new key and secret as described in [Configure communication with AM servers](#configuring-agent-communication). Do not use the default `test` key pair in a real environment. ## Configure communication with AM servers AM communicates authentication and authorization information to Java Agent by using OpenID Connect (OIDC) JSON web tokens (JWT). To secure the JSON payload, AM and the agent support JWT signing with the RS256 algorithm. For more information, refer to [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518.html). AM uses an HMAC signing key to protect requested `ACR` claims values between sending the user to the authentication endpoint, and returning from successful authentication. By default, AM uses a demo key and an autogenerated secret for these purposes. For production environments, perform the steps in the following procedure to create new key aliases and configure them in AM. ### Configure AM secret labels for the agents' OAuth 2.0 provider By default, AM is configured to: * Sign JWTs with the secret mapped to the `am.global.services.oauth2.oidc.agent.idtoken.signing` secret label. The label defaults to the `rsajwtsigningkey` key alias provided in AM's JCEKS keystore. * Sign claims with the secret mapped to the `am.services.oauth2.jwt.authenticity.signing` secret label. The label defaults to the `hmacsigningtest` key alias available in AM's JCEKS keystore. For more information about secret stores, refer to [Secret stores](https://docs.pingidentity.com/pingam/8/security-guide/secret-stores.html) in AM's *Security guide*. 1. Create the following aliases in one of the secret stores configured in AM, for example, the default JCEKS keystore: * RSA key pair * HMAC secret 2. In the AM admin UI, select Configure > Secret Stores > *Keystore Secret Store Name* > Mappings, and configure the following secret labels: * The new RSA key alias in the `am.global.services.oauth2.oidc.agent.idtoken.signing` secret label. * The new HMAC secret in the `am.services.oauth2.jwt.authenticity.signing` secret label. You might already have a secret configured for this secret label, because it is also used for signing certain OpenID Connect ID tokens and remote consent requests. For more information, refer to [Secret label default mappings](https://docs.pingidentity.com/pingam/8/security-guide/secret-mapping.html#secret-mapping.html#secret-label-mappings) in AM's *Security guide*. 3. Save your changes. ## Create agent profiles Use Java 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 [API Explorer](https://docs.pingidentity.com/pingam/8/REST-guide/about-api-explorer.html) in AM's *REST guide*. 1. In the AM admin UI, select Realms > *Realm Name* > Applications > Agents > Java, 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). When the agent is in [remote configuration mode](../user-guide/glossary.html#def-remote-configuration-mode), the Agent URL is used to populate 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. When the agent is in [remote configuration mode](../user-guide/glossary.html#def-remote-configuration-mode), the Server URL is used to populate the agent profile for 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 using a password manager or by using the command line tool [agentadmin --key](agentadmin.html#agentadmin-key). | 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 only contain 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 [mapping](https://docs.pingidentity.com/pingam/8/security-guide/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 group and inherit settings Use agent profile groups to set up multiple agents that inherit settings from the group. 1. In the AM admin UI, select Realms > *Realm Name* > Applications > Agents > Java. 2. In the Group tab, add a group. Use the URL to the AM server in which to store the profile. 3. Edit the group configuration as necessary, and save the configuration. 4. Select Realms > *Realm Name* > Applications > Agents > Java, and select an agent you created previously. 5. In the Global tab, select Group, and add the agent to the group you created previously. The [icon: lock, set=fa]icon appears next to some properties. 6. For each property where [icon: lock, set=fa]appears, toggle the icon to set inheritance: * [icon: unlock, set=fa]: Do not inherit the value from the group. * [icon: lock, set=fa]: Inherit the value 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/latest/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 Java Agent, Web 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/authentication-guide/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/auth-node-agent-data-store-decision.html) node. All Java Agent, Web 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, Java Agent authenticates to AM using the `Agent` tree if it exists but falls back to authenticating with the deprecated authentication module if the tree is missing. If you want to 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 Java Agent, Web 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/auth-node-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/auth-node-page.html) node to collect the agent credentials if they're not 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/auth-node-agent-data-store-decision.html) node to verify that the agent credentials match the registered Java 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" } ``` ## Create agent administrators for a realm To create agent profiles when installing Java Agent, you need the credentials of an AM user who can read and write agent profiles. This section describes how to create an agent administrator for a specific realm. Use this procedure to reduce the scope given to users who create agent profiles. 1. In the AM admin UI, select Realms > *Realm Name* > Identities. 2. In the Groups tab, add a group for agent administrators. 3. In the Privileges tab, enable Log Read and Log Write. 4. Return to Realms > *Realm Name* > Identities, add agent administrator identities. 5. For each identity, select the Groups tab, add the user to agent profile administrator group. 6. Provide each system administrator who installs agents with their agent administrator credentials. When installing the agent with the `--custom-install` option, the system administrator can choose the option to create the profile during installation, and then provide the agent administrator username and the path to a read-only file containing the agent administrator password.