--- title: NGINX agent configuration description: Use the $NGINX/paa/http.conf and agent.properties files to manage the configuration of the PingAccess Agent for NGINX. component: pingaccess version: 9.0 page_id: pingaccess:agents_and_integrations:pa_nginx_agent_config canonical_url: https://docs.pingidentity.com/pingaccess/9.0/agents_and_integrations/pa_nginx_agent_config.html revdate: December 19, 2025 section_ids: modifying-the-paa-conf-file: Modifying the paa.conf file modifying-the-agent-properties-file: Modifying the agent.properties file --- # NGINX agent configuration Use the `$NGINX/paa/http.conf` and `agent.properties` files to manage the configuration of the PingAccess Agent for NGINX. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can find more information about improving agent performance in the [Performance tuning guide](../reference_guides/pa_performance_tuning.html). | ## Modifying the `paa.conf` file The `$NGINX/paa/http.conf` file contains the following parameters. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | * You don't have to make any changes to `http.conf` if you followed the PingAccess agent for NGINX [Installation steps](pa_installing_on_nginx.html). * Changes to the `paa_upstream` parameter impact how the agent communicates with PingAccess. Incorrect changes might lead to a non-functional agent. * The `upstream pingaccess-policy-server` contains the `pingaccess_servers` directive. This directive indicates that the servers for the containing upstream are defined by the `agent.properties` file. The agent only allows you to specify this directive for a single upstream. | > **Collapse: Parameters** > > | Parameter | Definition | Default Value | > | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | > | **paa\_property\_files** | Properties file that stores configuration data used to connect the agent to the PingAccess engine nodes. | `$NGINX/paa/agent.properties` | > | **paa\_enabled** | Determines whether the agent is enabled for a specific server configuration. Acceptable values are `on` or `off`.To control which blocks the agent protects, you can set the `paa_enabled` parameter on:- Specific server blocks within the NGINX server > > - Specific location blocksFor example, if you want to set up an unprotected passthrough resource PingAccess should always allow access to, set `paa_enabled` to `off` in the location block representing the unprotected resource. This expedites request processing because the agent doesn't need to request a decision from the PingAccess engine. You can apply this parameter globally to the http block. The agent follows the most specific value that you set. If you set the paa\_enabled parameter to off globally, ensure that the paa\_enabled parameter is set to on for the PingAccess reserved application context root. By default, this context root is /pa. | `off` | > | **paa\_upstream** | Defines the upstream that the PingAccess agent uses to route policy decision requests to PingAccess policy servers. | `pingaccess-policy-server` | > | **paa\_upstream\_max\_response\_header\_size** | Defines the maximum size of the response header, in bytes, that the PingAccess agent can receive from a PingAccess policy server. | `4096` | > | **paa\_thread\_pool** | Defines the thread pool the agent uses for the blocking operations it performs. This includes only policy cache lookup operations when using the ZeroMQ multiprocess policy cache. | `default` | ## Modifying the `agent.properties` file The `agent.properties` file can contain the following properties. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * If you make changes to the `agent.properties` file, you must restart the web server. * You can add comments to the `agent.properties` file if necessary. The agent ignores lines beginning with the `#` or `!` characters. | > **Collapse: Properties** > > | Property | Definition | Default Value | > | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | `agent.engine.configuration.scheme` | The Uniform Resource Identifier (URI) *(tooltip: \
\

Identifies a web resource with a string of characters conforming to a specified format.\

