You can find the code for this tutorial here.

Let’s start by catching a glimpse of the file structure of the project:

Just to throw some background in, we have a wonderful introduction, courtesy of jwt.io! Let’s take a look:

JSON Web Token (JWT) is an open standard (RFC 7519) 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.

Let’s explain some concepts of this definition further.

Compact: Because of their smaller size, JWTs can be sent through a URL, POST parameter, or inside an HTTP header. Additionally, the smaller size means transmission is fast.

Self-contained: The payload contains all the required information about the user, avoiding the need to query the database more than once.

Here are some scenarios where JSON Web Tokens are useful:

Authentication: 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 be easily used across different domains.

Information Exchange: JSON Web Tokens are a good way of securely transmitting information between parties. Because JWTs can be 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.

JSON Web Tokens consist of three parts separated by dots (.), which are:

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz

Let’s break down the different parts.

Header

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

For example:

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

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 metadata. There are three types of claims: reserved, public, and private claims.

An example of payload could be:

The payload is then Base64Url encoded to form the second part of the JSON Web Token.

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.

For example if you want to use the HMAC SHA256 algorithm, the signature will be created in the following way:

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way. Putting all together

The output is three Base64 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.

The following shows a JWT that has the previous header and payload encoded, and it is signed with a secret. Encoded JWT

In authentication, when the user successfully logs in using their credentials, a JSON Web Token will be returned and must be saved locally (typically in local storage, but cookies can be also used), instead of the traditional approach of creating a session in the server and returning a cookie.

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

This is a stateless authentication mechanism as the user state is never saved in server memory. The server’s protected routes will check for a valid JWT in the Authorization header, and if it’s present, the user will be allowed to access protected resources. As JWTs are self-contained, all the necessary information is there, reducing the need to query the database multiple times.

This allows you to fully rely on data APIs that are stateless and even make requests to downstream services. It doesn’t matter which domains are serving your APIs, so Cross-Origin Resource Sharing (CORS) won’t be an issue as it doesn’t use cookies.

The following diagram shows this process:

Token based authentication schema’s became immensely popular in recent times, as they provide important benefits when compared to sessions/cookies:

Some trade-offs have to be made with this approach:

JWT Authentication flow is very simple

It’s important to note that authorization claims will be included with the Access token. Why is this important? Well, let’s say that authorization claims (e.g user privileges in the database) are changed during the life time of Access token. Those changes will not become effective until new Access token is issued. In most cases this is not big issue, because Access tokens are short-lived. Otherwise go with the opaque token pattern.

Let’s see how can we implement the JWT token based authentication using Java and Spring, while trying to reuse the Spring security default behavior where we can. The Spring Security framework comes with plug-in classes that already deal with authorization mechanisms such as: session cookies, HTTP Basic, and HTTP Digest. Nevertheless, it lacks from native support for JWT, and we need to get our hands dirty to make it work.

This demo is currently using a MySQL database called user_db that’s automatically configured by Spring Boot. If you want to connect to another database you have to specify the connection in the application.yml file inside the resource directory. Note that hibernate.hbm2ddl.auto=create-drop will drop and create a clean database each time we deploy (you may want to change it if you are using this in a real project). Here's the example from the project:

gist:murraco/91a9fe41aa964efac500ec375d455d02

JwtTokenFilter

The JwtTokenFilter filter is applied to each API (/**) with exception of the signin token endpoint (/users/signin) and singup endpoint (/users/signup).

This filter has the following responsibilities:

Please ensure that chain.doFilter(request, response) is invoked upon successful authentication. You want processing of the request to advance to the next filter, because very last one filter FilterSecurityInterceptor#doFilter is responsible to actually invoke method in your controller that is handling requested API resource.

gist:murraco/5dae435e69e0a4265a060d7a96d7be55

JwtTokenFilterConfigurer

Adds the JwtTokenFilter to the DefaultSecurityFilterChain of spring boot security.

gist:murraco/dd74df7efcbd375361e4bad5fbd6a07b

JwtTokenProvider

The JwtTokenProvider has the following responsibilities:

MyUserDetails

Implements UserDetailsService in order to define our own custom loadUserbyUsername function. The UserDetailsService interface is used to retrieve user-related data. It has one method named loadUserByUsername() which finds a user entity based on the username and can be overridden to customize the process of finding the user.

It is used by the DaoAuthenticationProvider to load details about the user during authentication.

WebSecurityConfig

The WebSecurityConfig class extends WebSecurityConfigurerAdapter to provide custom security configuration.

Following beans are configured and instantiated in this class:

Also, inside WebSecurityConfig#configure(HttpSecurity http) method we'll configure patterns to define protected/unprotected API endpoints. Please note that we have disabled CSRF protection because we are not using Cookies.

gist:murraco/2e3c634329e689065b3c9158c6d0681c

As you can see from this post, thanks to Spring Boot and Spring Security, we can have a JWT authentication service up and running in record time. This is also incredibly easy to integrate into a Microservices ecosystem if we make use of Spring Cloud and the Netflix Stack: Eureka, Zuul, Ribbon and Hystrix (we’ll see more about this in future posts). In the meantime remember to check the code on GitHub to try it out or to add JWT authentication to your own project!

What am I missing here? Let me know in the comments and I’ll add it in! Thanks for reading!

Don’t miss our posts, follow us now on Twitter!