PingFederate Server

Enabling dynamic discovery for clustering

You can enable and configure dynamic discovery setup for clustered PingFederate deployments by editing the run.properties and jgroups.properties files.

Before you begin

If your PingFederate deployment has cluster discovery settings in the tcp.xml file, migrate those settings to the jgroups.properties file. For more information, see Migrating cluster discovery settings.

About this task

If you enable dynamic discovery, you must manually configure or synchronize the dynamic discovery properties in the run.properties file and jgroups.properties file on each node in the cluster. The files are not synchronized automatically across the nodes in a cluster, nor is it part of the replicate configuration process.

Whenever you add a node to the cluster, perform the following procedure on the new node.

To enable and configure dynamic discovery for clustering:

Steps

  1. Configure the cluster protocol properties in the <pf_install>/pingfederate/bin/run.properties file.

    See the file’s inline comments and the following table.

    Cluster protocol properties in run.properties
    Property Description

    pf.operational.mode

    Configure the operational mode of the PingFederate node. The value CLUSTERED_CONSOLE denotes an administrative console node. The value CLUSTERED_ENGINE denotes a runtime engine node.

    A PingFederate cluster has only one administrative console node. When you scale your PingFederate infrastructure, set the pf.operational.mode property value to CLUSTERED_ENGINE to deploy additional PingFederate runtime engine nodes.

    pf.cluster.tcp.discovery.initial.hosts

    Remove any configured value. No IP addresses are required here.

    pf.cluster.transport.protocol

    Set the value to tcp.

    pf.cluster.*

    See the inline comments to configure the rest of the pf.cluster.* property values.

  2. Configure dynamic discovery properties in the <pf_install>/pingfederate/bin/jgroups.properties file.

    See the file’s inline comments and the following tables.

    NATIVE_S3_PING properties in jgroups.properties
    Property Description

    pf.cluster.NATIVE_S3_PING.region_name

    The name of the region in which discovery should be attempted.

    If no region is specified, only nodes in the same region as this node can be discovered.

    pf.cluster.NATIVE_S3_PING.bucket_name

    The name of the bucket in your Amazon S3 environment.

    For information about buckets, see the Create a bucket documentation from Amazon.

    pf.cluster.NATIVE_S3_PING.remove_all_data_on_view_change

    When set to true (the default), JGroups cleans up data when it detects a view change.

    For more information, see .jgroups.org/manual4/index.html//[].

    pf.cluster.NATIVE_S3_PING.write_data_on_find

    Default value of true resolves the issue where subclusters could fail to merge after a network partition.
    DNS_PING properties in jgroups.properties
    Property Description

    pf.cluster.DNS_PING.dns_query

    A DNS query to the DNS Server that obtains information about the cluster members. For example, jgroups-dns-ping.myproject.svc.cluster.local.

    For more information, see .jgroups.org/manual4/index.html//[].
    AWS_PING properties in jgroups.properties
    Property Description

    pf.cluster.AWS_PING.port_number

    The port on which PingFederate listens for cluster communication.

    The default value is ${pf.cluster.bind.port}, which pulls the value defined by the pf.cluster.bind.port property in the <pf_install>/pingfederate/bin/run.properties file.

    pf.cluster.AWS_PING.port_range

    The number of additional ports that PingFederate can probe when attempting to connect to other nodes in the event that it fails to connect to the port specified by the port_number property.

    For example if the port_number property is 7600, a port_range property value of 0 means PingFederate will only try to connect at port 7600. If the port_range property value is set to 2, PingFederate will make up to two additional attempts, with the port value increasing by one each time. For example, if PingFederate fails to connect at port 7600, it will try at port 7601. If it fails again, it will try at port 7602.

    The default value is 0.

    pf.cluster.AWS_PING.regions

    A comma separated list of EC2 regions in which PingFederate will attempt discovery.

    If no regions are specified, only nodes in the same region as this node can be discovered. List all regions where you have nodes running.

    For information about regions, see the AWS documentation on Regions, Availability Zones, and Local Zones.

    pf.cluster.AWS_PING.tags

    A comma separated list of EC2 tag names.

    When specified, only EC2 instances that have been assigned with the specified tags can be discovered. If multiple tags are specified, only EC2 instances that have been assigned with all tags can be discovered.

    For information about tags, see the documentation from Amazon (docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html).

    pf.cluster.AWS_PING.filters

    A semi-colon separated list of key value pairs of system metadata.

    When specified, only EC2 instances that match the specified filters can be discovered. If multiple filters are specified, only EC2 instances that match all filters can be discovered.

    Note that you can enter a comma separated list of values for each filter. In this case, a filter is considered a match if one of the values is satisfied. For example, if you enter: filters="instance-type=t2.small,t2.medium;architecture=x86_64", then only EC2 instances that have an instance-type of either t2.small or t2.medium and also an architecture of x86_64 can be discovered.

    For information about filters, see the describe-instances documentation from Amazon.

    pf.cluster.AWS_PING.access_key and pf.cluster.AWS_PING.secret_key

    The access key and its secret key for the purpose of querying AWS for EC2 instances.

    Applicable and required only if permissions to ec2:Describe* actions are associated with the access key.

    Keys can be encrypted using the obfuscate utility (obfuscate.bat for Windows or obfuscate.sh for Linux), located in the <pf_install>/pingfederate/bin directory

    pf.cluster.AWS_PING.log_aws_error_messages

    When set to true (the default), error messages received from AWS are logged to the server log.
    SWIFT_PING properties in jgroups.properties
    Property Description

    pf.cluster.SWIFT_PING.auth_type

    The authentication type.

    pf.cluster.SWIFT_PING.auth_url

    The authentication URL.

    pf.cluster.SWIFT_PING.username and pf.cluster.SWIFT_PING.password

    The security credentials.

    Password can be encrypted using the obfuscate utility (obfuscate.bat for Windows or obfuscate.sh for Linux), located in the <pf_install>/pingfederate/bin directory

    pf.cluster.SWIFT_PING.tenant

    The name of your OpenStack Keystone tenant.

    pf.cluster.SWIFT_PING.container

    The name of the root container.

    For more information about each of the SWIFT_PING properties, see .org/manual/index.html//[jgroups.org/manual4/index.html#_swift_ping].

    pf.cluster.SWIFT_PING.remove_all_data_on_view_change

    When set to true (the default), JGroups cleans up data when it detects a view change.

    For more information, see .org/manual/index.html//[jgroups.org/manual4/index.html#FILE_PING].

    To use a discovery protocol that PingFederate does not officially support, set the discovery protocol and class in jgroups.properties:

    pf.cluster.discovery.protocol={discovery protocol}
pf.cluster.discovery.class={fully qualified class name}

    For example, to use a discovery protocol called CUSTOM, add the following lines:

    pf.cluster.discovery.protocol=CUSTOM
pf.cluster.discovery.class=org.jgroups.custom.discovery

    To add a custom attribute to a protocol, use the following syntax in jgroups.properties:

    pf.cluster.{discovery protocol}.{attribute name}={attribute value}

    For example, to add a custom attribute called bucket_prefix to the NATIVE_S3_PING protocol and assign it the value jgroups, add the following line:

    pf.cluster.NATIVE_S3_PING.bucket_prefix=jgroups

  3. Start or restart PingFederate.

  4. Repeat these steps for each node in the cluster.