JWT Structure and Claims

JSON Web Tokens (JWTs) might look like long, random strings, but they have a very clear and organized structure.

A JWT is composed of three distinct parts, each separated by a dot (.):

• Header
• Payload
• Signature

Think of it like a sealed letter: the header is information about the letter itself, the payload is the message inside, and the signature is the wax seal proving its authenticity.

The Header is the first part of a JWT. It's a JSON object that contains metadata about the token itself, primarily telling us what algorithm was used to sign the token.

It typically includes two key elements:

• alg (Algorithm): Specifies the cryptographic algorithm used for signing the token (e.g., HS256 for HMAC SHA-256, RS256 for RSA SHA-256).
• typ (Type): Indicates the type of token, which is almost always JWT.

Here's what a typical JWT header looks like as a JSON object:

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

Before being included in the JWT string, this JSON object is Base64Url encoded. This process converts the JSON into a web-safe string.

The Payload is the second part of the JWT and is arguably the most important. It's also a JSON object, but this one contains the actual data, known as "claims."

Claims are statements about an entity (usually the user) and additional data. They are essentially key-value pairs that carry information such as:

• User ID
• User roles or permissions
• Token expiration time

JWTs define a set of "standard claims" that are recommended for common use. While optional, using them helps ensure interoperability.

Some common standard claims include:

• iss (Issuer): Identifies the principal that issued the JWT (e.g., auth.example.com).
• sub (Subject): Identifies the principal that is the subject of the JWT (e.g., a user ID like user123).
• exp (Expiration Time): The time after which the JWT MUST NOT be accepted for processing. It's a Unix timestamp.
• iat (Issued At): The time at which the JWT was issued. Also a Unix timestamp.
• aud (Audience): Identifies the recipients that the JWT is intended for (e.g., api.example.com).

In addition to standard claims, you can include any custom claims in the payload that are relevant to your application.

This allows you to store application-specific data directly within the token, such as:

• User-specific roles (e.g., admin, editor)
• Permissions (e.g., read:product, write:order)
• Unique identifiers specific to your system

Keep custom claims concise to minimize the overall token size, which helps with performance.

Here's an example of a JWT payload containing both standard and custom claims:

{
  "sub": "user123",
  "name": "Alice Smith",
  "roles": ["admin", "editor"],
  "iat": 1678886400,
  "exp": 1678890000
}

Like the header, this JSON object is also Base64Url encoded before becoming part of the full JWT string.

The Signature is the third and final part of a JWT. It's critical for security, as it serves two main purposes:

1. Integrity: Verifies that the token hasn't been tampered with since it was issued.
2. Authenticity: Confirms that the token was indeed created by the expected issuer.

Without a valid signature, the token should be considered invalid and untrustworthy.

The signature is created by taking the Base64Url encoded header, the Base64Url encoded payload, and a secret key, then running them through the cryptographic algorithm specified in the header.

Conceptually, it works like this:

signature = Algorithm( 
  Base64Url(header) + "." + 
  Base64Url(payload), 
  secret_key
)

The resulting signature is then also Base64Url encoded and appended to the JWT string, completing its three-part structure.

Test your knowledge on JWT claims!

Great job! You now understand the fundamental structure of a JSON Web Token.

• The Header contains metadata about the token, including the signing algorithm and type.
• The Payload carries the actual data in the form of "claims," which can be standard (like iss, sub, exp) or custom.
• The Signature is a cryptographic hash that ensures the token's integrity and authenticity, preventing tampering and verifying the sender.

Understanding these three distinct parts is crucial for effectively working with and securing applications using JWTs.