Introduction to JWT

What are tokens

Tokens are the process of substitution of sensitive data with a non-sensitive equivalent. A token has no exploitable meaning and is just an identifier that can be mapped back to sensitive data.

What is JWT

JSON Web Tokens (JWT), pronounced ‘jot’, is a token standard that allows information to be easily and securely transferred around using a self-contained JSON Object.

Self Contained: The JWT payload can contain extra information avoiding the need to query a database i.e. to retrieve a user’s name
Easy to pass around: Because the JSON object is small in size it can easily be sent in requests via a HTTP Header.

Other types of tokens

Opaque tokens - Are typically an identifier to information persisted on a server. Because it is just a pointer to information a request to the server is required to validate it.

What does a JWT look like?

A JWT is made up of three parts separated by a (.)
i.e. aaaaaaaa.bbbbbbbb.cccccccc

Part 1 - Header

The header consists of two parts

The type of token, which is JWT
The hashing algorithm used For example:
```
{
"typ": "JWT",
"alg": "HS256"
}
```
This JSON is Base64 Url encoded to make up the first part of the JWT.
```
ewogICAgInR5cCI6ICJKV1QiLAogICAgImFsZyI6ICJIUzI1NiIKfQ
```

Part 2 - Payload

The payload consists of the claims.

Claims

Claims are statements that are made about an entity (in most cases a user). A claim can be one of three types:

Reserved claims:
These are claims that have a reserved name and although they are not mandatory they are recommended.
- iss Issuer
- sub Subject,
- aud Audience
- exp Expiration Time
- nbf Not Before
- iat Issued At
- jti JWT ID
Public claims: These claims can be defined be ourselves i.e. name, email. It is recommended they should be defined in the IANA JSON Web Token Registry or defined as a URI to avoid collisions.
Private claims: These are custom claims agreed between the producer and consumer that are not reserved or public claims.

Example:

{
  "iss": "craigpickles.com",
  "exp": 1300819380,
  "email": "[email protected]"
}

This JSON is Base64 Url encoded to make up the second part of the JWT.

ewogICJpc3MiOiAiY3JhaWdwaWNrbGVzLmNvbSIsCiAgImV4cCI6IDEzMDA4MTkzODAsCiAgImVtYWlsIjogInRlc3RAdGVzdC5jb20iCn0

Part 3 - Signature

The final part of the JWT is the signature. This takes the first and second parts and creates a hash using the specified hashing algorithm and a secret that only the server knows.

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

The signature is used to verify that the message hasn’t changed.

Now we have our completed JWT.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjcmFpZ3BpY2tsZXMuY29tIiwiZXhwIjoxMzAwODE5MzgwLCJlbWFpbCI6InRlc3RAdGVzdC5jb20ifQ.9CkKadbcOZHPGrJWxASu10pWsKw4ATkl9XQ4VXV61uU

How do you use a JWT

When a user successfully authenticates themselves they are provided with a JWT which is stored locally to be used on any future requests. The JWT is typically sent in the Authorization header using the Bearer schema i.e.

Authorization: Bearer {token}

Protected server resources will check the authorization header to see if the user is allowed to access it instead of using a more traditional method of the user’s authenticated state being stored on the server.

When to use JWT

Authentication
The most common use for JWT is authentication, where as described above the token is included in all future requests allowing access to services or resources. JWT can also be used cross-domain making it great for Single Sign On.
Non-sensitive information exchange JWTs are a great way of sending information between parties as they are signed allowing all parties to verify the information hasn’t been tampered with. Using a public/private key both the send and also the recipient can confirm the payload is correct.

Things to consider

Unlike sessions which are stored on a server JWT tokens cannot be invalidated. By design, they are valid until they expire.

Therefore it is recommended that JWTs are made short-lived and only valid for a few minutes. If a token is expected to be used for a longer period an opaque refresh token should be provided allowing the client to request a new JWT. The opaque refresh token, because it is managed on the server, can restrict access to the client once the already provided JWT has expired.

Useful links

Introduction to JWT