JWT - If your name's not on the list...

I love a good metaphor when learning a new topic. I recently started using JSON Web Tokens (JWT) to protect an API making calls to a database. I imagined that database as a place where people want to get into, but only a selected few are allowed. How can you make sure only the right people are allowed in? It sounds like you need a bouncer!

Our Scenario

Let’s say our users are people on a night out. The database, holding private data, is an exclusive nightclub. Everyone wants in but, as you may have heard before, “If your name’s not on the list, you're not coming in!”

How this Works

Luckily, you’re in with the right people and your name is on the list. You approach the bouncer, flash your photo ID and you’re in. You have free access to the nightclub. There are certain places you can’t go, like the kitchens or the VIP section, but otherwise, you’re in for a great night. What if you need to leave? Will you be allowed back in? Will you have to go through the whole vetting process all over again?In this nightclub, they use tokens (like a stamp on your hand) to show that you are allowed back in. You can come and go as you please for an amount of time. With the token, security trusts that you are who you say you are. They won’t check again – straight in you go.

Guest Passes, what Types?

There are different types of tokens, just like there are different types of passes at a concert. Let’s say you are very important indeed, so you are given a VIP pass token when your credentials are initially checked. Not only can you access the dance floor and bar, you can also access the VIP area. What a privilege!

Unsavoury Guests

Unfortunately, there are unsavoury characters who want to get into the nightclub. Their names are definitely not on the list! Somehow, they’ve managed to intercept a VIP and either take their token or make a copy of it. As far as security is concerned, the person holding this token is a VIP so they are given access to the nightclub.This isn’t secure and something had to be done. A token now comes with a timeout. Every night, the tokens are changed. If you try to use an old, out-of-date token you will not be allowed in. If someone manages to get a token before it times out, they could still get into the nightclub. There needs to be more stringent checks.The nightclub decides to introduce JWT Tokens. To get a token, you must hold a secret key as well as your credentials. This secret key is used to create another encrypted password with a signature.Anyone can see the encrypted password. When a token is used, a quick check is done on this visible encrypted password. The bouncer is now able work backwards to calculate the secret key by looking at the encrypted password. If the secret key matches the one the nightclub uses, the bouncer knows that this is a valid token.

So ...

(If you haven’t twigged it by now, the bouncer is an Authorisation API, and the nightclub has the sensitive data. A token can contain “Claims” which hold more details about the user who wants the data (aka. the guest who wants to gain entry to the nightclub). One claim could be that this is an admin user and should have access to all endpoints (aka. a VIP guest who should have access to free drinks)).

To Summarise

While JWT doesn’t guarantee security, they can reassure you that the tokens are authentic and not counterfeit. Hopefully this metaphor can help you understand using JWT for website security and also give you flash backs to horrible memories of queuing outside clubs!