cloudnative wiki

README

5 min read

JWT

What is JWT?

JWT (JSON Web Token) is a compact, URL-safe means of representing claims to be transferred between two parties. The token is digitally signed, ensuring the integrity and authenticity of the information contained within it. JWTs are commonly used for authentication and authorization in web applications.

Structure of JWT

A JWT is composed of three parts:

  1. Header
  2. Payload
  3. Signature

These parts are separated by dots (.), forming a string like this: header.payload.signature.

1. Header

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

Example:

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

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

2. Payload

The payload contains the claims. Claims are statements about an entity (typically, the user) and additional metadata. There are three types of claims:

  • Registered claims: These are a set of predefined claims that are not mandatory but recommended to provide a set of useful, interoperable claims. Examples include iss (issuer), exp (expiration time), sub (subject), and aud (audience).
  • Public claims: These can be defined at will by those using JWTs but should be collision-resistant. They can be registered in the IANA JSON Web Token Registry or be defined using the URI format to avoid name collisions.
  • Private claims: These are custom claims created to share information between parties that agree on using them.

Example payload:

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

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

3. Signature

To create the signature part, you need to take the encoded header, the encoded payload, a secret, and the algorithm specified in the header, then sign that.

For example, if you want to use the HMAC SHA256 algorithm, the signature will be created like this:

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

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

Example JWT

An example of a complete JWT might look like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

How JWT Works

  1. User logs in: When a user successfully logs in using their credentials, a JWT is generated by the authentication server.
  2. JWT is sent to the client: The token is sent back to the client and stored locally (usually in localStorage or a cookie).
  3. Client sends JWT on subsequent requests: When the client makes an API request to a protected route, it includes the JWT in the Authorization header using the Bearer schema.
  4. Server validates JWT: The server verifies the token’s signature using the secret key. If the token is valid, the server processes the request. If not, it rejects the request.

Benefits of JWT

  • Compact: Because of their small size, JWTs can be sent through URLs, POST parameters, or inside HTTP headers.
  • Self-contained: The payload contains all the required information about the user, avoiding multiple database queries.
  • Security: JWTs can be signed to ensure the authenticity of the token and encrypted to ensure the confidentiality of the claims.

JWT Claims

JWT claims are pieces of information asserted about a subject. They provide additional context about the token and the entity it represents. Claims are typically included in the payload part of the JWT. Here are some common types of claims:

Registered Claims

These are predefined claims that provide a standardized way to communicate information. Some of the most commonly used registered claims include:

  • iss (Issuer): Identifies the principal that issued the JWT.
  • sub (Subject): Identifies the subject of the JWT (the user or system the token represents).
  • aud (Audience): Identifies the recipients that the JWT is intended for.
  • exp (Expiration Time): Identifies the expiration time on or after which the JWT must not be accepted.
  • nbf (Not Before): Identifies the time before which the JWT must not be accepted.
  • iat (Issued At): Identifies the time at which the JWT was issued.
  • jti (JWT ID): Provides a unique identifier for the JWT.

Public Claims

These claims can be defined by anyone using the JWT but should be registered in the IANA JSON Web Token Registry or use a collision-resistant name. Examples might include:

  • email: The email address of the user.
  • role: The role of the user within an application.

Private Claims

These are custom claims created to share information between parties that agree on using them. They are not registered or standardized and can be anything that the application needs.

Example of JWT Claims

Here’s an example of a payload with various claims:

{
  "iss": "https://your-domain.com/",
  "sub": "1234567890",
  "aud": "your-audience",
  "exp": 1615327890,
  "iat": 1615231490,
  "name": "John Doe",
  "admin": true,
  "email": "john.doe@example.com"
}

In this example:

  • iss is the issuer of the token.
  • sub is the subject or the user ID.
  • aud is the intended audience.
  • exp and iat are the expiration and issued-at times, respectively.
  • name, admin, and email are custom claims that provide additional information about the user.

“https://x.com/alexxubyte/status/1680955830504660995?s=20”

“https://x.com/AmigosCode/status/1714315937589993881?s=20”

Graph View