Introduction to JSON Web Tokens

What is JSON Web Token?

JSON Web Token (JWT) is a widely-adopted open standard (RFC 7519) that facilitates secure information exchange between parties as a JSON object. This method ensures data integrity and authenticity through digital signatures. JWTs can be signed using a secret key with the HMAC algorithm or a public/private key pair with RSA or ECDSA.

While JWTs can be encrypted to ensure confidentiality between parties, this guide focuses on signed tokens. Signed tokens validate the integrity of the claims they contain, whereas encrypted tokens conceal these claims from unauthorized parties. When using public/private key pairs for signing, the signature guarantees that only the holder of the private key has signed the token.

When should you use JSON Web Tokens?

JSON Web Tokens (JWTs) are highly versatile and can be used in various scenarios:

• Authorization: JWTs are commonly used for authorization purposes. After a user logs in, each subsequent request includes the JWT, granting access to routes, services, and resources permitted by the token. JWTs are ideal for Single Sign-On (SSO) due to their small size and cross-domain usability.
• Information Exchange: JWTs provide a secure method for transmitting information between parties. By signing JWTs with public/private key pairs, you can ensure the authenticity of the sender and the integrity of the data, as the signature is based on the header and payload.

Understanding the Structure of JSON Web Tokens

JSON Web Tokens (JWTs) are composed of three distinct parts separated by dots (.), which include the Header, Payload, and Signature. This compact structure makes JWTs easy to transmit and verify.

• Header
• Payload
• Signature

A typical JWT looks like this:

Header

The header usually consists of two parts: the type of token (JWT) and the signing algorithm (e.g., HMAC SHA256 or RSA).

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

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

Payload

The payload contains the claims, which are statements about an entity (typically, the user) and additional data.

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

The payload is then Base64Url encoded to form the second part of the JWT.

Signature

To create the signature, you combine the encoded header, the encoded payload, a secret, and the algorithm specified in the header, and then sign it.

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

The signature ensures that the token has not been altered and, in the case of tokens signed with a private key, verifies the sender's identity.

How do JSON Web Tokens work?

When a user logs in successfully, an authentication server issues a JSON Web Token (JWT). This token, which acts as a credential, should be handled with care to avoid security risks. It is advisable to store tokens only for the necessary duration.

To access protected routes or resources, the user agent sends the JWT in the Authorization header using the Bearer schema. The header format is as follows:

This method can serve as a stateless authorization mechanism. The server checks for a valid JWT in the Authorization header to grant access to protected resources. If the JWT contains the required data, it may reduce the need for database queries, although this is not always the case.

Using the Authorization header to send the token avoids Cross-Origin Resource Sharing (CORS) issues, as it does not rely on cookies.