JWT – Quick reference for the header and JWS parameters

This blog was originally posted to – https://devonblog.com/security/quick-reference-for-the-header-and-jws-parameters/ 

This blog aims at providing quick reference over the JWT claims and meta information because they are often presented short in three letters to keep them compact. To follow the blog intermediate security knowledge is required.

The oversimplified JWT definition:

JWT has three components.

[MetaInformation].[Claims].[Signature]

Sample JWT in the image below:

1. Base64 – The meta data (or header or manifest) that includes how the token is structured, signed, and so on.

2. Base64 – Claims is what provides the actual meaning of the token.

3. Base64 – Signature intends to provide authenticity and integrity.

https://tools.ietf.org/html/rfc7519#section-10.1.2 describes the registered claims for JWT. An identify provider has the flexibility to add claims that are specific for the intended situations.

Exploring JWT header:

Let’s look at the following JWT sample (base64 decoded) that has the below header information. We will explore the data section subsequently.

RFC reference – https://tools.ietf.org/html/rfc7515#section-4.1 (JSON Web Signature)

typ:

In the above example typ indicates the token type that is JWT

alg:

alg indicates the algorithm type of algorithm used to sign the JWT token. Most commonly used values are RS256, HS256 which stand for RSA-SHA256 (asymmetric) and HMAC-SHA256 (symmetric) respectively.

RS256 alg belongs to the RSA kty (read the kty section below)

x5t:

x5t is the X509 certificate’s thumbprint. That is the certificate whose private key was used to sign the JWT

kid:

kid id the key id indicating which key was used to sign the JWT token. This field is particularly useful when the public key discovery endpoint supports many keys and we need to know which key was used to sign.

In order to verify the signature of the JWT token, the verifier needs to know the public key of the public /private key pair used to sign the JTW token. Most identify providers expose this information via discovery mechanisms such as the one below from Microsoft azure.

In the above example

kty:

If the key type that is the algorithm family used to sign the JWT. RSA, EC are some allowed kty. RS256, RS512 are some algorithms (alg) that belong to the RSA algorithm family (kty)

use:

whether the algorithm is used for enc encryption or sig signing

x5t and kid:

explained above

n:

public key component of the RSA – https://en.wikipedia.org/wiki/RSA_(cryptosystem)#Operation

e:

public key component of the RSA – https://en.wikipedia.org/wiki/RSA_(cryptosystem)#Operation

[Note: If the algorithm kty is EC (elliptic Curve) then the public components are x and y]

x5c:

the x509 certificate chain

The next blog will provide reference information for a sample JWT token from Azure AD.

Credits and References:

https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-id-and-access-tokens

https://tools.ietf.org/html/rfc7519

https://redthunder.blog/2017/06/08/jwts-jwks-kids-x5ts-oh-my/

https://tools.ietf.org/html/rfc7518

https://tools.ietf.org/html/rfc7515