Simple metaphor to easily understand and remember how token-based authentication works
In this modern era, software is often using token-based authentication so that parts of the software can be isolated as stateless processes.
Although this is a great practice and allows for highly scalable software, it increases the complexity for us, front-end developers, because we now also have to understand the nitty-gritty of token-based authentication.
In this article I share with you a powerful metaphor I use to easily remember and explain how token-based authentication works.
The goal of this article is NOT to discuss technical implementation details of token-based authentication such as JWT.
The goal of this article is to make you understand and communicate the underlying concepts of token-based authentication in such a way that you can easily remember them and reason about them with non-technical people (e.g. your management) when needed.
The metaphor
Consider the following metaphor:
- think of your application as a hotel
- think of your authentication service as the hotel reception
- think of your application resources as hotel rooms
- think of an access token as a hotel key card
- think of credentials as your passport
Now carefully read the next few paragraphs, allowing your brain to map the authentication concepts to some simple scenarios your are already familiar with.
In just a few minutes, you will never forget the mechanics of token-based authentication again for the rest of your life!
So let's get started!
Imagine that you arrive at a hotel. You can freely enter the public parts of the hotel, if there are any, such as the entrance hall and public bathroom.
Imagine that you visit a modern web application. You can freely view the public homepage.
However, to access restricted resources such as your room and the fitness area, you need a personal key card.
However, to visit your personal account area that requests private data from the API, you need a token.
So you head over to the reception and show your passport. The receptionist checks your credentials and provides you with a key card.
So you head over to the sign-in page and enter your credentials. The authentication service checks your credentials and provides you with a token.
Using your key card, you can now enter your room and the fitness area.
Using your token, you can now request data from the API.
Your key card === you
As far as the hotel is concerned, whenever your key card is used, it will assume it is you that is holding it.
As far as the application or API is concerned, when your token is used, it will assume it is you who is making the request.
If you give your key card to someone else, the door lock will think that it is you who requests access and thus grant access.
If you give your token to someone else, the API will think that it is you who performs the request and thus return your private data.
Do not take this lightly. Do not share your key card and make sure you don't lose it.
Never share your token and make sure no one can see it!
Your key card may expire
The receptionist has configured your key card to expire automatically.
The authentication service has configured your token to expire automatically.
After a predetermined period of time your key card is no longer valid and you are no longer able to access your room and the fitness area.
After a predetermined period of time your token is no longer valid and you are no longer able to access your private data.
So even if you keep the key card in your pocket and come back to the hotel at a later time, it will no longer provide access to restricted resources.
So even if the token is still in your session, if you come back later, the API will no longer provide you with your private data.
Big consequences when you lose your key card
When you lose your key card, the person who finds your key card can enter your room.
When you lose your token, the person who has a copy of your token is able to access your private data.
The finder would have to know which room to access, but if he or she does, your room's door lock will think it is you and provide access to the finder.
The finder would have to know the endpoint URL's, but if he or she does, the API will think it is you and return your private data.
Luckily, some hotels have door locks that are equipped with a mechanism that is able to verify whether or not a key card has been invalidated before access is granted.
Luckily, some applications have a mechanism to verify whether or not a token has been invalidated before access is granted.
Such a revoking mechanism works roughly like this:
- when you lose your key card, you notify the receptionist
- the receptionist deactivates the lost key card
- the door locks are made aware of the deactivated key card and deny further access
If a door lock is not aware that your key card was deactivated, it will think all is okay and grant access.
If the API is not aware that your token was deactivated, it will think all is okay and return your private data.
Even though hotel security is much tighter with locks that have a mechanism to handle invalidated key cards, the finder is still able to access your room from the moment you lose your key card till the moment that the door lock is aware the key card has been invalidated.
Even though application security is much tighter with a mechanism to handle invalidated tokens, the finder is still able to access your private data from the moment you lose your token till the moment that they API is aware the token has been invalidated.
Different types of key cards
A hotel may carry different types of key cards.
An application may support different types of tokens.
For example: you may have a key card that only allows access to your own room and the fitness area. In contrast the cleaning crew may have a key card that allows access to all rooms.
For example: you may have a token that only allows access to your private data. In contrast an administrator may have a token that allows access to all data.
Your key card is digitally signed
To make sure key cards cannot be tampered with, all key cards contain a digital signature.
To make sure tokens cannot be tampered with, all tokens contain a digital signature.
As soon as you try to use a corrupted key card, the hotel is be able to detect your malicious intent and deny access.
As soon as you try to use a corrupted token, the application is able to detect your malicious intent and deny access.
In summary
Although actual implementations of token-based authentication systems may vary, think about token-based authentication as visiting a hotel and:
- think of the hotel as your application
- think of the hotel reception as your authentication service
- think of the hotel rooms as your application resources
- think of your hotel key card as your access token
- think of your passport as your credentials
This simple hotel key card metaphor has helped me tremendously before with explaining token-based authentication to people that had never heard of it before — even non-technical people.
May it now benefit you too.
Have a great one!
PS: If you are interested in learning more about the technical details of token-based authentication, make sure to check out these articles: