JWKS Endpoint

The JSON Web Key Set (JWKS) Endpoint hosts the Public Signing Keys used by Corppass.

Corppass signs all sensitive tokens (including the ID Token and Userinfo Response) using a dedicated private key. To validate the integrity and authenticity of these tokens, Relying Parties (RPs) must retrieve the corresponding public key from this endpoint.

Request

GET /.well-known/keys

Response

The response is a JSON object containing an array of keys (keys). Each key follows the JSON Web Key (JWK) specification.

Performance Note: Caching

Responses from this endpoint, or individual keys within the JWKS, should be cached by the RP for at least 1 hour to avoid retrieving the JWKS for every JWT validation.

Sample Reponse

HTTP/2 200
content-type: application/jwk-set+json; charset=utf-8
content-length: 955
{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "kid": "OvNklZwNmhiE6tu9mtWTDAv218k2DMjuRaGhkBgFdOo",
      "alg": "ES256",
      "crv": "P-256",
      "x": "gnbm-h8k3ZzeegHK0x87wO_SP_MLFts9XPZm7pE8U04",
      "y": "JvtZtPUqAS6837asiImtx-oO05wQS-Z6lOneq9zi_qQ",
    }
  ]
}

How to Validate a Signature

This endpoint returns one or more public keys in JSON Web Key (JWK) format.

To validate a JWT signature, your application (or OIDC library) must follow these steps:

1. Extract Header: Parse the JOSE Header of the received JWT (ID Token or Userinfo).

2. Read Key ID: Note the kid (Key ID) value in that header.

3. Find Key: Look up the key in the JWKS response where the kid matches the token's kid.

4. Check Usage: Ensure the matched key has the attribute "use": "sig" (that indicates a signing key).

5. Verify: Use this public key to verify the JWT signature.

Key Rotation

Corppass reserves the right to rotate / update its signing keys at any time, and without prior notice.

When a key rotation occurs:

1. New keys will be published to the JWKS endpoint, each with a unique kid value.

2. JWTs issued after the rotation will reference the updated kid in their JOSE headers.

3. RPs must refresh their cached JWKS by querying the JWKS endpoint to retrieve the updated keys.

Handling Rotation (Best Practice): To ensure zero downtime, RPs should implement a "Lazy Refresh" strategy:

1. Cache the JWKS response locally (e.g., for 1 hour).

2. If you receive a token with an unknown kid (not in your cache), immediately refresh your cache by calling this endpoint again.

3. Retry validation with the new keys.