Client JWKS

Clients must provide public keys in the JSON Web Key (JWK) format to enable secure signing and encryption operations. These keys are essential for verifying signed client requests and for encrypting ID tokens returned by Corppass.

Clients authenticating with Corppass using JWT-based client assertions must expose a JSON Web Key Set (JWKS) at a publicly accessible URL. This allows Corppass to verify the digital signatures of JWTs submitted with PAR (Pushed Authentication Request) or token requests.

What is a JWKS?

A JWKS is a JSON document that contains one or more public keys. Each key corresponds to a private key that the client uses to sign JWTs. Corppass uses the kid (Key ID) in the JWT header to find the matching key in the JWKS and verify the signature.

Ensure that the private key component (d) is never included in the JWK. Only public key parameters such as x, y, e, n should be exposed to maintain the security of cryptographic operations.

Hosting your JWKS

Clients integrating with Corppass must adhere to the following service-level requirements to ensure secure and reliable interactions:

• HTTPS Requirement: The JWKS endpoint must be served over HTTPS on port 443, using a publicly trusted and verifiable TLS certificate.

• Performance: The endpoint should respond within 3 seconds to ensure optimal performance and minimal authentication latency.

• Key Availability: The JWKS must always include at least one valid public key for signing and encryption respectively.

• Direct Accessibility: The configured JWKS endpoint URL must return the JWKS response directly and should not perform HTTP redirects (e.g. 301, 302, 307).

JWKS Example

{
  "keys": [
    { 
      "kty": "EC", 
      "use": "sig",
      "alg": "ES256",
      "kid": "UErQ3h_cFg3FQHrWFwAj7RPyeHjPoO7mj3IWj2jGhso", 
      "x": "7eArnDiZnGA0Pg115rH4X0VHbnI00fVag1wbLihruF4", 
      "y": "eK6jKnD1P4f9hsjZ9v4W6ZTuhwd87R01ClK1NEYAdoI", 
      "crv": "P-256" 
    },
    {
      "kty": "EC", 
      "use": "enc",
      "alg": "ECDH-ES+A128KW",
      "kid": "SfyArsBpqSONSMkYid3snFYPea69t1Blc-tiDaUUlVs", 
      "x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY", 
      "y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE",
      "crv": "P-256"
    }
  ]
}

JWK for Signing

The signing JWK is used to verify the Client Assertion JWT submitted during token requests.

An example of Signing JWK (ES256, P-256 Curve):

{ 
  "kty": "EC", 
  "use": "sig", 
  "alg": "ES256", 
  "kid": "UErQ3h_cFg3FQHrWFwAj7RPyeHjPoO7mj3IWj2jGhso",
  "x": "7eArnDiZnGA0Pg115rH4X0VHbnI00fVag1wbLihruF4", 
  "y": "eK6jKnD1P4f9hsjZ9v4W6ZTuhwd87R01ClK1NEYAdoI", 
  "crv": "P-256" 
}

Claim	Description
kty	Specifies the key type. Must be "EC" to denote an Elliptic Curve key.
use	Indicates the intended use of the key. Must be set to sig to specify that the key is used for digital signature operations.
alg	Defines the algorithm intended for use with the key. Supported values are: ES256, ES256K, ES384, and ES512.
kid	A unique identifier that helps Corppass select the correct key for verifying client assertions.
crv	Indicates the elliptic curve used. Supported values are: P-256 (NIST secp256r1) P-384 (NIST secp384r1) P-521 (NIST secp521r1) secp256k1

JWK for Encryption

The encryption JWK is used to encrypt sensitive responses returned by the Authorization Server, including the ID Token issued at the /token endpoint and the payload from the /userinfo resource endpoint. This ensures that only the intended recipient (the client) can decrypt and access the protected information. Clients must publish a valid public encryption key in JWK format to enable this secure transmission.

An example of an Encryption JWK (ECDH-ES+A128KW, P-256 Curve)

{ 
  "kty": "EC", 
  "use": "enc",
  "alg": "ECDH-ES+A128KW",
  "kid": "SfyArsBpqSONSMkYid3snFYPea69t1Blc-tiDaUUlVs", 
  "x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY", 
  "y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE", 
  "crv": "P-256", 
}

Claim	Description
kty	Specifies the key type. Must be "EC" to indicate an Elliptic Curve key.
use	Indicates the intended use of the key. Must be set to "enc" to specify that the key is used for encryption.
alg	Defines the key management algorithm used for encryption. Supported values are: ECDH-ES+A128KW, ECDH-ES+A192KW, and ECDH-ES+A256KW.
kid	A unique identifier that allows the Authorization Server to select the correct public key for encrypting responses.
crv	Indicates the elliptic curve used. Supported values are: P-256 (NIST secp256r1), P-384 (NIST secp384r1), and P-521 (NIST secp521r1).

Key Rotation Guidelines

To maintain strong security hygiene and align with best practices, clients should rotate their signing and encryption keys regularly.

Corppass supports seamless key rotation without downtime by allowing clients to publish multiple keys in their JWKS. The Authorization Server uses the kid (Key ID) value in incoming JWTs to select the appropriate key for verification or encryption.

By following the steps below, clients can introduce new keys and deprecate old ones without impacting ongoing integrations.

Signing Key Rotation

Time	Action
Prep	The Relying Party (RP) generates a new signing key pair (K2) for use in signing client assertions.
T0	The RP publishes the new public key (K2) to its JWKS endpoint, while retaining the existing key (K1).
T0 - T+1 hour	Corppass retrieves the RP’s updated JWKS, which now includes K2. It uses the kid value in the client assertion's header to identify the correct key for signature verification
> T+1 hour	The RP begins signing client assertions using the new key (K2).
Clean Up	Once confident that K2 is in use and functioning correctly, the RP may remove the old key (K1) from its JWKS endpoint.

Encryption Key Rotation

Time	Action
Prep	The Relying Party (RP) generates a new encryption key pair (K2) for decrypting tokens. The existing key pair (K1) remains available for decrypting ID tokens.
T0	The RP updates its JWKS endpoint by removing public key K1 and adding the new public key K2.
T0 - T+1 hour	Corppass begins encrypting ID tokens and other protected payloads using the new encryption key (K2).
> T+1 hour	During key rotation, Corppass may begin encrypting ID tokens using a new key (K2), while some tokens may still be issued using the previous key (K1) due to caching or propagation delays. Relying Parties (RPs) must implement dynamic decryption by inspecting the kid field in the JWE header to determine which decryption key (K1 or K2) to use. Failure to support multiple active decryption keys during rotation may result in decryption failures or rejected tokens.
Clean Up	Once the RP confirms that no new tokens are being encrypted with K1, it can safely remove support for decrypting with K1.