--- title: Configuring PingFederate properties description: The default administrative console and runtime behavior of PingFederate is controlled in part by configuration properties set in the /pingfederate/bin/run.properties file. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_config_pf_propert canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_config_pf_propert.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: May 22, 2024 section_ids: steps: Steps admin-console-properties: Admin console properties runtime-server-properties: Runtime server properties deployment-properties: Deployment properties --- # Configuring PingFederate properties The default administrative console and runtime behavior of PingFederate is controlled in part by configuration properties set in the `/pingfederate/bin/run.properties` file. ## Steps 1. Edit the `/pingfederate/bin/run.properties` file. | | | | - | ----------------------------------------------------------------- | | | Before editing `run.properties` create a backup copy of the file. | 2. Modify the applicable properties. 3. Restart PingFederate. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You must manually configure the runtime server-related properties on each engine node. The `run.properties` file isn't copied from the console node to the engine nodes automatically. Also, it's not part of the **Replicate Configuration** process. If running, restart PingFederate. | The most common properties are documented in the following tables. For the rest of the properties, including various cookie-encoding options, see the `run.properties` file. The clustering configuration options are also maintained in the `run.properties` file. Learn more in [Deploying cluster servers](../server_clustering_guide/pf_deploying_cluster_servers.html). ## Admin console properties | Property | Description | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pf.admin.https.port` | Defines the port on which the PingFederate administrative console runs. The default value is `9999`. | | `pf.admin.baseurl` | Defines the URL that PingFederate's administrative node uses to populate resource references in Administrative application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)* responses. The administrative node also uses it for the redirect URL it sends to an OpenID Provider (OP) *(tooltip: \
\

In OAuth terms, an authorization server (AS). The OP/AS issues access tokens to protected resources for approved clients (relying parties). The clients use the access token to access the protected resources hosted by the OAuth resource server.\

