Securing Web-REST-APIs with JWT
By: Samuel Owino
Tags: Software Engineering, Security, Rest Api, Software Architecture, Json Web Token

The right way to balance out security and convenience on the web

source: the Independent: the US to call for a worldwide tightening of airport security measures over fears of ‘new generation’ of Syrian terror attacks

JSON Web Token (JWT) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

This information can be verified and trusted because it is digitally signed.

JWTs can be signed using a secret(with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

JWT is robust and can carry a lot of information but it's still simple to use even though its size is relatively small.

Link any other token, JWT can be used to pass the identity of authenticated users between an identity provider and a service provider

(which are not necessarily the same system). It can also carry all the user’s claim, such as authorization data, so the service provider does not need to go into the database or external system to verify user’s roles and permissions for each request; ~ that data is extracted from the token.

JWT Authentication Flow

source: toptal blog: Spring Security

Clients logs in by sending their credentials to the identity provider.

The identity provider verifies the credentials; if all is OK, it retrieves the user data, generates a JWT containing user details and permissions that will be used to access the services, and it also sets the expiration of the JWT (which might be unlimited).

The client stores the JWT for a limited or unlimited amount of time, depending on the expiration set by the identity provider.

The client sends the stored JWT in an Authorization header for every request to the service provider.

For each request, the service provider takes the JWT from the Authorization header ad decrypts it, if needed, validates the signature and if everything is OK, extracts the user data and permissions. Based on this data solely, and again without looking up further details in the database or contracting the identity provider, it can accept or deny the client request. The only requirements are that the identity and service providers have an agreement on encryption so that the service can verify the signature or even decrypt which identity was encrypted.

The main difference between JWT and other arbitrary tokens is the standardization of the token’s content.

Another recommended approach is to send the JWT token in the Authorization header using the Bearer scheme.

The content of the header should look like this;

:Authorization: Bearer <token>

When should you use JSON Web Tokens?

Authorization:

This is the most common scenario for using JWT. Once the user is logged in, each subsequent request will include the JWT, allowing the user to access routes, services, and resources that are permitted with that token. Single sign-on is a feature that widely uses JWT nowadays, because of its small overhead and its ability to easily be used across different domains.

Information Exchange:

JSON Web Tokens are a good way of securely transmitting information between parties. Because JWTs can be a signed-for example, using public/private key pairs- you can be sure the senders are who they say they are. Additionally, as the signature is calculated using the header and the payload, you can also verify that the content hasn’t been tampered with.

What is the JSON Web Token Structure?

In its compacted form, JSON Web Tokens consist of three parts by dots (.)

which are:

1. Header

2. Payload

3. Signature

Therefore a jwt looks like the following:

xxxx.yyyyyy.zzzzz

Let's break down the different parts.

a. Header

The header typically consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256 or RSA.

For example:

{

“alg”: “HS256”,

“typ”: “JWT”

}

Then this JSON is Base64Url encoded to form the first of the JWT.

b. Payload

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional data. These three types of claims, public, registered and private claims.

c. Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header and sign that.

The result is three BASE64-URL strings separated by dots that can be easily passed in HTML and HTTP environments while being more compact

when compared to XML-based standards such as SAML.

How do JSON Web Tokens work? — Client-Side

In authentication, when the user successfully logs in using their credentials, a JSON Web Token will be returned. Since tokens are credentials, great care must be taken to prevent security issues. In general, you should not keep tokens longer than required.

Whenever the user wants to access a protected route or resource, the user agent should send the JWT, typically in the Authorization header using the Bearer schema. The content of the header should look like the following:

Authorization: Bearer <token>

The server’s protected routes will check for a valid JWT in the Authorization header, and if its present, the user will be allowed to access the protected resource.

If the token is sent in the Authorization header, Cross-Origin Resource Sharing (CORS) won’t be an issue as it doesn’t use cookies.

Why use JSON Web Tokens?

JWT is more compact that SAML (Security Markup Language Tokens) which are based on XML.

SWT (Simple Web Tokens) can only be symmetrically signed by a shared secret using the HMAC algorithm. JWT and SAML can use public/private key

pairs.

JWT’s main strength is handling user authentication in a stateless, and therefore scalable way while keeping everything secure with up-to-date cryptography standards.