JWTs

This post is a quick and dirty introduction to JWTs. Honestly, there are better resources out there to learn about JWTs. See the references section below. These are just some of my own, fairly hastily written, notes…

Introduction

JWTs, pronounce jots, are Json Web Tokens. You can think of a JWT simply as a bucket of information that you an trust.

More formally:

“JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.” (from https://jwt.io/)

 

“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.” (from https://jwt.io/introduction/)

Structure

Payload

In JWT nomenclature, this “bucket” I referred to is called the payload but also referred to as the “claims”, and is in JSON format.

For example:

{
“userId”: “b08f86af-35da-48f2-8fab-cef3904660bd”
}

In this simple example, we only have a single “claim”,  but you can have as many claims as you like. There are several standard claims, including:

• Issuer (iss) – identifies principal that issued the JWT;
• Subject (sub) – identifies the subject of the JWT;
• Expiration time (exp) – the expiration time of the JWT;
• (see more at https://en.wikipedia.org/wiki/JSON_Web_Token#Standard_fields)

 

The payload/claims are then wrapped with a header and signature, separate by periods:

header.payload.signature

Header

The header usually consists of just two parts

1. the type of the token, which is JWT (is it ever anything else!?)
2. The hashing algorithm being used, e.g. HMAC or RSA, such as HMAC-SHA512 or RSA-SHA256 (see complete list at https://tools.ietf.org/html/rfc7518#section-3)

For example:

    {
      "typ": "JWT",
      "alg": "HS256"
    }

This JSON is then Base64Url encoded to form the first part of the JWT.

Signature

The signature is a combination of the header and payload, in combination with a secret. More specifically, it uses this algorithm (from https://jwt.io/introduction):

    HMACSHA256(
        base64UrlEncode(header) + "." +
        base64UrlEncode(payload),
        secret)

When something receives a JWT, it can recreate the signature using this algorithm. If the signature matches the one in the JWT, you can be confident that the JWT has not been modified (hence the “bucket of information that you can trust”).

Note that this requires both the sender (issuer) and receiver (consumer) to have access to the secret.

Whole JWT

All 3 components are then combined to create the JWT, in the header.payload.signature format mentioned earlier.

More specifically, we take the base64url encoded versions of the header and of the payload, and the signature we calculated, and separate by periods. For example:

// JWT Token
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM

 

Why use JWTs?

JWT reduce the need to store state on the server. They allow two entities (e.g. client & server, or 2 microservices) to pass information and validate its integrity.

They allow you to confirm the identity of a caller. If you receive a JWT with the userID of 123, you can safely trust that this on on behalf of user 123

They are an alternative to session IDs. Instead of passing an opaque session ID that then need to be looked up server side, e.g. in a database, and translated into something more meaningful (e.g. a user ID, and the permissions that user has), we instead pass a JWT that contains the information. Note however, that there are arguments both for and against using JWTs as a substitute for session IDs, e.g. https://dzone.com/articles/jwtjson-web-tokens-are-better-than-session-cookies and https://developer.okta.com/blog/2017/08/17/why-jwts-suck-as-session-tokens

 

Security

Are JWTs secure?

JWTs are signed and encoded, but they are not encrypted. As a result, JWTs do not guarantee any security for sensitive data.

JWTs still require CSRF prevention.

 

References

• https://jwt.io
• https://jwt.io/introduction
• https://developer.okta.com/blog/2017/08/17/why-jwts-suck-as-session-tokens
• https://www.slideshare.net/dblevins1/2016-javaone-deconstructing-rest-security
• https://stormpath.com/blog/jwt-the-right-way

Tags: jsonwebtokens, jwt, jwts