Configuring static signing keys - PingAccess - 8.0

PingAccess

bundle
pingaccess-80
ft:publication_title
PingAccess
Product_Version_ce
PingAccess 8.0 (Latest)
category
Product
pa-80
pingaccess
ContentType_ce

Configure static keys for use in private key JSON Web Token (JWT)JSON Web Token (JWT)JWT An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. To read the industry standard, see RFC 7519 OpenID Connect (OIDC)OpenID Connect (OIDC)OIDC An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management. code flow instead of dynamically rotating keys to sign tokens as necessary.

  • In your token provider configuration, make sure that you've set up an OAuth clientOAuth clientThe application in an OAuth framework that requests access to resources. If the request is approved by the authorization server, the client is issued an access token for the resources..

    If you haven't set up an OAuth client and are using PingFederate as the token provider, see managing OAuth clients.

  • In PingAccess, make sure that you've generated or imported a key pairkey pair The private key and public key represented by a certificate. and then assigned it to a virtual host or HTTPS listener.

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

Important:

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 OpenID Connect.
Note:

PingAccess uses the Signing Algorithm configured on the OAuth Key Management page for dynamic key rotation unless you have 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 OpenID Connect to gain more control over key rotation.

To configure static signing keys:

  1. In PingAccess, go to Security > Key Pairs > Static OAuth/OIDC Keys.
  2. Select the Enable Static Keys check box to use static keys for OAuth and OpenID Connect.

    This check box 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 that 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.
      Note:

      There are no default selections for the signing key lists. If you don't find the signing key that 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 that you'd previously selected in the Active list if you still want the token provider to validate it.
      Note:

      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 that you want to use.
    4. Optional: For any key type for which you have selected an Active signing key, select the Publish Certificate check box to publish the certificates associated with the active signing key and the previous signing key (if configured) at the GET /staticKeys/JWKS endpoint.

      When you select the Publish Certificate check box 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.

    The active signing key and the previous signing key (if configured) are published at the PingAccess static key JSON Web Key Set (JWKS) endpoint, GET /staticKeys/JWKS.

  4. Prepare the token provider to validate the signed JWT that it will receive from PingAccess.
    Important:

    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.
      Tip:

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

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

      If you're using PingFederate as the token provider:

      1. In PingFederate, go to Applications > OAuth Clients and open the OAuth client that you're using for this configuration.
      2. In the JWKS field, paste the metadata value that you copied in step 4a.

      For more information, see Configuring OAuth Clients.

Configure the Signing Algorithm on the associated web session. For more information, see step 8 of Creating web sessions.