\
)* for administrator OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* (for example, https\://pingfederate-admin.example.com or, if the load balancer uses a custom port, https\://pingfederate-admin.example.com:8443). The default value is blank.Use `pf.admin.baseurl` instead of `pf.admin.hostname`, which has been deprecated. If `run.properties` defines both, PingFederate ignores `pf.admin.hostname`. But if `run.properties` defines only `pf.admin.hostname`, PingFederate constructs the URL the same way it does in versions of PingFederate earlier than 10.3. | | `pf.console.bind.address` | Defines the IP address over which the PingFederate administrative console communicates. Use for deployments where multiple network interfaces are installed on the machine running PingFederate. | | `pf.console.title` | Defines the browser window or tab title for the administrative console. It makes separate instances easily identifiable. | | `pf.console.environment` | Defines the name of the PingFederate environment that will be displayed in the administrative console. It makes separate environments easily identifiable. | | `pf.console.show.background.images` | Enables or disables the background images on the dashboard of the administrative console. The images are enabled by default. | | `pf.pingone.admin.url.region` | These properties set the URL of the PingOne unified admin icon in the PingFederate administrative console. This property should be set based on the region of your PingOne organization.Choose one of the following region-specific values for your environment.- com console.pingone.com - eu console.pingone.eu - asia console.pingone.asia The asia region is deprecated. Use the australia region instead. - ca console.pingone.ca - com.au console.pingone.com.au | | `pf.pingone.admin.url.environment.id` | Defines the ID of your PingOne organization's environment. | | `pf.console.session.timeout` | Defines the length of time in minutes until an inactive administrative console times out. The minimum setting is 1 minute, and maximum is 8 hours (480 minutes). Default is `30` minutes. | | `pf.console.login.mode` | Indicates whether more than one administrative user may access the administrative console at one time. Supported values are `Single` or `Multiple`. The default value is `Multiple`. Setting this property to Single can prevent conflicts caused by multiple admins overwriting the same confgiruations. Learn more in Admin console best practices. | | `pf.console.authentication` | Indicates whether administrators sign on to PingFederate using credentials managed internally by PingFederate or externally by other systems. | | `pf.admin.api.authentication` | Defines the authentication method of the PingFederate administrative API. Valid values are:- `none` - No direct login method is available. - `native` - Internal password file authentication. - `LDAP` - External LDAP authentication. - `cert` - X509 certificate-based authentication. - `RADIUS` - External RADIUS authentication. - `OAuth2` - External or internal OAuth2 authorization. - `JWT` - JSON Web Token authentication, Learn more in [Enabling JWT authorization](../developers_reference_guide/pf_enabling_jwt_authorization.html)The default value is `native`. The values are case-insensitive.You can also configure PingFederate to support both `OAuth2` authorization and a basic authentication method by specifying two values separated with a comma. For example, specify `pf.admin.api.authentication=OAuth2,LDAP`. The basic authentication methods are `native`, `LDAP`, and `RADIUS`. Supporting two authentication methods is helpful when you want to change applications from one method to another. When configuring support for two authentication methods, consider the following: The order of the values isn't important. PingFederate uses the HTTP Authorization request header to determine the authorization scheme. A request can contain only one authorization header. You cannot combine the none and cert values with other values. If you specify an invalid value or more than two values, PingFederate will fail on startup. You should only allow multiple authentication sources while migrating from one source to another because using multiple authentication sources simultaneously increases security risks. For administrative API authentication, after migration, you should use OAuth2 for the authentication source. | | `ldap.properties.file` | When Lightweight Directory Access Protocol (LDAP) *(tooltip: \
\

An open, cross platform protocol used for interacting with directory services.\

\
)* administrative console authentication is enabled, indicates the name of the file containing configuration properties. | | `cert.properties.file` | When certificate-based console authentication is enabled, indicates the name of the file containing configuration properties. | | `radius.properties.file` | When RADIUS-based console authentication is enabled, indicates the name of the file containing configuration properties. | | `oidc.properties.file` | When OIDC administrative-console authentication is enabled, indicates the name of the file containing configuration properties. | | `oauth2.properties.file` | When OAuth 2.0 administrative-API authentication is enabled, this property indicates the name of the file containing configuration properties. | ## Runtime server properties | Property | Description | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pf.http.port` | Defines the port on which PingFederate listens for unencrypted HTTP traffic at runtime. For security reasons, this port is disabled by default. This port should remain disabled in production if your deployment configuration directly exposes the PingFederate server to the internet. | | `pf.https.port` | Defines the port on which PingFederate listens for encrypted HTTPS (SSL/TLS) traffic. The default value is `9031`. | | `pf.secondary.https.port` | Defines a secondary HTTPS port that can be used for mutual SSL/TLS (client X.509 certificate) authentication for both end users and protocol requests (Security Assertion Markup Language (SAML) *(tooltip: \
\

A standard, XML-based, message-exchange framework enabling the secure transmittal of authentication tokens and other user attributes across domains.\

