JSON Web Token (JWT)

A JSON Web Token (JWT) is a secure way to send information between a client and a server. It is mainly used in web applications and APIs to verify users and prevent unauthorized access. A JWT is JSON data secured with a cryptographic signature.

The signing can be done using these cryptographic methods:

• HMAC (Hash-based Message Authentication Code)
• RSA or ECDSA (Asymmetric cryptographic algorithms)

JWT Structure

Here is the structure of a JWT:

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

Header. Payload. Signature

1. Header: Contains metadata about the token, such as the algorithm used for signing.
2. Payload: Stores the claims, i.e., data being transmitted.
3. Signature: Ensures the token's integrity and authenticity.

1. Header

The header contains metadata about the token, including the signing algorithm and token type here metadata means data about data.

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

• alg: Algorithm used for signing (e.g., HS256, RS256).
• typ: Token type, always "JWT".

Base64Url Encoded Header

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

2. Payload

The payload contains the information about the user also called as a claim and some additional information including the timestamp at which it was issued and the expiry time of the token.

{
    "userId": 123,
    "role": "admin",
    "exp": 1672531199
}

Common claim types:

• iss (Issuer): Identifies who issued the token.
• sub (Subject): Represents the user or entity the token is about.
• aud (Audience): Specifies the intended recipient.
• exp (Expiration): Defines when the token expires.
• iat (Issued At): Timestamp when the token was created.
• nbf (Not Before): Specifies when the token becomes valid.

Base64Url Encoded Payload

eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNzA4MzQ1MTIzLCJleHAiOjE3MDgzNTUxMjN9

3. Signature

The signature ensures token integrity and is generated using the header, payload, and a secret key. In this example we will use HS256 algorithm to implement the Signature part

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

Example Signature:

SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

4. Final JWT token

After all these steps the final JWT token is generated by joining the Header, Payload and Signature via a dot. It looks like as it is shown below.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNzA4MzQ1MTIzLCJleHAiOjE3MDgzNTUxMjN9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

How JWT token Works?

This diagram explains how JWT (JSON Web Token) authentication works. Here are the key steps in simple points:

• Login Request: The user logs in through the client application (e.g., web or mobile app) by sending their credentials (username & password) to the server.
• Server Generates JWT: If the credentials are correct, the server generates a JWT token using a secret key.
• Returns JWT: The server sends the JWT back to the client application.
• Further Requests with JWT: For any subsequent requests, the client sends the JWT along with the request. The server verifies the JWT before granting access to protected resources.

Note: JWTs are primarily used for authentication and secure data exchange in web applications and APIs.

Security Considerations

When working with JWTs, keep these best practices in mind to ensure safe and reliable authentication:

• Use HTTPS: Prevent man-in-the-middle attacks by transmitting JWTs over HTTPS.
• Set Expiration Time: Prevent long-lived tokens that can be exploited.
• Use Secure Storage: Store JWTs securely (e.g., HttpOnly cookies instead of local storage).
• Verify Signature: Always validate the token's signature before trusting its content

Common Issues During Development with JWT

JWT errors often arise from mismatched details or token problems:

• JWT Rejected: The server could not verify the token. This can happen if the token has expired, the signature is invalid, or the claims do not match the expected details.
• Token Does Not Support Required Scope: The token does not include the permissions needed for the action. For example, it may allow only reading data, but the app requires write access.
• JWT Decode Failed: The token is not in the correct format or not properly encoded, so the client cannot read it.