Another proud son of JSON: Using JSON Web Token to send data

JSON Web Token

A JSON Web Token (JWT) is a URL safe way to represent a set of information between two parties. The information shared between the parties can be referred to as claims. It is a safe way to transfer information because it can be signed using a secret or using a public or private key. The token is a base64 encoded string which due to its short length is meant for space constrained environments.

There are two basic scenarios in which the use of a JWT is recommended.

• Once a user is authenticated in an application and wishes to make subsequent requests, each one of those request should include a JWT to make sure that the user has access to certain routes, services or resources.

• To exchange information in a secure manner making use of the signature. The signature is calculated based on the body and the payload of the JWT which allows a party to know if the message has been tampered with (Auth0, 2015).

JWT structure example - JWT.

The JWT is made up of three parts that are separated by a single dot. Remember all the values are base64 encoded (header.payload.signature).

1. Header:

• Algorithm: This refers to the algorithm used to sign the token. Usually HMAC SHA256 or RSA.

• Type: Refers to the type of token. In this case "JWT".

2. Payload: Contains claims (names are only 3 characters long), which are statements about the user/entity and any additional metadata. Types of claims:

• Reserved: Predefined but not mandatory.

• Public: Defined by the user. Should be defined in a collision resistant namespace.

• Private: Custom created to share information between parties.

3. Signature: This is made by taking the encoded header, payload and secret/key and using the algorithm specified in the header to sign it.

How it works

JWT flow. Source: Stecky (2016).

As we can see in the image above, we have three entities. The user, the authentication server and the application server. Here we have four steps.

1. Initial authentication: The user first signs in to the authentication server. If we are talking about a company this could be the active directory.

2. JWT generation: The JWT is created by the authentication server and sent to the user to be used in further request.

3. User request: The user then makes an API call. In a company this could be a query made in the company's billing system. The JWT is added to the original request and sent to the application server.

4. JWT verification: The application server, billing system in our example, makes sure the call is coming from an authenticated user by checking the JWT and then returns a response to the user.

JWT Security

Remember the data in the JWT is encoded and signed but not encrypted. The data is encoded to transform the data structure and allow transportation following a standard definition. The data is signed to verify authenticity which lets me know if a message has been tampered with but it does not prevent it.

Here is a great article on how to Use JWT The Right Way!

Other alternatives like SAML (Security Assertion Mark-up Language) imply larger XML documents. JWTs are great when we have space constrained environments and are looking to guarantee the authenticity of the data being transported.

References

• Auth0. (2015, January 1). Introduction to JSON Web Tokens. Retrieved May 3, 2017.

• Internet Engineering Task Force IETF. (2015, May 1). RFC 7519. Retrieved May 3, 2017.

• Stecky, M. (2016, May 16). 5 Easy Steps to Understanding JSON Web Tokens. Retrieved January 3, 2022.