During the installation of the agent, a configuration schema extension is added to the system.webServer section. This schema extension adds the following two configuration options:

Parameter Definition Default Value

PaaCertificateDir

A string value containing the path to the certificates extracted from the .properties files.

C:\Program Files\Ping Identity\PingAccess Agent for IIS\certs.properties

PaaPropertyFiles

The list of .properties files which store configuration data used to connect the agent to the PingAccess engine nodes with which the agent will communicate.

C:\Program Files\Ping Identity\PingAccess Agent for IIS\agent.properties

Important:

Do not make any changes to the previous two configuration options if you followed the steps in Installing on IIS.

Agent.properties

The configured agent.properties files can contain the following properties:

Property Definition Default Value

agent.engine.configuration.scheme

The URI scheme used to connect to the engine node. Acceptable values are:

  • 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.

Tip:

This value is defined in the PingAccess run.properties file.

Defined in the PingAccess admin UI.

agent.engine.configuration.username

The unique agent name that identifies the agent in PingAccess.

Defined in the PingAccess admin UI.

agent.engine.configuration.checkCertRevocation

Determines whether the agent performs certificate revocation list (CRL) checking against the server certificate used by the engine nodes or by a load balancer in front of the engine nodes. A value of 1 enables CRL checking, while a value of 0 disables CRL checking.

This property isn't present by default. The value is treated as 1 when not specified.

agent.engine.configuration.checkCertRevocation.bestEffort

Determines whether the agent ignores the requirement to perform CRL checking if the backend server is offline or missing. A value of 1 enables the ability to ignore CRL checking, while a value of 0 disables the property.

Note:

If the value of the agent.engine.configuration.checkCertRevocation property is 0, the agent ignores the agent.engine.configuration.checkCertRevocation.bestEffort property as well.

This property isn't present by default. The value is treated as 0 when not specified.

agent.engine.configuration.shared.secret

The password which is used to authenticate the agent to the engine.

Defined in the PingAccess admin UI.

agent.engine.configuration.bootstrap.truststore

The base64-encoded public certificate which is used to establish HTTPS trust by the agent to the PingAccess engine.

Note:

If you are having difficulty connecting an agent to the PingAccess engine, complete the following steps to verify that the Agent Trusted Certificate is configured correctly:

  1. Base64 decode the public certificate into a .crt file and review the contents.
  2. 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.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.

Warning:

Disabling caching has a significant impact on the scalability of the PingAccess policy servers, as every rule evaluation is processed by the policy server. Because of the performance penalty, only use this option if necessary.

0

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.

Defined in the PingAccess admin console

agent.engine.configuration.failover.failedRetryTimeout

The number of seconds to wait before the agent should retry connecting to a failed PingAccess server.

60

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
Does not 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 along 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 from the server variable on the IIS context, which returns a string such as Microsoft-IIS/7.5.
h
The host name of the PingAccess agent retrieved from the IIS context.

Learn more in Agent inventory logging.

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;
Note:

The specified header fields are case-sensitive.

This property isn't present by default.

agent.cache.defaultTokenType

Specifies which token-type to favor 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 in the PingAccess 8.1 documentation.

Note:

This property isn't listed in the agent.properties file by default. To configure A as the agent.cache.defaultTokenType, you must add this property to the agent.properties file and set it equal 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
    Note:

    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
Note:

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.

This property isn't present by default.

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

This property isn't present by default.

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

This property isn't present by default.

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.

Important:

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

This property isn't present by default.

agent.request.block.xss.http.status

Set a custom status code to display when the agent blocks a request because of a bad XSS character.

Tip:

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

This property isn't present by default.

agent.request.block.uri.http.status

Set 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

This property isn't present by default.

agent.request.block.query.http.status

Set 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

This property isn't present by default.

agent.request.block.form.http.status

Set 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

This property isn't present by default.

Tip:

You can add comments to the agent.properties files if necessary. The agent ignores lines beginning with the # or ! characters.

Important:

If you make changes to the agent.properties file, you must restart the web server.

Tip:

Learn more about improving agent performance in the Performance tuning guide.