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 during token or PAR 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.
JWKS Example
{
"keys": [
{
"kty": "EC",
"kid": "UErQ3h_cFg3FQHrWFwAj7RPyeHjPoO7mj3IWj2jGhso",
"use": "sig",
"alg": "ES256",
"x": "7eArnDiZnGA0Pg115rH4X0VHbnI00fVag1wbLihruF4",
"y": "eK6jKnD1P4f9hsjZ9v4W6ZTuhwd87R01ClK1NEYAdoI",
"crv": "P-256"
},
{
"kty": "EC",
"use": "enc",
"kid": "SfyArsBpqSONSMkYid3snFYPea69t1Blc-tiDaUUlVs",
"crv": "P-256",
"x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY",
"y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE",
"alg": "ECDH-ES+A128KW"
}
]
}
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",
"kid": "UErQ3h_cFg3FQHrWFwAj7RPyeHjPoO7mj3IWj2jGhso",
"use": "sig",
"alg": "ES256",
"x": "7eArnDiZnGA0Pg115rH4X0VHbnI00fVag1wbLihruF4",
"y": "eK6jKnD1P4f9hsjZ9v4W6ZTuhwd87R01ClK1NEYAdoI",
"crv": "P-256"
}
use
Indicates the intended use of the key. Must be set to sig
to specify that the key is used for digital signature operations.
kid
A unique identifier that helps Corppass select the correct key for verifying client assertions.
kty
Specifies the key type. Must be "EC"
to denote an Elliptic Curve key.
alg
Defines the algorithm intended for use with the key. Supported values are: ES256
, ES256K
, ES384
, and ES512
.
crv
Indicates the elliptic curve used. Supported values are:
P-256
(NISTsecp256r1
)P-384
(NISTsecp384r1
)P-521
(NISTsecp521r1
)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 /entity-info
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",
"kid": "SfyArsBpqSONSMkYid3snFYPea69t1Blc-tiDaUUlVs",
"crv": "P-256",
"x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY",
"y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE",
"alg": "ECDH-ES+A128KW"
}
use
Indicates the intended use of the key. Must be set to "enc"
to specify that the key is used for encryption.
kid
A unique identifier that allows the Authorization Server to select the correct public key for encrypting responses.
kty
Specifies the key type. Must be "EC"
to indicate an Elliptic Curve key.
alg
Defines the key management algorithm used for encryption. Supported values are: ECDH-ES+A128KW
, ECDH-ES+A192KW
, and ECDH-ES+A256KW
.
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
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
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.
Last updated