Layer7 API Gateway Json Web Token and how they work symmetric encryption

Products

• CA API Gateway

Issue/Introduction

Sometimes there is confusion about how a Json web token works and as such this is intended to bring some clarity on the functionality of JWE/JWT/JWKS.

 

Environment

Ca Layer7 API Gateway: 11.x

Resolution

JSON Web Token (JWT, rfc7519) is a compact and self-contained way to share data between parties securely. A JWT contains all of the required information about an entity to avoid querying a database more than once. The recipient of a JWT can validate its digital signature and or decrypt the token locally, without the need to interact with another server. JWTs are commonly used for authentication and authorization in APIs and data transfer between clients and servers. 

JSON Web Signature (JWS, rfc7515)

By signing a JWT the recipient can verify that the sender of the token is who it says it is and to ensure that the JSON object wasn't changed along the way. JWTs can use a public/private key pair in the form of an X.509 certificate for signing. A JWT can also be symmetrically signed by a shared secret using the HMAC algorithm. See the RFC-7519 7.1 section for details on creating. And  RFC-7519 7.2 section verifying a JWT signature.

Depending on the signing algorithm used the signing and verification process differs and a brief explanation is provided below: 

For asymmetric keys (RSA signature algorithms) the private/public keys are used. The private key is used to generate the signature, and the recipient of the JWT retrieves the public key from either metadata endpoints or the JSON Web Key (JWK)/JSON Web Key Set (JWKS) to perform the JWT signature verification. 

• JSON Web Key (JWK) A JSON object that represents a cryptographic key. The members of the object represent the properties of the key, including its value.
• JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) when the RS256 signing algorithm is used.

Note:

During the RSA JWT signature verification, the following occurs when a JWK/JWKS is available/used:

• Matching the "kid" (Key ID) from the JWT header with the corresponding key in the JWKS.
• Using the "n" and "e" values to construct the public key for signature verification.
• Verify the signature and other claims (Examples: iss, aud, expiration time, etc).

 

• If a JWKS contains the optional x5c parameter, the expectation is that the first X.509 certificate's RSA public key modulus in the list matches the "n" parameter; if this is not the case verification will fail.

 

For symmetric keys (HMAC signature algorithm) a private key/secret is used and shared between the two parties. Since the same key is used to both generate the signature and to validate it, care must be taken to ensure that the key is not compromised.

The Probabilistic Signature Scheme (i.e PS256) is a probabilistic version of RSA but differs in that the same JWT header and payload will generate a different signature each time (See the above RSA explanation for signature generation and verification).

JSON Web Encryption (JWE, rfc7516)

By encrypting a JWT payload you ensure that only the intended recipient can read it while also providing integrity and authentication checks. Combine this with JWS, and you have an encrypted token suitable for use as an access token in OAuth or an identity token in OpenID Connect. When a JWT is encrypted using JWE the output is serialized using the JWE Compact format (as opposed to less popular JWE JSON Serialization, which is not supported by the Layer7 Gateway). 

For symmetric keys (AES), a shared secret is used to encrypt the JWT payload. Since the secret is used to both encrypt and decrypt the payload, care must be taken to ensure that the secret is not compromised.

For asymmetric keys (RSA), the public key of the recipient is used to encrypt all necessary fields and is referenced by the key id (kid) and then decrypted using the recipient's private key.