Understanding JSON Web Tokens (JWT)

JSON Web Tokens (JWT), pronounced "jot", are a compact, URL-safe means of representing claims to be transferred between two parties. They are widely used in modern web development for authentication and information exchange.

What is a JWT?

A JWT is a string of characters that contains information (claims) about an entity (typically a user) and is signed by the issuer. Because it is signed, the recipient can verify that the content has not been tampered with.

If you have a JWT string and want to see what's inside, check out our JWT Decoder Tool.

The Structure of a JWT

A JWT consists of three parts separated by dots (.):

1. Header
2. Payload
3. Signature

Therefore, a JWT typically looks like this:

xxxxx.yyyyy.zzzzz

1. Header

The header usually consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256 or RSA.

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

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

2. 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 data.

There are three types of claims:

• Registered claims: Predefined claims which are not mandatory but recommended (e.g., iss (issuer), exp (expiration time), sub (subject)).
• Public claims: These can be defined at will by those using JWTs.
• Private claims: Custom claims created to share information between parties that agree on using them.

Example payload:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022
}

This is also Base64Url encoded to form the second part.

[!IMPORTANT] Do not put secret information in the payload or header elements of a JWT unless it is encrypted. JWTs are signed (tamper-proof) but not encrypted (visible to anyone).

3. Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the 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:

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

How JWTs Work (Verification)

In authentication, when the user successfully logs in using their credentials, a JSON Web Token will be returned. Since tokens are credentials, great care must be taken to prevent security issues. In general, you should not keep tokens longer than required.

Whenever the user wants to access a protected route or resource, the user agent should send the JWT, typically in the Authorization header using the Bearer schema.

Authorization: Bearer <token>

The server's protected routes will check for a valid JWT in the Authorization header, and if it's present, the user will be allowed to access protected resources.

Security Best Practices

1. Keep it secret: The signing key should be kept secret on the server. If an attacker gets your key, they can forge tokens.
2. Use specific algorithms: Don't allow the client to decide the algorithm (e.g., avoid the "none" algorithm attack). Explicitly verify using HS256 or RS256.
3. Validate Expiration: Always check the exp claim to ensure the token hasn't expired.
4. HTTPS: Always transmit JWTs over HTTPS to prevent interception.

JSON vs JWT

If you are new to the JSON format itself, you might want to read our article on Understanding JSON first. JWT is built on top of JSON, using it as the format for both the header and the payload.

Summary

• Compact: Smaller than XML, making it good for mobile environments.
• Self-contained: The payload contains all the required information about the user, avoiding the need to query the database more than necessary.
• Secure: Can be signed and encrypted.

Ready to inspect a token? Go to the JWT Decoder Tool and paste your token to see the structure in action.