An Introduction to JSON Web Tokens (JWT)

Monday Dec 2nd 2019 by Diogo Souza

Diogo Souza walks you through what JSON Web Tokens are and how JWTs work.

JWT is an industry standard (RFC-7519) that defines how to transmit and store JSON objects compactly and securely between different applications. The data contained therein can be validated at any time because the token is digitally signed.

It consists of three sections: Header, Payload and Signature.


The Header is a JSON object that defines information about the token type (typ), in this case JWT, and the encryption algorithm used in its signature (alg), usually HMAC SHA256 or RSA.

{<br />   "alg": "HS256",<br />   "typ": "JWT"<br />}


Payload is a JSON object with the claims of the handled entity, usually the authenticated user.

These claims can be of 3 types:

    • Reserved claims: Non-mandatory (but recommended) attributes that are used in token validation by API security protocols.
sub (subject) = Entity to which the token belongs, usually the user ID; <br />iss (issuer) = Token sender; <br />exp (expiration) = Timestamp of when the token will expire; <br />iat (issued at) = Timestamp of when the token was created; <br />aud (audience) = Token recipient, represents the application that will use it.

Generally the most used attributes are: sub, iss and exp.

      • Public claims: Attributes we use in our applications. We usually store the authenticated user information in the application.
<span>name</span><br /><span>roles</span><br /><span>permissions</span>
      • Private claims: Attributes specially defined to share information between applications.
{<br />   "sub": "123454",<br />   "name": "John Doe",<br />   "admin": true<br />}


The signature is the concatenation of hashes generated from Header and Payload using base64UrlEncode, with a secret key or RSA certificate.

This signature is used to ensure the integrity of the token, if it has been modified and was actually generated by you.

This prevents man-in-the-middle attacks in which an attacker could intercept the request and modify its content, thereby impersonating the user with false information. If the payload changes, the final hash will not be valid as it was not signed with your secret key.

Final Result

The end result is a token with three sections (header, payload, signature) separated by "." - dot.

JWT Figure 1
Figure 1. Example of token

Using the Token

When you log in to an authentication service, a JWT token is created and returned to the client. This token must be sent to the APIs through the Authorization header of each HTTP request with the Bearer flag, as illustrated in the diagram below.

<span>Authorization: Bearer <token> </span>

In possession of the token, the API does not need to go to the database to consult the user information, because contained in the JWT token itself, we already have its access credentials.


In order to improve your skills on JWT, you can follow up with reviewing the official JWT specification.

As you can see, authentication in APIs is vitally important. We cannot expose our APIs to the world without guaranteeing at least minimal security, unless the intention is to actually leave it open.

There are many other points to note, such as using Refresh Tokens, external authentication via Facebook, Google and Twitter for example.

About the Author

Diogo Souza works as a Java Developer at PagSeguro and has worked for companies such as Indra Company, Atlantic Institute and Ebix LA. He is also an Android trainer, speaker at events on Java and mobile world.

Mobile Site | Full Site