JSON Web Tokens


JSON Web Tokens (JWT) is a compact URL-safe means of representing claims to be transferred between two parties. The claims in a JSON Web Tokens are encoded as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or MACed and/or encrypted.

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. JSON Web Tokens can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA.

Let's explain some concepts of this definition further:

  • Compact: Because of its size, it can be sent through an URL, POST parameter, or inside an HTTP header. Additionally, due to its size its transmission is fast.
  • Self-contained: The payload contains all the required information about the user, to avoid querying the database more than once.

The Goal#

JSON Web Tokens goal is not to hide data, but to prove your identity (Authentication) to the server. Anyone can decode the token, but they can't create fake tokens because that requires the Private Key. The server will throw an exception when attempting to decode a fake token, since no one knows your private key (I hope!).

When should you use JSON Web Tokens?#

There are some scenarios where JSON Web Tokens are useful:

JSON Web Tokens structure?#

JSON Web Tokens consist of three parts separated by dots (.), which are:
  • Header
  • Payload
  • Signature

Therefore, a JWT typically looks like the following.


JSON Web Tokens Header#

Public Header values are Registered within the JSON Web Signature and Encryption Header Parameters Registry

The header contains the metadata for the token and at a minimal contains the type of the signature and/or encryption algorithm:

For example:
  "typ": "JWT"
  "alg": "HS256",
  "cty": "arbitrary"
Then, this JSON is Base64Url encoded to form the first part of the JWT.

JSON Web Tokens Payload#

The second part of the token is the payload, which contains the claims. Claims are statements about an entity (typically, the user) and additional metadata.

There are three types of claims:

  • Reserved claims: These are a set of predefined claims, which are not mandatory but recommended, thought to provide a set of useful, interoperable claims. Some of them are:
  • Public claims: These can be defined at will by those using JWTs. But to avoid collisions they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision resistant namespace.
  • Private claims: These are the custom claims created to share information between parties that agree on using them.

JSON Web Token Claims#

JSON Web Token Claims are registered names.
Notice that the claim names are only three characters long as JWT is meant to be compact.

An example of payload could be:

  "sub": "1234567890",
  "name": "John Doe",
  "admin": true

The payload is then Base64Url encoded to form the second part of the JSON Web Tokens

JSON Web Tokens Signature#

To create the signature part you have to take the:
  • encoded header
  • encoded payload
  • a secret
  • algorithm specified in the header
and sign that.

For example if you want to use the HMAC SHA256 algorithm, the signature will be created in the following way.

  base64UrlEncode(header) + "." +
The signature provides the same assurances as any Digital Signature

JSON Web Tokens Profiles#

THere are some JSON Web Tokens "Profiles" that more narrowly define the contents of JSON Web Tokens.

How to Secure JSON Web Tokens[3]#

There are a lot of libraries out there that will help you create and verify JSON Web Tokens, but when using JWT’s there still some things that you can do to limit your security risk.

First Always verify the signature before you trust any information in the JWT. This should be a given, but we have recently seen security vulnerabilities in other company’s JWT frameworks. One gotcha that we have seen recently is around the JWT spec that allows you to set signature algorithm to ‘none’. This should be ignored if you expect the JWT to be signed. Put another way, if you are passing a secret signing key to the method that verifies the signature and the signature algorithm is set to ‘none’, it should fail verification.

Second_ Secure the secret signing key used for calculating and verifying the signature. The secret signing key should only be accessible by the issuer and the consumer, it should not be accessible outside of these two parties.

Third Do not use any sensitive data in a JWT that is not encrypted. JWT tokens are usually signed to protect against manipulation (not encrypted) so the data in the claims can be easily decoded and read. For example, you should not include a user’s address in a JWT. You could provide a link to the user’s record or some other identifier that is opaque and have your application look up the information. If you do need to store sensitive information in a JWT, check out JSON Web Encryption (JWE).

If you worried about replay attacks, include a nonce (jti claim), expiration time (exp claim), and creation time (iat claim) in the claims.

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants#

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants is described in RFC 7523

More Information#

There might be more information for this subject on one of the following: