Now let’s talk about one of the hottest topics for web developers. In this article, the goal is to outline the fundamentals of JSON Web Tokens (JWT). Recently learning about this tool to create my newest project
trvce. I have applied JWT’s in my project to be able to check the authenticity of a user.
First off, let us start with the definition of the JSON Web Token.
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 or ECDSA.
Now, let us go over a simple use case for the JSON Web Token. Let’s say you are creating a simple web application. In this web application you would like to have a
REST API, and a web app, which will interact with the web server.
Now now… I know my drawing is a little ridiculous, but I think it’s worth a million bucks!
Some notes about the image:
1. The user will sign into the application, for example you are logging into facebook. This is why the arrow is passed on from the stick person’s hand.
2. In the auth server, we will check to see if we would like to authentication you, if we do, we’re onto step three. The auth server implements the JWT into our heads, we are ready to make an API call.
3. Now, we make an API call to the web server. Usually when you get any data from a web app, such as a user’s data on Facebook, this is data which you received from the API call. Here, the REST API / web server will check to see if your JWT is valid, if it is we move onto step four.
4. Web server verified the JWT, processes the API call, and returns the data to the user, and we are able to render that beautiful user profile page on the front end! See, now the diagram makes sense.
Now that you have a basic idea of how the JWT is used, let us process the JWT, and really dig deep into the dirt! The JWT is created from three subsections, the header, payload and the signature.
header.payload.signatureHere is a an example of what a raw JWT looks like:
eyJhbJciOiJIUzI1YiIsInR5cCI6IkpXVYJ9.
eyJzdWIiOiI1Yzk2YWVjNzY2OTljNTM3EWVtODk4M2IiLCJpYXQiOjP1NTYzOTM5MjR9.Nis1XjrFwO68Chb8YiGSemrY-8NJqyaTuGUFjb5gO58
What do you mean HEADER???
Well, the header contains the following information:
The type of the token.
The signing algorithm being used. (HMAC SHA256 or RSA)
Typically, which in the end will look something like this:
{
“alg”: “HS256”,
“typ”: “JWT”
}After this, the header is then
Base64Urlencoded to form the first part of the JWT, known as the HEADER.
// When the header is generated, it looks something like this:
eyJhbGciOiJIUzI1NkIsInR5cCI6IkpYVCJ9Okay, so if that’s the HEADER… then what is the PAYLOAD?
The second part of the JWT, the
payload, contains the claims. The claims are the statements about the object, typically the user, and additional data. Usually we store the USERID of the user making the API call in the payload.
Now there are three claims:
registered, public, and private claims.
Registered: A set of predefined claims, not mandatory but recommended. Some include iss (issuer), exp (expiration time), sub (subject), aud (audience), and others. Feel free to read more here.
Public: These are custom claim names which are required to be collision resistant.
Private: These are custom claims created to share information between parties agreeing on using them. They are neither registered or public claims.
For our example, you don’t really need to know about these, if you are interested. I will leave some articles to read at the bottom of the entry.
Now an example payload can look something like this:
{
“sub”: “0987654321”,
“name”: “Michael O'Connor”,
“admin”: true
}Just like the header, the payload is then
Base64Urlencoded to form the second part of the JWT, known as the PAYLOAD.
// When the payload is generated, it looks something like this:
eyJzdWIiOiI1Yzk2YWVjNzY2OTljNTM3EWVtODk4M2IiLCJpYXQiOjP1NTYzOTM5MjR9Please do not store secret information in the payload or header of the JWT unless it is encrypted. This information is readable by anyone.
What do you mean by SIGNATURE?
No… not the same signature you use to sign your personal docmuents.
The signature of a JWT is esentially the algorithm which Base64Url encodes the header and the payload. The algorithm then joins these encoded strings together with a period (.)
Let’s go over some quick pseudo code:
// combine the two base64urlencoded strings, separate by period.
signatureData = base64UrlEncode(headerObject) + “.” base64UrlEncode(payloadObject)secret = "SOME_RANDOM_STRING"// use our hashing algorithm to combine header, payload and secret.
hashedData = hash(signatureData, secret)// base64urlecode the signature
signature = base64UrlEncode(hashedData)In the example, you can see that we used a secret. The secret is a random string which only YOU are allowed to see. If you change this string, it will completely change the JWT output.
Now in the very last line of the example, you can see we
Base64Urlencoded the hashed data, which produces the signature.
// When the signature is generated, it looks something like this:
Nis1XjrFwO68Chb8YiGSemrY-8NJqyaTuGUFjb5gO58Finalizing the JWT
Having generated the Header, the Payload, and the Signature, we are now ready to create the JWT.
Remember:
header.payload.signatureSo we want to take the
Base64Urlencoded header, payload and signature and put them together.
JWT = header + “.” + payload + “.” + signatureconsole.log(JWT)
>>eyJhbJciOiJIUzI1YiIsInR5cCI6IkpXVYJ9.eyJzdWIiOiI1Yzk2YWVjNzY2OTljNTM3EWVtODk4M2IiLCJpYXQiOjP1NTYzOTM5MjR9.Nis1XjrFwO68Chb8YiGSemrY-8NJqyaTuGUFjb5gO58Now, why don’t you try and create your own JWT using
jwt.io.
After creating this JWT, the web server will check to make sure the user has proper authentication to retrieve data from the REST API.
Thanks for reading.