Key rotation policies
Key rotation is the process of regularly generating a new public-and-private key pair to secure cryptographic operations. Periodic key rotation reduces risk by limiting the amount of data protected by a single key.
PingOne uses key rotation to automatically generate new keys based on the key rotation policy (KRP). The default rotation is 90 days, which exceeds industry best practices. New applications automatically use a key from the default KRP to sign access tokens and ID tokens. For applications not using the default KRP, you can update the application to the default KRP. Learn more in Updating the key rotation policy for an application.
|
Beginning March 2, 2027, PingOne will only use signing keys from KRPs to sign ID tokens and access tokens, regardless of whether the audience for the access token is PingOne APIs or custom resources. Any OpenID Connect (OIDC)-based applications not using the KRP will automatically update to use the default KRP on this date. |
Application types
KRPs apply to the following PingOne application types:
-
OIDC
-
Native
-
Single page
-
Worker
-
Device authorization
-
Service
Non-worker OIDC-based applications
You can update the application to use the default KRP. Learn more in Updating the key rotation policy for an application.
Worker applications
You can select the signing key for non-interactive and interactive worker applications to use. PingOne uses the KRP to sign tokens as follows:
Non-interactive worker
If the application uses the client credentials grant type, you can select the signing key for the application to use. If you set the non-interactive worker application to use a KRP, PingOne uses the selected KRP to sign API access tokens. Learn more in Editing an application - Worker.
Interactive worker
If the application uses an interactive grant type, such as authorization code, you can select the signing key for the application to use. If you set the interactive worker application to use a KRP, PingOne uses the selected KRP to sign API access tokens and ID tokens. Learn more in Editing an application - Worker.
Using the admin console
You can manage signing keys for applications in the PingOne admin console as follows:
-
Update the signing key for applications not using the default KRP.
-
For worker applications, select which signing key PingOne should use. Learn more in Editing an application - Worker.
Using the API
You can review and fine-tune KRPs using the PingOne API. Learn more in Key rotation policies in the PingOne Platform API Reference.
Updating cached and hard-coded signing keys
If your applications have the PingOne signing key cached or hard-coded, you must update them using the guidance in the following sections.
Beginning March 2, 2027, PingOne will only use signing keys from KRPs, and any OIDC-based applications not using the KRP will automatically update to use the default KRP on this date.
Applications that use PingOne access tokens and ID tokens must be able to handle signing key changes when PingOne rotates to a new key. To handle these changes properly, it’s best practice to update applications to use the PingOne KRP as the signing key.
Cached signing keys
Set the cache duration to a time period shorter than the KRP rotation period. Use the following examples as best practice:
-
If the KRP uses the default rotation period of 90 days, set the cache duration to 89 days or fewer.
-
If the KRP rotation period is set to a shorter period through the management API, such as 45 days, set the cache duration to 44 days or fewer.
-
If the KRP is set to the minimum rotation period of 30 days through the management API, set the cache duration to 29 days or fewer.
Hard-coded signing keys
For applications hard-coded to use the PingOne signing key indefinitely, update the application to retrieve signing keys from the PingOne JSON Web Key Set (JWKS) endpoint.
You can alternatively update your application to cache signing keys following the best practices in Cached signing keys.
To find the JWKS endpoint URL:
- PingOne domain
-
Go to
https://auth.pingone.<region>/as/.well-known/openid-configurationand retrieve the value ofjwks_uri. - Custom domain
-
Go to
https://<customDomain>/as/.well-known/openid-configurationand retrieve the value ofjwks_uri.
Learn more in Domains.