There are two types of OAuth authorization grants, namely transient grants and persistent grants.

Transient grants

Transient grants are valid only for the lifetime of their respective access tokens. Authorizations obtained by OAuth clients in the following manners are considered transient.

  • Grants obtained by using Authorization Code, Resource Owner Credentials, or Device Authorization grant type, without the Refresh Token grant type.
  • Grants obtained by using Client Credential, JWT Bearer, SAML 2.0 Bearer Assertion, or Token Exchange grant type.

Transient grants are not preserved.

Persistent grants

Persistent grants typically bear a longer lifetime than their respective access tokens do. Authorization grants obtained by OAuth clients in the following manners are considered persistent.

  • Grants obtained or updated by using the Authorization Code, Resource Owner Credentials, or Device Authorization grant type, in conjunction with the Refresh Token grant type.

    If the use cases involve mapping attributes from authentication sources (IdP adapter instances or IdP connections) or Password Credential Validator (PCV) instances to the access tokens (directly or through persistent grant extended attributes), such attributes and their values are stored along with the persistent grants so that they can be reused when clients subsequently present refresh tokens for new access tokens.

  • Grants obtained or updated by using the Implicit grant type, for which PingFederate is configured to reuse existing persistent grants.

    If the use cases involve mapping attributes from authentication sources or PCV instances to the access tokens (directly or through persistent grant extended attributes), attribute values are obtained at runtime for each token request. No attributes or their values are stored with the persistent grants.

Persistent grant lifetime and maintenance

Persistent grants (and the associated attributes and their values, if any) remain valid until the grants expired or are explicitly revoked or cleaned up.

Grants can persist without any expiration information. Grants can also persist with an idle timeout window, a maximum lifetime, or both. If an idle timeout value is configured, the idle timeout window slides when a persistent grant is updated. When an idle timeout value is configured without a maximum lifetime, persistent grants remain valid until they expire due to inactivity, or are revoked or removed. When an idle timeout value is configured with a maximum lifetime, persistent grants remain valid until they expire (due to inactivity or lifetime expiration) or are removed from the grant storage.

PingFederate removes expired grants and the associated attributes from the grant datastore once a day. The frequency and the size of the cleanup batch are configurable. Optionally, PingFederate can put a cap on the number of persistent grants on a basis of the combination of user, client, and grant type.

Persistent grant storage

Support for persistent grants requires the use of a database server or a directory server for long-term storage. PingFederate also supports other storage solutions through the PingFederate SDK.

PingFederate uses a built-in HSQLDB database as its grant datastore after the initial setup.

CAUTION:

We strongly recommend that you use the built-in HSQLDB only for trial or training environments. For testing and production environments, always use a secured external storage solution for proper functioning in a clustered environment. For more information, see Defining an OAuth grant datastore.

Testing involving HSQLDB is not a valid test. In both testing and production, it might cause various problems due to its limitations and HSQLDB involved cases are not supported by PingIdentity.