Home » Enterprise Java » JWT Tutorial for Beginners

About Ed de Jongh

Avatar photo
Ed has worked in the IT industry for over 20 years, gaining experience in programming, architecture and design. As a seasoned Solution Architect, he is passionate about advancing simplicity and elegance. In addition to solution design, he is also involved in development and integration. Outside of the office, enjoys anything on two wheels and being a dad.

JWT Tutorial for Beginners

1. Introduction

JSON Web Tokens are described by the Internet Engineering Task Force (IETF)   RFC 7519 as:

a compact URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.”


Acronym fatigue, anyone? In case you’re still on board for some reason JWT is pronounced “JOT”, there that should leave you at least a little more puzzled. In this article I will break this down into “bite size” more easily digestible pieces that hopefully leave you the reader better informed as to what JWT is and how it works.

You see, even though I have used JWT a few times and seen it implemented in several solutions I have worked on. As with most tech projects in today’s deadline driven world I tend to glance over a lot of these types of technologies. Merely fulfilling the API requirements and merrily marching towards the end goal!!! All too often without stopping to smell the binary along the way. This however is a new year (I know it’s March already) and I have promised myself to focus on my art of solution development from a different perspective. To be a better geek and right the wrongs of the acronym enslaved universe.

2. JWT Compared

When compared to Simple Web Tokens (SWT) and Security Assertion Markup Language (SAML), there are some great benefits. JWT is arguably more secure than SWT because the latter can only be symmetrically signed by a shared secret implementing the HMAC (Hash based Message Authentication Code) algorithm. SAML on the other hand is XML based and unwieldy. JSON being less verbose than XML thus smaller and much better suited to HTML and HTTP passing.

JWT is pretty much ubiquitous across the internet and particularly suited to web applications and mobile apps too.

2.1 The JWT Lifecycle

2.1.1 Basic Steps

A user logs into an application and provides their credentials.

The Authentication server authenticates the user and creates a JWT which is returned to the user.

The user then makes various calls to the application and passes with these calls the newly created JWT.

The application can use the JWT to verify that the user has in fact been authenticated and proceed with fulfilling the users’ requests.

JWT Tutorial - JWT Lifecycle
JWT Lifecycle

3. JWT Structure

A JSON Web Token consists of three parts: A Header, a payload and a signature. Let’s take a look.

https://jwt.io offers a great introduction to this process, as well as an excellent breakdown of the three key elements of the JWT: The Header, a payload and a signature.

Let’s take a look.

The header typically consists of two parts, the type of token which is JWT and the signing algorithm for example SHA512

   "alg": " HS512",
   "typ": "JWT"

The header is the Base64Url encoded.

3.2 Payload

The payload contains the claims. Claims provide information about an entity, typically a user which has been authenticated and other data for example expiration time of the token. There are three types of claims: Registered, Public and Private.

A better technical definition of these categories of claims can be found here https://tools.ietf.org/html/rfc7519#section-4.1

On a cautionary note, when creating custom claim types there is a very real possibility of collisions with existing registered names. Collisions can be avoided by only utilising unregistered claim types. For more information see: https://www.iana.org/assignments/jwt/jwt.xhtml

An example Payload would look something like:

   "sub": "1234567890",
   "name": "Ricky Bobby",
   "admin": true 	 

The payload is also Base64Url encoded and added to the encoded header.

3.3 Signature

The third and final part of the Token is the signature. To create this, we take the Base64Url encoded header and payload, add a secret, the algorithm specified in the header and sign it.

  base64UrlEncode(header) + "." +

The secret should really also in my opinion, be Base64Url encoded, but it is not mandatory. The example here uses a secret for symmetrical signing for brevity. However, JWT can be asymmetrically signed using a suitable algorithm such as PS256 which relies on public/private key pairs.

The end result looks something like this:


4. JWT Security Considerations

JWT is about authorisation. I think this is an important statement to ponder when implementing JWT. Remember the user has already authenticated when they receive their token.

While the asymmetric encryption options do exist and are definitely necessary in some scenarios. We should consider the potential added complexity of certificate management and administration.

4.1 Encryption

While the above example is not encrypted and could be decoded. Any form of token manipulation should be detected by the receiver and the token should be rejected. This is very much implementation dependant.

Here is an excellent article by Sjoerd Langkemper https://www.sjoerdlangkemper.nl/2016/09/28/attacking-jwt-authentication/

that demonstrates just some possible vulnerabilities. The pros and cons of symmetric vs asymmetric JWT should be carefully considered.

If the entire session is over SSL/TLS is that not arguably sufficient? Without added complexity. It’s a tradeoff! Also depending on the JWT encryption implementation, there could potentially be an unnecessary performance overhead incurred.

4.2 Expiration

The IETF provides for an expiration value in the JWT specification: https://tools.ietf.org/html/rfc7519#section-4.1.4

