PingFederate Server

Transient grants and persistent grants

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

Transient grants

Transient grants are valid only for the lifetime of their respective access tokens. Transient authorizations include those obtained by OAuth clients in the following manners:

  • Grants obtained by using the 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. Persistent authorizations include those obtained by OAuth clients in the following ways:

  • Grants obtained or updated 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, such as IdP adapter instances or IdP connections, or password credential validator (PCV) instances to the access tokens, directly or through persistent grant-extended attributes, storing these attributes from authentication sources and their values along with the persistent grants maintains them for reuse 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, runtime procedures obtain attribute values for each token request, but persistent grants do not store with attributes or their values.

Persistent grant lifetime and maintenance

Persistent grants and any associated attributes and their values remain valid until the grants expire or until PingFederate explicitly revokes or cleans them up.

Grants persist without any expiration information. Grants also persist with an idle timeout window, a maximum lifetime, or both. If you configure an idle timeout value, the idle timeout window slides when a persistent grant updates. When you have an idle timeout value configured without a maximum lifetime, persistent grants remain valid until they expire because of inactivity or until the grant storage revokes or removes them. When you have an idle timeout value configured with a maximum lifetime, persistent grants remain valid until they expire due to inactivity or lifetime expiration or until the grant storage removes them.

Grants can persist without expiration information, or with expiration depending on your PingFederate configuration. You should set a maximum lifetime for a grant.

Grants can persist with an idle timeout window, a maximum lifetime, or both. If you configure an idle timeout value, the idle timeout window restarts when a persistent grant updates.

When a persistent grant has an idle timeout value, but no maximum lifetime, the grant remains valid and will never expire or be purged, even if there is no activity. These grants must be explicitly revoked.

When a persistent grant has both an idle timeout and maximum lifetime configured, the grant remains valid until it expires due to inactivity, or until its lifetime expires. Inactive grants will be purged by the grant storage. It can also be explicitly revoked.

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. Depending on the datastore being used, the removal of expired grants can be done by the datastore itself. You should configure the datastore to purge expired grants whenever possible. Optionally, PingFederate caps 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. For more information, see OAuth grant datastores.

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

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.

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