PingFederate Server

JSON Web Keys endpoint

PingFederate supports the OpenID Connect (OIDC) JSON Web Key Set (JWKS) endpoint.

This endpoint provides a list of JSON Web Keys (JWKs) used to validate, sign, and encrypt JSON Web Token (JWT). The endpoint does not require client authentication and includes configured Elliptic Curve (EC) and RSA-based keys.

Each key listed in the endpoint includes a key ID (kid) and other claims. When PingFederate generates and signs a JWT, it includes the matching kid in the JWT header to identify the public key required to verify the signature.

After downloading the JWKS, a client can locate the appropriate public key by matching the kid and then validating the JWT signature. To encrypt a JWT, a client uses a JWK whose usage is configured for encryption and includes the kid in the generated JWT header.

The following table outlines the property names and descriptions of the JWKS endpoint.

Property name Description

kty

The family of cryptographic algorithms used with the key.

kid

The unique identifier for the key.

use

Indicates the intended use of the key:

  • sig represents signature.

  • enc represents encryption.

n

The modulus for the RSA public key.

e

The exponent for the RSA public key.

alg

An optional parameter to identify the specific cryptographic algorithm used with the key.

The key size might not always match the cryptographic algorithm used with the key. For example, an RSA 256 key can be used when the signing algorithm is RS384.

x5c

The X.509 certificate chain. The first entry in the array is the certificate to use for token verification. The other certificates can be used to verify this first certificate.

x5t

The x.509 certificate SHA-1 thumbprint.

The list of JWKs can be maintained and managed by PingFederate, which can create and rotate the keys, or manually by the PingFederate administrator. The supported algorithms are listed in both the OIDC and OAuth Metadata endpoints.

When PingFederate manages the keys, it includes the alg (algorithm) claim for the following keys:

  • All elliptic curve keys using any supported algorithm , such as ES256, ES384, and ES512

  • Three RSA keys, when the signing algorithm is RS256 (previous, current, pending)

For manually managed keys (static keys), the alg claim is included for the following keys:

  • All elliptic curve keys using any supported algorithm, such as ES256, ES384, and ES512

  • Two RSA keys using RS256 (previous, current)

PingFederate traditionally uses one RSA-based key for multiple RSA-based signing algorithms (RS384 and RS512) irrespective of the key size, and when the signing algorithm is RS256, the signing key is a dedicated RSA key with the alg header RS256. Not all RSA-based keys support the alg header.

The following is an example of the JWKS response with an array of two JWK objects:

    {
      "keys": [
         {
            "kty": "RSA",
            "kid": "1",
            "use": "sig",
            "n": "t7jW8PvJRA7qo4N4dY7JZt1vNtLX9SdRyV1ytW8Fv2jKgGJfRdKjSNWZIvA2fO3efrjzb35LTUpatb0x6OcTjID0J6YwO6UZQL0xfDeX9jK78B2JGpxShsC-VzHf2ggn_rBBFBRHvLcZlGSlpjOyh7X9dNIx-rKjyZH8OYdY7db4nxHzvZV7LZjKzRt7S9jkG5Qh7Kol8F1JwYjGIVf03QmUR-yWZnGGFJbP9oEJMW_kRWVCn_-Ic6wgK1NIDJFjjUZP6oZgQzAjbAULNV1sHsMYyrDTyOAc_26fTJp6MLDeUZ_iO8jKkrrgXsDxUnsztOeHOrGnvMw",
            "e": "AQAB",
          },
          {
             "kty": "RSA",
             "kid": "2",
             "use": "sig",
             "alg": "RS256",
             "n": "uysKtR1Gz9Sd5Q5np5mKk8Q2YwI5RByz1-Z8ry_vWOBzvBaC87Pc3q3a8K1JxFNv-Wz_s0cYfB2oEgG0jJeb5yo6H5l5TT8g6PYmJ1r14HMeuV7Kj59aGxEV7y4i1HnV7-  eQX07ZuVnZSgmjJNN3qXL_8nwTBNCHrqtkyLGtjK__s1sXljjnoV7lZjzNq3Y3qyTb-7B2wJXTKjyyVyx1epcnoeZVxP4pLVTmHjK4SLjjL20l4gTXi1hKj2QHQXbF7ZdDfCn19cdYQ-CK8h6NGKgJU5Z6U5M5mkhA6rMDZrLlRJvyNJzCFg8WuzF41GXwdrC3Aq3Q",
             "e": "AQAB"
           }
      ]
    }