Product
Hosting Environment
Operating System
Capability
Task Type
Draft Beta
Close

Configuration file reference guide

Updated 94

Add to MyDocs | Hide Show Table of Contents

Configuration file reference

This document provides a reference to configurable parameters used by PingAccess at runtime. These parameters are configured in the run.properties file located at <PA_HOME>/conf/.

Note: Changes made to the run.properties file will take effect after PingAccess is restarted.
Tip: When storing passwords in run.properties, we strongly recommend you obfuscate them using the obfuscate.bat or obfuscate.sh utility to mask the password value. This utility is located in the PA_HOME/bin folder.
account.locking.max.consecutive.failures
Defines the maximum number of failed login attempts before locking the account when using basic authentication in the administrative UI or administrative REST APIs. The default value is 3.
account.locking.max.lockout.period
Defines, in minutes, the amount of time to lock an account out from the administrative interfaces after exceeding the account.locking.max.consecutive.failures. The default value is 1.
admin.acceptors
Defines the number of admin acceptor threads used to establish connections. The default value is 1.
admin.auth
Overrides the administrator authentication method. For example, if SSO Authentication is enabled and is somehow misconfigured, this property can be used to bypass the database configuration and force the use of Basic Authentication. Default value is default.
admin.backlog
Defines the maximum queue length for incoming admin connection indications. The default value is 512.
admin.bindAddress
Defines the IP address that admin.port will bind to. This is typically required on multihomed servers having multiple IP addresses. The default value of 0.0.0.0 means that the port will bind to all of the server's IP addresses.
admin.header.Strict-Transport-Security
Sets the parameters for the Strict-Transport-Security response header sent to the browser when an administrator is interacting with the Admin UI.
admin.header.X-Content-Type-Options
Sets the parameters for the X-Content-Type-Options response header sent to the browser when an admin is interacting with the Admin UI.
admin.header.X-Frame-Options
Sets the parameters for the X-Frame-Options HTTP response header sent to the browser when an admin is interacting with the Admin UI.
admin.header.X-XSS-Protection
Sets the parameters for the X-XSS-Protection HTTP response header sent to the browser when an admin is interacting with the Admin UI.
admin.headers
Additional headers added to responses from the PingAccess Administrator Console and the Administrator API interface. Header values are defined using the admin.header prefix.
admin.httptransport.coreThreadPoolSize
Defines the number of threads to keep in the admin transport pool, even if they are idle. The default value is 5.
admin.httptransport.ioThreads
Defines the number of I/O threads for the admin host. A value of 0 is used to denote that PingAccess should automatically calculate the appropriate number of I/O threads for the host. The default value is 0.
admin.httptransport.maxThreadPoolSize
Defines the maximum number of threads for the admin transport pool. The default value is -1, which denotes no limit.
admin.httptransport.socketTimeout
Defines, in milliseconds, the admin socket timeout. The default value is 30000.
admin.max.request.bodylength
Defines, in megabytes, the maximum body length for a request to the administrative API endpoint. The default value is 15.
admin.polling.delay
Defines, in milliseconds, how long after the initial query to the administrative console that the replica administrative node begins querying for configuration information. The default is every 2000 milliseconds.
admin.polling.initialdelay
Defines, in milliseconds, how long after the replica administrative node starts up before it begins to poll the administrative console for configuration information. The default is 500.
admin.port
Defines the TCP port on which the PingAccess administrative console runs. Default is 9000.
admin.reuseAddress
When enabled, allows a process to bind to a port which remains in a TIME_WAIT state for the admin transport. The default value is true.
admin.ssl.ciphers
Defines the type of cryptographic ciphers available for use with administrative HTTPS ports.
admin.ssl.protocols
Defines the protocols for use with administrative HTTPS ports.
admin.ui.max.sessions
Defines the maximum number of sessions for the admin UI when admin SLO is not enabled.
agent.assets.header.X-Frame-Options
Sets the parameters for the X-Frame-Options HTTP response header sent to the browser via the agent when responding to a request for an asset used by a PingAccess template.
agent.assets.headers
Additional headers added to responses from PingAccess Agents. Header values are defined using the agent.assets.header prefix.
agent.authz.header.required
Defines whether PingAccess server should authenticate agent requests using agent name and shared secret in the vnd-pi-authz header. Default value is true. Setting this to false is useful for POCs and/or debugging.
agent.cache.invalidated.response.duration
Defines the duration in seconds that application configuration changes are sent by PingAccess server to agents using the vnd-pi-cache-invalidated header in agent responses for the changed application. Default value is 900.
agent.default.token.cache.ttl
Defines, in seconds, the time to live for cached agent tokens.
agent.error.header.X-Frame-Options
Sets the parameters for the X-Frame-Options HTTP response header sent to the browser via the agent when responding with a PingAccess error template.
agent.error.headers
Additional headers added to error responses from PingAccess Agents. Header values are defined using the agent.error.header prefix.
agent.http.backlog
Defines the maximum queue length for incoming admin connection indications. The default value is 512.
agent.http.bindAddress
Defines the address from which an engine listens for agent requests.
agent.http.enabled
Defines whether a STANDALONE or CLUSTERED_ENGINE node listens for agent requests on the port defined by the agent.http.port setting. Default is true.
agent.http.port
Defines the TCP port on which the engine listens for agent requests. Default is 3030.
agent.http.reuseAddress
When enabled, allows a process to bind to a port which remains in a TIME_WAIT state for the agent transport. The default value is true.
agent.http.secure
Defines whether the engine is using HTTPS for agent requests. Default is true.
agent.httptransport.coreThreadPoolSize
Defines the number of threads to keep in the agent transport pool, even if they are idle. The default value is 5.
agent.httptransport.ioThreads
Defines the number of I/O threads for the agent host. A value of 0 is used to denote that PingAccess should automatically calculate the appropriate number of I/O threads for the host. The default value is 0.
agent.httptransport.maxThreadPoolSize
Defines the maximum number of threads for the agent transport pool. The default value is -1, which denotes no limit.
agent.httptransport.socketTimeout
Defines, in milliseconds, the agent socket timeout. The default value is 30000.
agent.ssl.ciphers
Defines the type of cryptographic ciphers available for use with agent HTTPS ports.
agent.ssl.protocols
Defines the protocols used for communication with agent HTTPS ports.
as.ssl.ciphers
Defines the type of cryptographic ciphers available for use with authorization server HTTPS ports.
as.ssl.protocols
Defines the protocols used for communication with authorization server HTTPS ports.
client.ioThreads
Defines the number of threads for client connections to backend sites. A value of 0 means there is no limit. The default value is 0.
clusterconfig.acceptors
Defines the number of cluster configuration acceptor threads used to establish connections. The default value is 1.
clusterconfig.backlog
Defines the maximum queue length for incoming cluster configuration connection indications. The default value is 512.
clusterconfig.bindAddress
Defines the optional address used for cluster configuration.
clusterconfig.enabled
When enabled, uses the cluster coonfiguration port for cluster replication. When disabled, the admin port is used for cluster configuration replication. The default value is true.
Note: This parameter is set to false by the PingAccess Upgrade Utility after a PingAccess cluster is upgraded from a version earlier than 4.0.
clusterconfig.httptransport.coreThreadPoolSize
Defines the number of threads to keep in the cluster configuration transport pool, even if they are idle. The default value is 5.
clusterconfig.httptransport.ioThreads
Defines the number of I/O threads for the cluster configuration host. A value of 0 is used to denote that PingAccess should automatically calculate the appropriate number of I/O threads for the host. The default value is 0.
clusterconfig.httptransport.maxThreadPoolSize
Defines the maximum number of threads for the cluster configuration transport pool. The default value is -1, which denotes no limit.
clusterconfig.httptransport.socketTimeout
Defines, in milliseconds, the cluster configuration socket timeout. The default value is 30000.
clusterconfig.port
Defines the optional port used for cluster configuration.
clusterconfig.reuseAddress
When enabled, allows a process to bind to a port which remains in a TIME_WAIT state for the cluster configuration transport. The default value is true.
clusterconfig.secure
When enabled, enables SSL communications for the cluster configuration port. The default value is true.
clusterconfig.ssl.ciphers
Defines the type of cryptographic ciphers available for use with HTTPS ports in a clustered configuration.
clusterconfig.ssl.protocols
Defines the protocols used for communication with HTTPS ports in a clustered configuration.
enable.detailed.heartbeat.response
When enabled, this setting enables a customizable heartbeat response to be returned. When disabled, the heartbeat endpoint returns a 200 OK response. The default value is false.
engine.admin.configuration.audience
Defines the audience used for cluster authentication. This property must be set to the same value on all nodes in a PingAccess cluster. The default value is PingAccessAdminServer.
engine.assets.header.X-Frame-Options
Sets the parameters for the X-Frame-Options HTTP response header sent to the browser via the engine when responding to a request for an asset used by a PingAccess template.
engine.assets.headers
Additional headers added to responses from the PingAccess Engine. Header values are defined using the engine.assets.header prefix.
engine.error.header.X-Frame-Options
Sets the parameters for the X-Frame-Options HTTP response header sent to the browser via the engine when responding with a PingAccess error template.
engine.error.headers
Additional headers added to error responses from the PingAccess Engine. Header values are defined using the engine.error.header prefix.
engine.http.acceptors
Defines the number of engine acceptor threads used to establish connections. The default value is 1.
engine.http.backlog
Defines the maximum queue length for incoming engine connection indications. The default value is 512.
engine.http.bindAddress
Defines the address for an engine in a clustered environment.
engine.http.enabled
Defines whether a STANDALONE or CLUSTERED_ENGINE node listens for requests on the ports defined by the Engine Listeners. Default is true.
engine.http.reuseAddress
When enabled, allows a process to bind to a port which remains in a TIME_WAIT state for the engine transport. The default value is true.
engine.httptransport.coreThreadPoolSize
Defines the number of threads to keep in the engine transport pool, even if they are idle. The default value is 5.
engine.httptransport.ioThreads
Defines the number of I/O threads for the engine host. A value of 0 is used to denote that PingAccess should automatically calculate the appropriate number of I/O threads for the host. The default value is 0.
engine.httptransport.maxThreadPoolSize
Defines the maximum number of threads for the engine transport pool. The default value is -1, which denotes no limit.
engine.httptransport.socketTimeout
Defines, in milliseconds, the engine socket timeout. The default value is 30000.
engine.polling.delay
Defines, in milliseconds, how long after the initial query to the administrative console that the engine begins querying for configuration information. The default is every 2000 milliseconds.
engine.polling.initialdelay
Defines, in milliseconds, how long after the engine starts up before it begins to poll the administrative console for configuration information. The default is 500.
engine.ssl.ciphers
Defines the type of cryptographic ciphers available for use with engine HTTPS ports.
engine.ssl.protocols
Defines the protocols used with engine HTTPS ports.
engine.websocket.maxConnections
Sets the maximum number of allowed web socket connections. Default is -1 (unlimited).
pa.admin.test.connections
A boolean property that allows the PingAccess admin UI to make HTTP calls to validate that it can reach PingFederate and sites when the user configures them.
pa.admin.user.password.error.message
Defines the message returned when password complexity is not satisfied. The default value is Password must be at least 8 characters in length, contain one upper-case letter, one lower-case letter and one digit..
pa.admin.user.password.regex
Defines the regex that controls password complexity for the Administration Console. The default value is
((?=.*\\d)(?=.*[a-z])(?=.*[A-Z]).{8,20})
pa.auditing.unknown.resource
When set to true, this setting causes PingAccess to audit requests for resources that are requested but not mapped to an Application or Resource. This setting can be used to help troubleshoot resource definition issues. The default is false.
pa.backup.filesToKeep
Defines the number of backup files to preserve when the Administrator authenticates to PingAccess. The default value is 25.
pa.cluster.auth.pwd
Sets the key that each engine in the cluster must use to authenticate when joining the group. This prevents unauthorized engines from joining a cluster. This key should be treated as a strong key rather than as a human-readable password value. (Values: any string or blank)
Important: If pa.cluster.encrypt is true, pa.cluster.auth.pwd must not be blank.
pa.cluster.bind.address
Defines the IP address to which you bind the TCP or UDP listener. The default is 127.0.0.1.
pa.cluster.bind.port
The port associated with the bind-address property above. The default is 7610. Whether this is a TCP or UPD port depends on the value configured for the pa.cluster.interprocess.communication property (see above).
pa.cluster.encrypt
Indicates whether to encrypt network traffic sent between engines in a cluster. (Values: true or false [default])
Important: If pa.cluster.encrypt is true, pa.cluster.auth.pwd must not be blank.
pa.cluster.failure.detection.bind.port
Indicates the bind port of a server socket that is opened on the given engine and used by other engines as part of one of the cluster's failure-detection mechanisms. This port is bound to the address determined by pa.cluster.bind.address. The default is 7710. Whether this is a TCP or UDP port depends on the value configured for the pa.cluster.interprocess.communication property (see above).
pa.cluster.interprocess.communication
Defines how the JGroups cluster communicates. none (the default): Indicates that no communication is configured between servers in the cluster. udp: Indicates that the cluster uses Multicast communications to send and receive information to and from multiple servers at once. tcp: Indicates that the cluster uses Unicast communications to send and receive information to and from individual servers one at a time.
pa.cluster.mcast.group.address
Defines the IP address shared among engines in the same cluster for UDP multicast communication; required when the interprocess communication mode is set to udp. (Range: 224.0.0.0 to 239.255.255.255; note that some addresses in this range are reserved for other purposes.) This property is not used for TCP. All engines in a cluster must use the same address for this property and the port property below. The default value is 239.16.96.69.
pa.cluster.mcast.group.port
Defines the UDP port associated with the pa.cluster.mcast.group.address property above. The default value is 7611.
pa.cluster.serverstate.replicationIntervalMilliseconds
Defines, in milliseconds, how often Rate Limiting metadata is replicated within a subcluster. The default value is 1000.
pa.cluster.serverstate.staleEntryEvictionIntervalSeconds
Defines, in seconds, how often a PingAccess engine scans the Rate Limiting metadata to evaluate metadata to be removed from the cache, based on the pa.cluster.serverstate.timeToIdleSeconds value. The default value is 60.
pa.cluster.serverstate.timeToIdleSeconds
Defines, in seconds, how long metadata for the Rate Limiting rule is maintained by a PingAccess Engine after its last use. The default value is 86400.
pa.cluster.tcp.discovery.initial.hosts
Designates the initial hosts to be contacted for group membership information when discovering and joining the group; required when the interprocess communication mode is set to tcp. The value is a comma-separated list of host names (or IP addresses) and ports. For example, 127.0.0.1[7602].
pa.default.availability.ondemand.connectTimeout
Defines, in milliseconds, the amount of time to wait before trying to connect to the remote host. The default is 10000.
pa.default.availability.ondemand.failedRetryTimeout
Defines, in seconds, the amount of time to wait before retrying a failed host. The default is 60.
pa.default.availability.ondemand.maxRetries
Defines the maximum number of retries before marking the target system down. The default is 2.
pa.default.availability.ondemand.pooledConnectionTimeout
Defines, in milliseconds, the amount of time to wait before timing out the request for a pooled connection to the target site. The default is -1.
pa.default.availability.ondemand.readTimeout
Defines, in milliseconds, the amount of time to wait before timing out the read response for a target site. The default is -1.
pa.default.availability.ondemand.retryDelay
Defines, in milliseconds, the amount of time to wait after a timeout before retrying the host. The default is 250.
pa.default.contentRewrite.buffer.default
Defines, in bytes, the default buffer size when using a Rewrite Content rule to do a search and replace of content. The default value is 2048.
pa.default.contentRewrite.buffer.min
Defines, in bytes, the minimum buffer size used when using a Rewrite content rule. The default value is 1024.
pa.default.limitRequestLine
Defines the maximum number of bytes to read from the request line. The default value is 8192.
pa.default.maxConnectionsPerSite
Defines the maximum number of connections PingAccess will open to the PingFederate Admin or Engine. A value of -1 means there is no limit. The default is -1.
pa.default.maxHeaderCount
Defines the maximum number of headers to read from a request. The default value is 100.
pa.default.maxHttpHeaderSize
Defines the maximum number of bytes to read when reading headers. The default value is 8192.
pa.default.maxRequestBodySize
Defines the maximum number of bytes to read from a request body. The default value is 204800.
pa.default.session.cookie.attributes.httponly
Defines the default setting for the HTTP-Only Cookie setting for newly-created web sessions. The default value is true.
pa.default.session.cookie.attributes.secure
Defines the default setting for the Secure Cookie setting for newly-created web sessions. The default value is true.
pa.default.session.cookie.size.threshold
Defines, in bytes, the default maximum session cookie size. The default value is 4093.
pa.ehcache.AuthTokenCache.maxEntriesLocalHeap
Defines the maximum size of the JWT identity mapping token cache used when sending tokens to a protected site. Default is 10000.
pa.ehcache.PATokenValidationCache.maxEntriesLocalHeap
Defines the maximum number of entries in the local heap for decryption of signed or encrypted PingAccess tokens. The default is 10000.
pa.ehcache.PATokenValidationCache.timeToIdleSeconds
Defines, in seconds, the time an entry in the token validation cache can be idle before it is expired. The default is 120 seconds.
pa.ehcache.PATokenValidationCache.timeToLiveSeconds
Defines, in seconds, the maximum time an entry can be in the token validation cache. The default is 300 seconds.
pa.ehcache.PAWamUserAttributesCache.maxEntriesLocalHeap
Defines the maximum number of entries in the local heap for the PA WAM user attribute cache. The default is 10000.
pa.ehcache.PAWamUserAttributesCache.timeToIdleSeconds
Defines, in seconds, the time an entry in the PA WAM user attribute cache can be idle before it is expired. The default is 120 seconds.
pa.ehcache.PAWamUserAttributesCache.timeToLiveSeconds
Defines, in seconds, the maximum time an entry can be in the PA WAM user attribute cache. The default is 300 seconds.
pa.ehcache.PFSessionValidationCache.maxEntriesLocalHeap
Defines the maximum number of entries in the local heap for the session validation cache. The default is 10000.
pa.ehcache.PFSessionValidationCache.timeToIdleSeconds
Defines, in seconds, the time an entry in the session validation cache can be idle before it is expired. The default is 120 seconds.
pa.ehcache.PFSessionValidationCache.timeToLiveSeconds
Defines, in seconds, the maximum time an entry can be in the session validation cache. The default is 300 seconds.
pa.ehcache.PingFederateReferenceTokenCache.maxEntriesLocalHeap
Defines the maximum number of entries in the local heap for OAuth tokens. The default is 10000.
pa.ehcache.ServiceTokenCache.maxEntriesLocalHeap
Defines the maximum number of entries in the local heap for token mediation. The default is 10000.
pa.ehcache.ServiceTokenCache.timeToIdleSeconds
Defines, in seconds, the time an entry in the token mediation cache can be idle before it is expired. The default is 1800 seconds.
pa.ehcache.ServiceTokenCache.timeToLiveSeconds
Defines, in seconds, the maximum time an entry can be in the token mediation cache. The default is 14400 seconds.
pa.ehcache.SessionStateCache.maxEntriesLocalHeap
Defines the maximum size of the identity attribute entry cache when the user's attributes are stored on the server rather than as a cookie. Default is 10000.
pa.interceptors.relativepath.decode.count
Number of times the URL is decoded to check for path traversal characters. The default is 3.
pa.interceptors.relativepath.decode.regex
Defines the accepted URL regex pattern that administrators can customize based on their needs. The default value is:Defines the regular expression to use when checking for a valid path in an incoming request. The default value is
[\\p{Po}\\p{N}\\p{Z}\\p{L}\\p{M}\\p{Zs}\\./_\\-\\\\~()\\{\\}\\[\\]]*
Note: This value is double-escaped as required by the java.util.regex.Pattern Java class.
pa.interceptors.relativepath.strict
When this property is set to true, the incoming URL is matched with the whitelist pattern defined in pa.interceptors.relativepath.decode.regex. All other request URLs are rejected. The default value is false.
pa.jdbc.filepassword
Defines the password used to encrypt the PingAccess configuration database. Default is 2Access.
pa.jdbc.password
Defines the password for the database user of the PingAccess configuration database. Default is 2Access.
pa.jdbc.username
Defines the username for accessing the PingAccess configuration database. Default is sa.
pa.keystore.pw
Defines the password for the $JAVA_HOME/lib/security/cacerts keystore.
pa.localization.missing.message.placeholder
Defines the message used when an error message is unresolvable. An error will be logged.
pa.localization.resource.bundle.cache.enable
When set to false, allows language files in /conf/localization to be added or modified. When true, enables caching of language files and properties.
pa.oidc.logout.redirect
A boolean property that defines whether or not to redirect the user to the token provider on logout. If true, the user is redirected to the token provider.
pa.oidc.logout.redirectURI
The URI that a user gets sent to when they log out.
pa.oidc.post.preservation.encrypt
When enabled, POST data preserved through a redirection to PingFederate for authentication is encrypted on the client to be used after the authentication is successful. The default value is false.
pa.oidc.post.preservation.maxRequestBodySize
Defines, in bytes, the maximum size of the post body for POST preservation. The default value is 8192.
pa.oidc.post.preservation.paramsAttributeName
Used to store the encoded or encrypted POST payload in the browser session storage during POST preservation.
pa.operational.mode
Controls the operational mode of the PingAccess server in a cluster. Valid values are:
  • STANDALONE - Use this value for a standalone (unclustered) PingAccess instance that runs both the administrative console and the engine. This is the default.
  • CLUSTERED_CONSOLE - Use this value for the server instance you want to use as the administrative console server.
    Info: Only one engine in a cluster can run the administrative console.
  • CLUSTERED_CONSOLE_REPLICA - Use this value for the server instance you want to use as the backup administrative console server.
  • CLUSTERED_ENGINE - Use this value to indicate a server engine.