\
)*, WS-Trust, and OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)*). Set its value to the desired inbound listening TCP port. A value of `-1` disables this feature. If you are using client X.509 certificates for either WS-Trust Security Token Service (STS) authentication or for SAML back-channel authentication, you must use this port, or a similarly configured new listener, with either the WantClientAuth or NeedClientAuth parameter set to true in the jetty-runtime.xml file. You can find more information in the note at the end of this table. | | `pf.engine.bind.address` | Defines the IP address over which the PingFederate server communicates with partner federation gateways. Use for deployments where multiple network interfaces are installed on the machine running PingFederate. | | `pf.monitor.bind.address` | Defines the IP address over which Java Management Extensions (JMX) *(tooltip: \
\

Java technology that provides tools for managing and monitoring applications, devices, system objects, and service-oriented networks.\

\
)* communicate with PingFederate. Use for deployments where multiple network interfaces are installed on the machine running PingFederate. | | `pf.engine.prefer_ipv4` | Defines the protocol to be used by PingFederate. `True`, the default, enables use of IPv4 only. `False` enables use of both IPv4 and IPv6. | | `pf.runtime.context.path` | Allows customization of the server path for PingFederate endpoints. If this property is changed, the path must also be added to the base URL for your PingFederate environment. Base URL is defined on System > Server > Protocol Settings > Federation Info.The `pf.runtime.context.path` property is also compatible with virtual host names. Unlike the base URL configuration, the virtual host names configuration does not require any context path. Virtual host names are defined on **System > Server > Virtual Host Names**.For example, suppose the base URL is https\://www\.example.com:9031 and the virtual host names are www\.example.org and www\.example.info. To configure the `pf.runtime.context.path` property value as `/sso`, you must update the base URL to https\://www\.example.com:9031/sso but leave the virtual host names as they are. After configuring, you can access the runtime server at the following endpoints:- Base URL * https\://www\.example.com:9031/sso - Virtual host names * https\://www\.example.org:9031/sso * https\://www\.example.info:9031/sso | | `pf.log.dir` | Network path to the output location of log files. The default is `>/pingfederate/log`. | | `pf.hsm.mode` | Enables or disables (the default) a FIPS-compliance Hardware Security Module (HSM). | | `pf.hsm.hybrid` | Enables or disables the HSM hybrid mode. Applicable only when the `pf.hsm.mode` property is configured to use an HSM.When set to `true`, keys and certificates can be stored on either the HSM or the local trust store. When set to `false`, the default setting, keys and certificates are stored on the HSM when applicable.The HSM hybrid mode allows an organization to move the storage of keys and certificates from the local trust store to an HSM over time without deploying a new PingFederate installation and mirroring the setup. For more information, see [Transitioning to an HSM](pf_transition_to_hsm.html). | | `org.bouncycastle.fips.approved_only` | When the `pf.hsm.hybrid` property is set to `true`, this property can be set to `true` or `false`. In this case, the recommended setting is `false`.If `pf.hsm.hybrid` is set to `false`, this property must be set to `true`.In FIPS-approved mode only, the module will provide approved algorithms only. For more information, see [Algorithms & Key Types](https://www.bouncycastle.org/documentation/specification_interoperability/#algorithms-and-key-types) in the Bouncy Castle documentation.The default setting is `true`. | | `pf.provisioner.mode` | Enables or disables (the default) outbound provisioning. Also used to enable provisioning failover. | | `pf.log.eventdetail` | Enables or disables (the default) detailed event logging for actions performed by administrative console users. | | `pf.heartbeat.system.monitoring` | Enables or disables (the default) the heartbeat endpoint, `/pf/heartbeat.ping`, to return detailed system monitoring information through a customizable Velocity template file . Learn more in [Customizing the heartbeat message](pf_customize_heartbeat_message.html).When set to `false`, the `/pf/heartbeat.ping` endpoint returns OK.When set to `true`, the `/pf/heartbeat.ping` endpoint returns all available stats. | | `pf.runtime.http.maxRequestBodySize` | Sets the maximum size in bytes of the request body for inbound runtime requests. Default value is `200000` if not specified. | ## Deployment properties | Property | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Operational ModeLearn more in [Deploying cluster servers](../server_clustering_guide/pf_deploying_cluster_servers.html). | | | `pf.operational.mode` | Designates the operational mode of the runtime server from a clustering standpoint. Valid values are `STANDALONE`, `CLUSTERED_CONSOLE`, or `CLUSTERED_ENGINE`. | | `pf.cluster.node.index` | Integer that assigns the clustered node index ID. Only applies when operational mode is not STANDALONE. | | `pf.cluster.auth.pwd` | Sets the password that each clustered node must use to authenticate when joining the cluster. | | `pf.cluster.encrypt` | Whether to encrypt network traffic sent between clustered nodes. Values are `true` or `false`. | | `pf.cluster.encryption.keysize` | Specifies the key size to use with the AES encryption algorithm when encrypting communication between cluster nodes. | | `pf.cluster.bind.address` `pf.cluster.bind.port` `pf.cluster.failure.detection.bind.port` | Used to specify the IP address for communication between cluster nodes. Leave as `NON_LOOPBACK` to allow PingFederate to choose an available IP address. | | `pf.cluster.transport.protocol` `pf.cluster.mcast.group.address` `pf.cluster.mcast.group.port` | Used to designate the transport protocol for communications between clustered nodes. | | `pf.cluster.tcp.discovery.initial.hosts` | When TCP is the transport protocol, this property specifies a comma-separated list of hosts in the cluster | | `pf.cluster.adaptive` | Enables or disables adaptive clustering. Learn more in [Adaptive clustering](../server_clustering_guide/pf_adaptiv_cluster.html). | | `pf.cluster.diagnostics.enabled` | Enables or disables JGroups cluster diagnostics. | | `pf.cluster.diagnostics.addr` `pf.cluster.diagnostics.port` | Designates the IP address and port over which PingFederate communicates JGroups diagnostic information. | | `pf.cluster.thread.pool.max.threads` | The maximum number of threads in the JGroups thread pool responsible for processing JGroups remote procedure calls (RPCs). | | `node.tags` | Defines tags associated with this node. Tags are space-separated. | | Hardware Security Module Mode | | | `pf.hsm.mode` | Enables or disables a FIPS-compliance hardware security module (HSM) *(tooltip: \
\

