The reference token data model supports both adaptive clustering and directed clustering. For adaptive clustering, PingFederate shares token information across a replica set. If region identifiers are defined, PingFederate shares token information across replica sets in multiple regions. You can optionally override this default behavior in the configuration file for adaptive clustering. For directed clustering, PingFederate shares token information among all engine nodes, despite any state server or subcluster setup.

  1. Go to Applications > OAuth > Access Token Management and click Create New Instance.
  2. On the Instance Configuration window, modify the default values as needed.

    The following table describes each field.

    Field Description
    Token Length


    The number of characters that PingFederate uses to define the token reference. Increasing the length enhances token security.

    The default value is 28 characters. The minimum and maximum values are 22 and 256, respectively.

    Token Lifetime


    The amount of time in minutes that an access token is considered valid.

    The default value is 120 minutes.

    Lifetime Extension Policy Indicates whether PingFederate should reset the lifetime of an access token each time the token is validated, subject to the values defined in the Maximum Token Lifetime and Lifetime Extension Threshold Percentage fields.

    The options are:

    • No Extension
    • Tokens Not Backed by Persistent Access Grants (Transient Grants)
    • All Tokens

    The default selection is No Extension.

    Maximum Token Lifetime Defines an absolute maximum token lifetime for use with the Lifetime Extension Policy setting, in minutes. When configured, the lifetime of access tokens can be extended but not beyond the configured value. Any value, if specified, must be greater than or equal to the value specified in the Token Lifetime field.

    This optional field has no default value.

    Lifetime Extension Threshold Percentage


    When PingFederate is deployed in a cluster and token-lifetime extension is enabled, there must be a cluster-group remote procedure call (RPC) to extend the life of a token.

    To limit RPC overhead, this setting suspends the calls until the remaining time is less than the chosen value, as a percentage of token lifetime. For example, if the token lifetime is 60 minutes and the Lifetime Extension Threshold Percentage value is 30 percent, the lifetime will not be extended until the remaining time is less than 18 minutes. This option can drastically reduce RPC traffic between nodes, while still supporting a lifetime extension policy.

    The default value is 30 percent.

    Advanced Fields
    Mode for Synchronous RPC Synchronous RPC calls occur when a node receives a verification request for a token it does not recognize, and for token issuance.

    When Majority of Nodes is selected, the server waits for the majority of recipients to respond. It also eliminates the need for a complete state synchronization at startup.

    When All Nodes is selected, the server waits for all recipients to respond.

    The default selection is Majority of Nodes.

    RPC Timeout


    The timeout value between cluster nodes during synchronous communication, in milliseconds. The recommended value ranges from 100 milliseconds to 1000, or 1 second.

    The default value is 500 milliseconds.

    Expand Scope Groups Determines whether to expand scope groups into their corresponding scopes in the access token contents and introspection response.

    This check box is not selected by default.