Note:

Define the following Engine and Admin properties depending on what operational mode an engine is using.

  • Define all of the following Engine and Admin properties when pa.operational.mode is set to STANDALONE.
  • Define only the Admin properties when using CLUSTERED_CONSOLE or CLUSTERED_CONSOLE_REPLICA mode.
  • Define only the Engine properties when using CLUSTERED_ENGINE mode.
pa.uri.strict
When enabled, this setting requires the raw input URI be in strict compliance with the URI spec implemented by java.net.URI when generating URIs. The default value is false.
pf.api.keepAliveTimeout
Defines, in milliseconds, the keep alive timeout for the PingFederate API. The default value is 30000.
pf.api.maxConnections
Defines the maximum number of connections PingAccess will establish to the PingFederate API endpoint. A value of -1 means there is no limit. The default value is -1.
pf.api.maxRetries
Defines the maximum number of retries PingAccess attempts to make to the PingFederate server before delcaring the server unavailable. The default value is 0.
pf.api.readTimeout
Defines, in milliseconds, how long the API will wait for responses from PingFederate when making calls to the PingFederate Admin API. The default value is -1.
pf.api.socketTimeout
Defines, in milliseconds, the socket timeout for the PingFederate API endpoint. The default value is 5000.
pf.redirect.header.X-Frame-Options
Sets the parameters for the X-Frame-Options value that is sent when the user is redirected to PingFederate to authenticate.
pf.redirect.headers
Additional headers added to the redirection response that sends the client to PingFederate for authentication. Header values are defined using the pf.redirect.header prefix.
pf.ssl.ciphers
Defines the type of cryptographic ciphers available for use with PingFederate HTTPS ports.
pf.ssl.protocols
Defines the protocols used for communication with PingFederate HTTPS ports.
provider.ssl.ciphers
Defines the type of cryptographic ciphers available for use with Provider HTTPS ports.
provider.ssl.protocols
Defines the protocols used for communication with Provider HTTPS ports.
rule.error.headers
Additional headers added to responses that result from policy rule results. Header values are defined using the rule.error.header prefix.
site.ssl.ciphers
Defines the type of cryptographic ciphers available for use with Site HTTPS ports.
site.ssl.protocols
Defines the protocols used for communication with Site HTTPS ports.
tls.default.cipherSuites
Defines the default set of ciphers used for HTTPS communication.
Note: Legacy browsers may require the addition of SHA1-based ciphers to negotiate a cipher suite with the server. In this case, add the following ciphers to the run.properties file and restart PingAccess:
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
tls.default.protocols
Defines the default protocols used for HTTPS communication.

Tags Product > PingAccess > PingAccess 5.2; Product > PingAccess