Client JWKS

Client JWK Requirements

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

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

JWK for Signing

The signing JWK is used to validate the Client Assertion JWT provided during token requests. Clients must adhere to the following requirements:

Attribute	Requirement
Key Use (use)	Must include "sig" to indicate signing.
Key ID (kid)	Must include a unique identifier to allow Corppass to select the correct key for validation.
Key Type (kty)	Must be an EC key.
Supported Algorithms (alg)	ES256, ES256K, ES384, ES512.
Supported Curves (crv)	P-256 (NIST, secp256r1), P-384 (NIST, secp384r1), P-521 (NIST, secp521r1), secp256k1.

JWK for Signing Example (ES256, P-256 Curve)

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

JWK for Encryption

The encryption JWK is used to encrypt the ID Token issued at the /token endpoint. Clients must adhere to the following requirements:

Attribute	Requirement
Key Use (use)	Must include "enc" to indicate signing.
Key ID (kid)	Must include a unique identifier to allow the client to select the correct decryption key.
Key Type (kty)	Must be an EC key.
Supported Algorithms (alg)	ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW.
Supported Curves (crv)	P-256 (NIST, secp256r1), P-384 (NIST, secp384r1), P-521 (NIST, secp521r1).

JWK for Encryption Example (ECDH-ES+A128KW, P-256 Curve)

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

Key Rotation

Clients can rotate signing and encryption keys without downtime by adhering to the following steps:

Signing Key Rotation

Time	Action
Prep	RP generates a new signing key pair (K2) supported for signing.
T0	RP adds public key K2 to its JWKS endpoint (and keeps K1 on the endpoint).
T0 - T+1 hour	Corppass retrieves the RP's published keys from their JWKS endpoint, now including K2. Corppass identifies the key to validate based on the kid provided in the JWS header.
> T+1 hour	RP changes their system to start signing client assertions using the new signing key K2.
Clean Up	Post-validation, the RP can remove key K1 from their JWKS endpoint once they are confident the new signing key is working.

Encryption Key Rotation

Time	Action
Prep	RP generates a new encryption key pair (K2) supported for decryption. The existing key pair (K1) remains available for decrypting ID tokens.
T0	RP removes public key K1 and adds public key K2 to its JWKS endpoint.
T0 - T+1 hour	Corppass begins encrypting ID tokens using the new encryption key K2.
> T+1 hour	During this period, the RP receives tokens encrypted with K2. However, in scenarios where keys are temporarily cached, Corppass may still send tokens encrypted with K1. The RP must ensure it can decrypt tokens with either K1 or K2 during this time.
Clean Up	Once confident that tokens encrypted with K1 are no longer in use, the RP can remove support for decrypting with K1.

Service-Level Expectations

• Must support HTTPS on port 443 with a publicly verifiable TLS certificate.

• Must respond within 3 seconds for optimal performance.

• Failure to retrieve JWKS will result in invalid_client errors for:

  • Client assertion validation

  • Encryption of ID Tokens