PingFederate Server

Configuring PingFederate properties

The default administrative console and runtime behavior of PingFederate is controlled in part by configuration properties set in the <pf_install>/pingfederate/bin/run.properties file.

Steps

  1. Edit the <pf_install>/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.

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) responses. The administrative node also uses it for the redirect URL it sends to an OpenID Provider (OP) for administrator OpenID Connect (OIDC) (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.

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) 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), WS-Trust, and OAuth). 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) 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 <pf_install>>/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.

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

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 Mode

Learn more in Deploying cluster servers.

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.

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.

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). Learn more about HSMs in Supported hardware security modules.

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.fips.additional.allowed.providers

Used to allow additional providers when operating in BCFIPS mode.

Outbound Provisioner Properties

Learn more in Deploying cluster servers.

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.

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 Settings

Learn more in Configuring forward proxy server settings.

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 Settings

Learn more in Tuning the server thread pool.

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 Settings

Learn more in Tuning the acceptor queue size.

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

Additional configuration of the listener ports, including adding new listeners, is available through the <pf_install>/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.