A dedicated cryptographic processor designed to manage and protect digital keys. HSMs act as trust anchors that protect the cryptographic key lifecycle by securely managing, processing, and storing cryptographic keys inside a hardened, tamper-resistant device.\

\
)*. Learn more about HSMs in [Supported hardware security modules](../getting_started_with_pingfederate/pf_supported_hardware_security_modules.html). | | Hardware Security Module Hybrid Mode | | | `pf.hsm.hybrid` | Enables or disables the HSM hybrid mode. Applicable only when the `pf.hsm.mode` property is configured to use an HSM.When set to `true`, keys and certificates can be stored on either the HSM or the local trust store. When set to `false`, the default setting, keys and certificates are stored on the HSM when applicable.The HSM hybrid mode allows an organization to move the storage of keys and certificates from the local trust store to an HSM over time without deploying a new PingFederate installation and mirroring the setup. Learn more in [Transitioning to an HSM](pf_transition_to_hsm.html). | | `pf.fips.additional.allowed.providers` | Used to allow additional providers when operating in BCFIPS mode. | | Redis data storageLearn more in [Storing PingFederate data with Redis](pf_storing_pf_data_redis.html). | | | `pf.redis.mode` | Global setting for PingFederate services that can store data in Redis. A value of `ON` enables all Redis-capable services. A value of `OFF` allows you to configure services individually. Default value is `OFF`. | | Outbound Provisioner PropertiesLearn more in [Deploying cluster servers](../server_clustering_guide/pf_deploying_cluster_servers.html). | | | `pf.provisioner.mode` | Enables or disables (the default) outbound provisioning. Also used to enable provisioning failover. | | `provisioner.node.id` | Integer that designates the ID of this node in failover mode. Only one server can actively handle provisioning at one time. Lower numbers have higher priority. If this property is left blank, the cluster node index is used as the provisioner node ID. | | `provisioner.failover.grace.period` | The grace period, in seconds after which a node is considered dead, and failover occurs. This value should be larger than the synchronization frequency.Learn more in [Configuring outbound provisioning settings](help_protocolsettingstasklet_saasglobalprovisioningsettingsstate.html). | | Jetty Customization Properties | | | `jetty51.encode.wildcard.session.cookies` | When `true`, PingFederate encodes cookie values for all cookies with names that end with "SESSION". For example, `SMSESSION`. | | `jetty51.encode.cookies` | A comma-separated list of cookie names whose values PingFederate encodes when the cookie is set. | | `cookies.skip.quoting` | A comma-separated list of cookie names whose values shouldn't be wrapped in quotes when special characters are detected. | | SSL Session Cache | | | `javax.net.ssl.sessionCacheSize` | Sets the size of the SSL session cache used to store SSL Session objects. A value of `0` means there is no limit. | | HTTP Forward Proxy SettingsLearn more in [Configuring forward proxy server settings](pf_configure_forward_proxy_server_settings.html). | | | `http.proxyHost` and `http.proxyPort` | Specifies the hostname, or the IP address, and the port number of the forward proxy server that HTTP traffic originating from PingFederate must go through. | | `https.proxyHost` and `https.proxyPort` | Specifies the hostname, or the IP address, and the port number of the forward proxy server that HTTPS traffic originating from PingFederate must go through. | | `http.nonProxyHosts` | Specifies one or more destinations where PingFederate is not required to proxy its HTTP and HTTPS traffic through the forward proxy server configured by the `http[s].proxyHost` and `http[s].proxyPort` properties. This property supports multiple values separated by the pipe character (`\|`) and the wildcard character (`*`) for pattern matching. See the example below.`*.example.com\|localhost` | | `jdk.http.auth.proxying.disabledSchemes` `jdk.http.auth.tunneling.disabledSchemes` | Used to disable proxy authentication schemes. For security purposes, basic authentication is disabled by default. | | `org.apache.xml.security.ignoreLineBreaks` | Determines whether PingFederate omits line breaks in XML digital signatures. If omitted, this setting defaults to `false`. Set this property to `true` for improved interoperability with Microsoft products. | | `sun.net.client.defaultConnectTimeout` | Determines the default connect timeout for outbound java.net.URL connections in milliseconds.The default setting is 10000. | | `sun.net.client.defaultReadTimeout` | Determines the default read timeout for outbound java.net.URL connections in milliseconds.The default setting is 10000. | | TLS Protocol Settings | | | `pf.tls.client.protocols` | Controls the allowed TLS protocols for outbound HTTPS connections. | | `pf.tls.runtime.server.protocols` | Controls the allowed TLS protocols for runtime inbound HTTPS connections. | | `pf.tls.admin.server.protocols` | Controls the allowed TLS protocls for admin console inbound HTTPS connections. | | HTTP Server Thread Pool SettingsLearn more in [Tuning the server thread pool](../performance_tuning_guide/pf_tuning_server_thread_pool.html). | | | `pf.admin.threads.min` | The minimum number of threads in HTTP server thread pools for the administrative console. The default value is `1`. | | `pf.admin.threads.max` | The maximum number of threads in HTTP server thread pools for the administrative console. The default value is `10`. | | `pf.runtime.threads.min` | The minimum number of threads in HTTP server thread pools for the runtime engine nodes. The default value is `10`. | | `pf.runtime.threads.max` | The maximum number of threads in HTTP server thread pools for the runtime engine nodes. The default value is `200`. | | HTTP Connector Queue Size SettingsLearn more in [Tuning the acceptor queue size](../performance_tuning_guide/pf_tuning_acceptor_queue_size.html). | | | `pf.admin.acceptQueueSize` | The queue size of the HTTP connector for the administrative console. The default value is `512`. | | `pf.runtime.acceptQueueSize` | The queue size of the HTTP connector for the runtime engine nodes. The default value is `512`. | | HTTP Server Request Handling Settings | | | `pf.admin.output.buffer.size` `pf.runtime.output.buffer.size` | The output buffer size in bytes. | | `pf.admin.request.header.size` `pf.runtime.request.header.size` | The request header size in bytes. | | `pf.admin.response.header.size` `pf.runtime.response.header.size` | The response header buffer size in bytes. | | `pf.admin.delayDispatchUntilContent` `pf.runtime.delayDispatchUntilContent` | Enable delayed dispatch optimization. | | `pf.admin.http.idleTimeout` `pf.runtime.http.idleTimeout` | The idle time before an HTTP request expires. | | `pf.admin.ssl.selectors` `pf.admin.ssl.acceptors` `pf.runtime.ssl.selectors` `pf.runtime.http.acceptors` `pf.runtime.http.selectors` | Controls the number and priority of acceptors and selectors. | | `pf.admin.http.compliance` `pf.runtime.http.compliance` | (Optional) Uncomment to set compliance modes for Jetty HTTP parsing and handling. | | HTTP Server Runtime Request Log Settings | | | `jetty.runtime.requestlog.format` | Controls the output format of the runtime HTTP request log. | | `jetty.runtime.requestlog.ignorePaths` | This path can optionally include a comma-separated list of request paths to ignore. Each path must begin with a `/`, and it can use the `*` wildcard. | | HTTP Server Admin Request Log Settings | | | `jetty.admin.requestlog.format` | Controls the output format of the admin console HTTP request log. | | Perform data upgrade on startup | | | `pf.data.upgrade.on.startup` | Whether PingFederate performs a data upgrade on startup. Default value is `true`. Data upgrade is enabled if the property is missing. | | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Additional configuration of the listener ports, including adding new listeners, is available through the `/pingfederate/etc/jetty-runtime.xml` file. For example, options include the `WantClientAuth` and `NeedClientAuth` flags, which indicate that a client certificate is either requested or required, respectively, for mutual SSL/TLS. For the pre-configured SSL secondary port, the `WantClientAuth` parameter is set to `true` and the `NeedClientAuth` parameter is set to `false` by default. |