The “exp” (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the “exp” claim requires that the current date/time MUST be before the expiration date/time listed in the “exp” claim.IETF

While tokens can be created without an expiration time. I do not recommend this. We know there are vulnerabilities with JWT implementations and an expiration time coupled with a well thought out session strategy for your particular use case helps mitigate some risks.

4.2.1 Access and Refresh Tokens

A basic guideline for most applications is 15 minutes or less. and re-authentication required every 5-7 days for tokens. You must allow clients to refresh their expired certificates. The shorter lived Token is known as the Access Token and the Longer Lived Token is the Refresh Token.

Access Token Access tokens are credentials used to access protected resources. An access token is a string representing an authorisation issued to the client. The string is usually opaque to the client. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorisation server. The token may denote an identifier used to retrieve the authorisation information or may self-contain the authorisation information in a verifiable manner (i.e., a token string consisting of some data and a signature). Additional authentication credentials, which are beyond the scope of this specification, may be required in order for the client to use a token. The access token provides an abstraction layer, replacing different authorisation constructs (e.g., username and password) with a single token understood by the resource server. This abstraction enables issuing access tokens more restrictive than the authorisation grant used to obtain them, as well as removing the resource server’s need to understand a wide range of authentication methods. Access tokens can have different formats, structures, and methods of utilisation (e.g., cryptographic properties) based on the resource server security requirements. Access token attributes and the methods used to access protected resources are beyond the scope of this specification and are defined by companion specifications such as [RFC6750].

Refresh Token Refresh tokens are credentials used to obtain access tokens. Refresh tokens are issued to the client by the authorisation server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorised by the resource owner). Issuing a refresh token is optional at the discretion of the authorisation server. If the authorisation server issues a refresh token, it is included when issuing an access token (i.e., step (D) in Figure 1). A refresh token is a string representing the authorisation granted to the client by the resource owner. The string is usually opaque to the client. The token denotes an identifier used to retrieve the authorisation information. Unlike access tokens, refresh tokens are intended for use only with authorisation servers and are never sent to resource servers.

IETF https://tools.ietf.org/html/rfc6749#section-1.4

4.3 Privacy of Data

The IETF also speaks to concern for privacy of the data in the JWT:

A JWT may contain privacy-sensitive information. When this is the case, measures MUST be taken to prevent disclosure of this information to unintended parties. One way to achieve this is to use an encrypted JWT and authenticate the recipient. Another way is to ensure that JWTs containing unencrypted privacy-sensitive information are on transmitted using protocols utilising encryption that support endpoint authentication, such as Transport Layer Security (TLS). Omitting privacy-sensitive information from a JWT is the simplest way of minimising privacy issues.IETF

Simply put, if you want to avoid another potential security issue, do not put sensitive data in the token.

The IETF provides much more information regarding security considerations here: https://tools.ietf.org/html/rfc6749#section-10

5. JWT Best Practices

The IETF provides a draft specification on JWT best practices: JSON Web Token Best Current Practices https://tools.ietf.org/html/draft-ietf-oauth-jwt-bcp-00#section-3

This document provides us with the current best practices and is a very valuable tool. While the document is very technically detailed I strongly recommend at least a once over for anyone looking at a JWT implementation.

I have summarised a list of best practices from the site here:

  • Cross-JWT Confusion
  • Perform Algorithm Verification
  • Validate All Cryptographic Operations
  • Use UTF-8
  • Validate Issuer and Subject
  • Use and Validate Audience
  • Use Explicit Typing

As with all things security related, weaknesses will be identified and fixes applied. It is always good to know you have at least covered the well known issues and countermeasures from the outset. In some instances not all the issues here will apply to your implementation such as cryptography if you are using secret based tokens.

6. JWT Tutorial – Conclusion

JWT is a great approach to securing web applications. Whether or not you use full blown encrypted certificates or simple signed certificates. The implementation will potentially deal with sensitive data and the access thereof. As such you need to handle with care.

When combined with powerful third party libraries such as AUTHO https://auth0.com/ for Authentication. it is a powerful security tool for the developer. However as shown JWT is about much more than simple Authorisation and I urge you to research best practices and ask the right questions when considering your next JWT implementation.

There is a plethora of tools out there available to help us ensure the security of our tokens and some of them are tried and tested.

TIP: You wouldn’t really consider creating your own encryption algorithm for obvious reasons (although in some cases you might need to), so make your journey easier, by leveraging what’s available in fulfilling a “best practice” implementation.

JWT implemented incorrectly, arguably just adds unnecessary overhead and little to no security benefits at all. When implemented correctly however, it provides a light weight, scalable, responsive token based security solution.

I am hoping that this article provided you, the reader with a much clearer understanding of what a JWT is comprised of and more importantly when and how it is used as part of your security strategy when building your next application.

7. Download the Source Code

This was a JWT tutorial for beginners.

You can download the full source code of this example here: JWT Tutorial for Beginners

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!


1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design


and many more ....


Receive Java & Developer job alerts in your Area

I have read and agree to the terms & conditions


Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Newest Most Voted
Inline Feedbacks
View all comments
3 years ago

Jason Web Tokens should be JSON Web Tokens.

3 years ago

Securing API with JWT

I understand the concept of JWT(Json Web Token) and how it works for REST APIs.

The thing is, in order to get the token, a user needs to authenticate(user and password), right?

How is that authentication secured and verified?
I know securing the channel(using HTTPS) is the first thing, but, if the following communications needs to be secured, authorized and authenticated; How is it possible the authentication part is not strongly secured?

Am I missing anything? Or is there anything else to secure the authentication step?