PingAccess

Configuring static signing keys

Configure static keys for use in private key JSON Web Token (JWT) OpenID Connect (OIDC) code flows instead of dynamically rotating keys to sign tokens as necessary.

Before you begin

About this task

Static and dynamically rotating keys are used to sign self-contained access tokens, ID tokens, and JWTs for client authentication and OIDC request objects.

You must make changes in both PingAccess and the token provider to modify your signing key configuration. Make these changes as soon as possible to reduce potential disruptions.
Dynamically rotating keys (default)

PingAccess generates and rotates keys automatically for OAuth and OIDC.

PingAccess uses the Signing Algorithm configured on the OAuth Key Management page for dynamic key rotation unless you’ve configured the signing algorithm on your web session. A signing algorithm configured on a web session takes priority over one configured on the OAuth Key Management page.
Static keys

Manually configure and rotate keys for OAuth and OIDC to gain more control over key rotation.

Static keys are currently only available for use with private key JWT client authentication for protected web apps. JWT identity mappings use the keys generated for /pa/authtoken/JWKS instead.

To configure static signing keys:

Steps

  1. In PingAccess, go to Security > Key Pairs > Static OAuth/OIDC Keys.

  2. Select the Enable Static Keys checkbox to use static keys for OAuth and OpenID Connect.

    This checkbox is cleared by default.

  3. In the Signing Keys section, fill out the relevant information for your static key configuration.

    The Active and Previous lists only display signing keys you’ve configured on the Key Pairs page that match the listed key type.

    1. For the RSA using SHA-256 key type, select a signing key in the Active list.

      There are no default selections for the signing key lists. If you don’t find the signing key you want, go to the Key Pairs page and generate or import the desired type of key pair.

    2. (Optional) In the Previous list, select a signing key you previously selected in the Active list if you still want the token provider to validate it.

      If you select a certificate in the Previous list, that certificate will appear in the JWT, but only the Active certificate is actually used in a JWT signing flow.

    3. (Optional) Repeat steps 3a and 3b for each additional key type you want to use.

    4. (Optional) For any key type for which you’ve selected an Active signing key, select the Publish Certificate checkbox to publish the certificates associated with the active signing key and the previous signing key (if configured) at the GET /keyPairs/oauthOpenIdConnect/JWKS endpoint.

      This endpoint is only available to authenticated PingAccess admin API users on the admin.port defined in the <PA_HOME>/conf/run.properties file. Learn more in PingAccess API endpoints.

      When you select the Publish Certificate checkbox for a key type, the associated chain of certificates is published as the x5c parameter value. This enables the OIDC provider to validate a certificate if it’s been revoked.

    5. Click Save.

      Result:

      The active signing key and the previous signing key (if configured) are published at the PingAccess static key gJWKS endpoint: GET /keyPairs/oauthOpenIdConnect/JWKS.

  4. Configure the token provider so it can validate the signed JWT that PingAccess will send.

    Switching between dynamically rotating and static keys in PingAccess doesn’t work the same way as it does in PingFederate. If you change a dynamically rotating key to a static key in PingAccess, you can’t use the previous JWKS URL value generated for the dynamically rotating key. This is because static keys and dynamically rotating keys use different JWKS endpoints in PingAccess. These endpoints generate values that overwrite each other.

    1. In PingAccess, on the Static OAuth & OpenID Connect Keys page, click View Metadata, then click Copy.

      Click View Metadata at any time to check the JWKS information available at the GET /keyPairs/oauthOpenIdConnect/JWKS endpoint.

    2. In your token provider environment, open the OAuth client you’re using for static key signing and paste the metadata value you copied in step 4a into your JWKS configuration.

      Example:

      If you’re using PingFederate as the token provider:

      1. In PingFederate, go to Applications > OAuth Clients and open the OAuth client you’re using for this configuration.

      2. In the JWKS field, paste the metadata value you copied in step 4a.

      Learn more in Configuring OAuth clients in the PingFederate documentation.

Next steps

Configure the Signing Algorithm on the associated web session. Learn more in step 8 of Creating web sessions.