\
)* scheme the agent uses to connect to the PingAccess engine node. Acceptable values include:- `http` > > - `https` | `https` | > | `agent.engine.configuration.host` | The PingAccess host name. | The value in the agent node's `PingAccess Host` field. | > | `agent.engine.configuration.port` | The port that the agent connects to on the PingAccess host. This value is defined in the PingAccess run.properties file. Learn more in the Configuration file reference. | Defined in the PingAccess `run.properties` file. | > | `agent.engine.configuration.username` | The unique agent name that identifies the agent in PingAccess. | Defined in the PingAccess admin console.This value corresponds with the **Name** you assign to the agent during creation.Learn more in the [Name](../pingaccess_user_interface_reference_guide/pa_agent_field_descriptions.html) table entry. | > | `agent.engine.configuration.shared.secret` | The password the agent uses to authenticate with the engine. | Generated by PingAccess when you click **Save & Download** after creating an agent in the admin console.Learn more in [Adding agents](../pingaccess_user_interface_reference_guide/pa_adding_agents.html). | > | `agent.engine.configuration.bootstrap.truststore` | The base64-encoded public certificate the agent uses to establish HTTPS trust with the PingAccess engine. If you're having difficulty connecting an agent to the PingAccess engine, complete the following steps to verify that the Agent Trusted Certificate is configured correctly: Base64 decode the public certificate into a .crt file and review the contents. In the PingAccess server, make sure that the agent HTTP listener is using the matching private key. Learn more in Assigning key pairs. | Generated by PingAccess. | > | `agent.engine.configuration.keypair` Only available when using version 3.0 or later of the agent with PingAccess 8.3 or later. | The private key the agent uses to sign JWTs it generates for authenticating to the engine. | Generated by PingAccess if the **Require Token Authentication** advanced setting is enabled.Learn more in [Agent field descriptions](../pingaccess_user_interface_reference_guide/pa_agent_field_descriptions.html). | > | `agent.engine.configuration.maxConnections` | The number of connections that a single web server worker process maintains to the PingAccess engine defined in the `agent.engine.configuration.host` property. | `10` | > | `agent.engine.configuration.timeout` | The maximum amount of time, in milliseconds, that an agent request made to PingAccess can take. If this time is exceeded, the client receives a generic `500 Server Error` response. | `30000` | > | `agent.engine.configuration.connectTimeout` | The maximum amount of time, in milliseconds, that the agent can take to connect to the PingAccess engine. If this time is exceeded, the client receives a generic `500 Server Error` response. | `30000` | > | `agent.cache.missInitialTimeout` | The maximum amount of time (in milliseconds) that a web server worker process waits for a response to a policy cache request sent to other web server worker processes. | `5` | > | `agent.cache.broker.publisherPort` | The network port that web server processes use to publish policy cache requests to other web server worker processes. This port is bound to the localhost network only. | `3031` | > | `agent.cache.broker.subscriberPort` | The network port that web server processes use to receive policy cache requests from other web server worker processes. This port is bound to the localhost network only. | `3032` | > | `agent.cache.maxTokens` | The maximum number of tokens that are stored in the policy cache for a single web server worker process. A value of `0` means there is no maximum. | `0` | > | `agent.cache.disabled` | Determines whether policy decision caching is enabled or disabled. A value of `1` disables caching, forcing the agent to communicate with the PingAccess host any time a policy decision needs to be made.You might want to use this option for custom rules created using the PingAccess SDK that involve data that changes with every request within a resource and session. Disabling caching has a significant impact on the scalability of the PingAccess policy servers, as the policy server processes every rule evaluation. Because of the performance penalty, only use this option if necessary. | By default, this property isn't included in the `agent.properties` file. | > | `agent.engine.configuration.failover.hosts` | The host name and port of the PingAccess server where the agent should send requests in the event of a failover from the PingAccess host. If this parameter is set, the upstream block name in $NGINX/paa/http.conf needs to be modified to a name that will be found in the certificate associated with the PingAccess agent HTTPS listener. For example, if your PingAccess certificate contains the name pa.nginx, set the upstream name to upstream pa.nginx. | Defined in the PingAccess admin console. | > | `agent.engine.configuration.failover.failedRetryTimeout` | The number of milliseconds to wait before the agent should retry connecting to a failed PingAccess server. | `60000` | > | `agent.engine.configuration.failover.MaxRetries` | The number of times to retry a connection to a PingAccess server after an unsuccessful attempt. If all retries fail, the agent marks the PingAccess server as failed for the duration of the `agent.engine.configuration.failover.failedRetryTimeout` value and tries another PingAccess server if one is available. | `2` | > | `agent.cache.type` | Controls the type of policy cache used by the agent. There are three acceptable values for this property:- AUTO > > Determines the appropriate cache to use based on the number of worker processes. If the number of worker processes is 1, the agent uses the `STANDALONE` cache. If the number of worker processes is 2 or more, the agent uses the `ZMQ` cache. > > - STANDALONE > > Doesn't share policy cache entries across worker processes. > > - ZMQ > > Allows the agent to share policy cache entries across all worker processes using ZeroMQ for inter-process communication. | `AUTO` | > | `agent.send.inventory` | Determines whether the `vnd-pi-agent` agent inventory header is sent with each request to the PingAccess policy server.This header contains the following fields:- `v` > > The PingAccess agent version. > > - `t` > > The type of PingAccess agent retrieved using the `NGINX_VER_BUILD` macro. > > - `h` > > The host name of the PingAccess agent retrieved using the `ServerName` directive.Learn more in [Agent inventory logging](../configuring_and_customizing_pingaccess/pa_agent_inventory_logging.html). | `true` | > | `agent.inventory` | Specifies additional values to include in the `vnd-pi-agent` agent inventory header.This property uses the following syntax:``` > agent.inventory=exampleheader=TEST;exampleheader2=TEST2; > ``` The specified header fields are case sensitive. | By default, this property isn't included in the `agent.properties` file. | > | `agent.cache.defaultTokenType` | Determines which token type takes precedence when making an access decision if both a cookie and an authorization header token are included in a request.Acceptable values are `C` for cookie or `A` for authorization bearer token. Learn more in the **token-type**, **path**, and **vnd-pi-token-cache-oauth-ttl** entries in [PAAP agent response](pa_ap_agent_response.html). By default, this property isn't included in the agent.properties file. To configure A as the agent.cache.defaultTokenType, you must add this property to the agent.properties file and set to A. | `c` | > | `agent.request.block.xss.characters` | If present, specifies a value (or values) that prompts PingAccess to block a request if it finds one or more of them in the request body. When defining these values, you can:- Use actual characters or URL-encoded characters > > - Specify a range of characters, such as a-z or `%00-%1f` > > - Use commas as delimiters to define multiple values > > To block a comma, you must URL encode it as %2C. > > - Configure any of the following special combinations for one value: > > * Two forward slashes (//) > > * A period and a forward slash (./) > > * A forward slash and a period (/.) > > * A forward slash and an asterisk (/\*) > > * An asterisk and a period (\*.)The following example demonstrates how to block some common XSS characters:``` > agent.request.block.xss.characters=<,>,',/\,\,%22,%0a,%0d > ``` Blocked requests are recorded as error entries in the PingAccess log. To get more details about why a particular request was blocked, set the log level to debug and review these error entries. | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.uri.characters` | If present, specifies a value (or values) that prompts PingAccess to block a request if it finds one or more of them in the request URI.When defining these values, follow the syntax established in the `agent.request.block.xss.characters` table entry.The following example demonstrates how to block some common URI characters:``` > agent.request.block.uri.characters=//,./,/.,/,.,~,\,%00-%1f,%7f > ``` | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.query.characters` | If present, specifies a value (or values) that prompts PingAccess to block a request if it finds one or more of them in the request's query parameters.When defining these values, follow the syntax established in the `agent.request.block.xss.characters` table entry.The following example demonstrates how to block some common query characters:``` > agent.request.block.query.characters=<,>,&,%22,%27,%28,%29,%7b,%7d > ``` | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.form.characters` | If present, specifies a value (or values) that prompts PingAccess to block a request if it finds one or more of them in the request's form parameters. The request must have a Content-Type header value of application/x-www-form-urlencoded for the agent to block form characters.When defining these values, follow the syntax established in the `agent.request.block.xss.characters` table entry.The following example demonstrates how to block some common form characters:``` > agent.request.block.form.characters=<,>,&,%22,%27,%28,%29,%7b,%7d > ``` | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.xss.http.status` | Specifies a custom status code to display when the agent blocks a request because of a bad XSS character. When configuring HTTP status codes initially, consider using a 500 error code to create more obvious test results. After you complete testing, set the HTTP status code to a more reasonable value, such as a 400 error code.The following example demonstrates how to set an XSS HTTP status code:``` > agent.request.block.xss.http.status=400 > ``` | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.uri.http.status` | Specifies a custom status code to display when the agent blocks a request because of a bad URI character.The following example demonstrates how to set a URI HTTP status code:``` > agent.request.block.uri.http.status=404 > ``` | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.query.http.status` | Specifies a custom status code to display when the agent blocks a request because of a bad query character.The following example demonstrates how to set a query HTTP status code:``` > agent.request.block.query.http.status=400 > ``` | By default, this property isn't included in the `agent.properties` file. | > | `agent.request.block.form.http.status` | Specifies a custom status code to display when the agent blocks a request because of a bad form character.The following example demonstrates how to set a form HTTP status code:``` > agent.request.block.form.http.status=400 > ``` | By default, this property isn't included in the `agent.properties` file. |