PingOne Recognize

JWT verification best practice

Learn how to a jwks.json endpoint for JWT verification and seamless key rotation.

We advise following best practice when leveraging JWT Verification. Doing so allows us to rotate the KMS keys, which also helps to increase the resilience of our SaaS platform.

Where to download the PingOne Recognize jwks.json endpoint.

The PingOne Recognize endpoint for downloading the jwks.json is available at https://api.keyless.io/customers/keyless/.well-known/jwks.json.

In this example, we used api.keyless.io as the Operation Service URL and keyless as the customer name. Replace this customer name with the tenant name you were provided nad the correct Operation Service URL for your region.

The verification process

  1. Extract the header: Parse the JWT header (unverified) to retrieve the kid (Key ID) and alg (Algorithm) parameters.

  2. Lookup the Key: Search the cached jwks.json for a key where the kid matches the JWT header. Confirm the use property is sig (signature) and the alg matches your expected security profile (for example, RS256).

  3. Construct Public Key: COnvert the JWK components (for RSA: the n modulus and e exponent) into a PEM-formatted public key.

  4. Validate Signature: Use the reconstructed public key to verify the JWT’s cryptographic signature and check standard claims (exp, iat, iss).

Handling key rotation

To prevent authentication failures when keys are rotated, implement the following logic in your validation logic:

  1. Caching with Refresh: Maintain an in-memory cache of the JWKS. Set a standard TTL (for example, 24 hours).

  2. Lazy refresh on kid mismatch: If a JWT arrives with a kid not present in your current cache, perform an immediate, one-time fetch of the jwks.json to see if a new key has been published.

  3. Rate limiting: Limit "on-demand" JWKS fetches (for example, once every 5 minutes) to prevent a malicious actor from triggering a Denial of Service (DoS) by sending tokens with random kid values.

  4. Graceful overlap: Ensure your verification logic can handle multiple keys in the keys array simultaneously. During rotation, the provider will publish both the old and new keys. Your system should trust any valid key currently present in the set.