---
title: Setting up an agent in PingAccess
description: Learn how to set up an agent integration for PingAccess applications.
component: solution-guides
page_id: solution-guides:customer_use_cases:htg_agent_setup_pa
canonical_url: https://docs.pingidentity.com/solution-guides/customer_use_cases/htg_agent_setup_pa.html
revdate: April 14, 2025
page_aliases: ["customer_use_cases:htg_agent_setup_pa_config_agent.adoc", "customer_use_cases:htg_agent_setup_pa_config_token_provider.adoc", "customer_use_cases:htg_agent_setup_pa_install_agent.adoc"]
section_ids:
  component: Component
  configuring-an-agent-for-pingaccess: Configuring an agent for PingAccess
  before-you-begin: Before you begin
  steps: Steps
  result: Result:
  example: Example:
  result-2: Result:
  configuring-a-token-provider: Configuring a token provider
  steps-2: Steps
  example-2: Example:
  installing-the-agent: Installing the agent
  steps-3: Steps
---

# Setting up an agent in PingAccess

Learn how to set up an agent integration for PingAccess applications.

## Component

* PingAccess 8.2

* PingAccess 6.3

## Configuring an agent for PingAccess

### Before you begin

* Install PingAccess with either a PingFederate, PingOne, or OpenID Connect (OIDC) token provider configured.

### Steps

1. Sign on to the PingAccess admin console.

2. Go to **Applications > Agents** and click **[icon: plus, set=fa]Add Agents**:

   1. In the **Name** field, enter a name for the agent.

   2. In the **PingAccess Host** field, enter a host name and port number.

   3. To retrieve the `agent.properties` file to use during the agent installation process, click **Save & Download**.

      |   |                                                                                                                                                                                                                                |
      | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
      |   | In most deployments the host name and port must match the `agent.http.port` value in the PingAccess `run.properties` file (default `3030`).The host name and port of the PingAccess server is where this agent sends requests. |

3. Go to **Applications > Applications**.

4. To connect the newly created agent with a PingAccess application, click **[icon: plus, set=fa]Add Application**:

   1. In the **Name** field, enter an application name.

   2. In the **Context Root** field, enter an appropriate value.

   3. In the **Virtual Host(s)** section, click **[icon: plus, set=fa]Create**.

   4. Create a virtual host that matches the agent server's host and port values that users will access, then click **Save**.

5. In the `Web Session` section, click **[icon: plus, set=fa]Create** to create a new web session:

   1. In the **Name** field, enter a name for the web session.

   2. In the **Audience** field, enter the names of the applications using this web session.

   3. In the **Client ID** and **Client Secret** fields, enter the OIDC Login Type values from the PingAccess token provider.

   4. Click **Save**.

      #### Result:

      You return to the **New Application** page.

6. In the **Web Identity Mapping** section, click **[icon: plus, set=fa]Create** to create a new mapping:

   1. In the **Name** field enter an identity mapping name.

   2. In the **Type** list, select **Header Identity Mapping**.

   3. In the **Attributes** section, click **Exclusion List**.

   4. In the **Header Name Prefix** field, enter a prefix pattern the agent application will expect.

      #### Example:

      If your user was Ping, your prefix header for the username field would be "ping-" and then it would say ping-username.

   5. In the **Attribute to Header Mapping** section, click **[icon: plus, set=fa]Add Row**.

   6. In the **Subject Attribute Name** list, select the attribute that corresponds to the user's subject value.

   7. In the **Header Name** field, enter a header name.

   8. Click **Save**.

      #### Result:

      You return to the **New Application** configuration page.

7. In the **Destination** list, select **Agent**.

8. In the **Agent** list, select the agent you created earlier.

9. Select the **Enabled** checkbox and click **Save**.

## Configuring a token provider

### Steps

* For the PingAccess token provider that you're using, add the virtual host's redirect URI to the OAuth client selected for the web session of the created application.

  #### Example:

  https\://*\<virtualhostname>*:*\<virtualhostnameport>*/pa/oidc/cb

## Installing the agent

### Steps

1. Download the appropriate agent installation file from the PingAccess [Add-Ons Downloads](https://www.pingidentity.com/en/resources/downloads/pingaccess.html) page.

2. Configure the PingAccess agent installation.

   You can find installation instructions for each agent type in PingAccess [Agents and Integrations](https://cdn-docs.pingidentity.com/archive/pdf/pingaccess/pingaccess-63.pdf#page=362) (page 362).

3. Copy the `agent.properties` file that you downloaded previously into the PingAccess agent installation directory.

   |   |                                                       |
   | - | ----------------------------------------------------- |
   |   | The properties file must be named `agent.properties`. |

4. To deploy the new PingAccess agent configuration to the desired resources, restart the web or API service that you just installed the agent on.