How do I set up a JWKS (JSON Web Key Set) endpoint
-
Understanding JWKS: JWKS is a set of keys containing the cryptographic keys that should be used to decode a JWT. These keys can be used to verify the signature of the client assertion JWT or to encrypt an ID token containing the user's Personally Identifiable Information(PII).
-
Creating a Publicly Accessible Website for Hosting JWKS:
-
Host the JWKS on a URL that is publicly accessible.
-
Ensure that the endpoint is compatible with NDI's service level expectations - NDI - Redirect Auth API Reference
-
Tools like mkjwk - JSON Web Key Generator can be used to understand how JWK works, but it is not recommended for generating real key pairs.
-
-
Client JWK Requirements :
-
If Relying Parties (RPs) are requesting NRIC and UUID in the payload, they must generate two types of cryptographic keys: one signing key and one encryption key pair. Only the public keys should be uploaded onto the JWKS endpoint.
-
Signature JWK:
-
Private Signing Key: Used by the RP to sign the client assertion.
-
Public Signing Key: NDI will retrieve this from the RP's JWKS endpoint to verify the signature of the client assertion JWT during the token request.
-
Multiple Keys: If there are multiple signing keys available, RP will need to specify the kid value in the client assertion so NDI knows which signing key to use
-
Requirement: The private signing key is used for signing, and the public signing key is used for verification by NDI.
-
-
Encryption JWK:
-
Public Encryption Key: NDI will retrieve this from the RP's JWKS to encrypt the ID tokens requested from the /token endpoint.
-
Private Encryption Key: Used by the RP to decrypt the ID token.
-
Multiple Keys: If there are multiple encryption keys available, NDI will select the strongest supported encryption key for encryption.
-
Requirement: The public encryption part is used by NDI for encryption, and the private encryption part is used by the RP for decryption.
-
-
-
JWK for Signing:
-
Key Usage: Must use value 'sig' as per rfc7517#section-4.2.
-
Key ID: Must contain a key ID in the standard 'kid' field as per rfc7517#section-4.5.
-
Key Type: Must be an EC key, with curves: P-256, P-384, or P-521 (NIST curves).
-
Example EC Signing Key:
{ "kty": "EC", "use": "sig", "kid": "sig-2021-01-15T12:09:06Z", "crv": "P-256", "x": "Tjm2thouQXSUJSrKDyMfVGe6ZQRWqCr0UgeSbNKiNi8", "y": "8BuGGu519a5xczbArHq1_iVJjGGBSlV5m_FGBJmiFtE" }
-
-
JWK for Encryption:
-
Key Usage: Must use value 'enc' as per rfc7517#section-4.2.
-
Key ID: Must contain a key ID in the standard 'kid' field as per rfc7517#section-4.5.
-
Key Type: Must be EC key, with curves: P-256, P-384, or P-521 (NIST curves)
-
Key Encryption Algorithm: Must specify the appropriate key encryption algorithm consistent with the key type/curve (key), and meet the requirements on allowed alg/curve/key sizes, compatible with RFC7518.
-
Examples:
-
EC Encryption Key:
{ "kty": "EC", "use": "enc", "kid": "enc-2021-01-15T12:09:06Z", "crv": "P-256", "x": "xom6kD54yfXRPvMFVYFlVjUKzmNhz7wf0DP_2h9kXtY", "y": "lrh8C9c8-SBJTm1FcfqLkj2AnHtaxpnB1qsN6PiFFJE", "alg": "ECDH-ES+A128KW" }
-
-
-
Tips and Considerations:
-
Utilize open-source tools like mkjwk - JSON Web Key Generator to understand JWK representation but avoid using it to generate real key pairs.
-
Review the supported algorithms and ensure compliance with NDI's broad requirements on structure.
-
By following these guidelines, you can successfully implement a JWKS that meets the requirements of NDI and ensures the secure handling of client assertions and user information.
Disclaimer: The tools shown are just examples among a wide array that are available. The use of a specific tool is in no way intended to be an endorsement of any particular product, service or vendor.
Comments
0 comments
Please sign in to leave a comment.