JWT Decoder Tool

What is a JWT?

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

JWTs are heavily used in modern web applications, particularly in single-page applications (SPAs) and stateless architectures, for authentication and information exchange.

JWT Structure

A JSON Web Token consists of three parts separated by dots (.):

1. Header: Contains metadata about the type of token and the cryptographic algorithms used to secure its contents.
2. Payload (Claims): Contains the statements (claims) about an entity (typically, the user) and additional data.
3. Signature: 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.

When combined, these three parts typically look like this: xxxxx.yyyyy.zzzzz

1. The Header

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

Example Header JSON:

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

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

2. The 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, public, and private claims.

Registered claims: These are a set of predefined claims which are not mandatory but recommended, to provide a set of useful, interoperable claims. Some of them are:

• iss (Issuer): Who issued the token.
• exp (Expiration time): When the token expires.
• sub (Subject): Whom the token refers to.
• aud (Audience): Who the token is intended for.
• iat (Issued at): When the token was created.
• nbf (Not before): When the token becomes valid.

Public claims: These can be defined at will by those using JWTs. But to avoid collisions, they should be defined in the IANA JSON Web Token Registry or be defined as a URI that contains a collision-resistant namespace.

Private claims: These are the custom claims created to share information between parties that agree on using them and are neither registered or public claims.

Example Payload JSON:

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

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

Note that for signed tokens this information, though protected against tampering, is readable by anyone. Do not put secret information in the payload or header elements of a JWT unless it is encrypted.

3. The 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 this way:

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

The signature is used to verify the message wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

How JWT Authentication Works

1. User Login: The user provides credentials (e.g., username and password) to the authentication server.
2. Token Generation: If the credentials are valid, the server creates a JWT, signs it with a secret key, and sends it back to the client.
3. Token Storage: The client stores the JWT (usually in localStorage, sessionStorage, or an HttpOnly cookie).
4. Subsequent Requests: For every subsequent API request to a protected route, the client includes the JWT in the Authorization header using the Bearer schema: Authorization: Bearer <token>.
5. Token Verification: The server intercepts the request, verifies the JWT's signature and expiration. If valid, it grants access to the requested resources.

JWT Security Best Practices

When implementing JWTs, consider the following security best practices:

• Always Verify the Signature: Ensure your application validates the token's signature on the server-side before trusting the payload.
• Do Not Store Sensitive Data: The payload is only Base64Url encoded, not encrypted. Anyone who intercepts the token can read it. Never store passwords, Social Security numbers, or API keys in a JWT payload.
• Keep Tokens Short-Lived: Use the exp claim to limit a token's lifespan. Short expiration times (e.g., 15 minutes) minimize the window of opportunity if a token is compromised.
• Use Refresh Tokens: For long-lasting sessions, use short-lived access tokens (JWTs) paired with long-lived refresh tokens (opaque strings).
• Enforce Strong Algorithms: Do not allow the none algorithm. Use strong algorithms like RS256 (asymmetric) or HS256 (symmetric with a strong, long secret key).
• Validate iss and aud Claims: Ensure the token was issued by your trusted server and is intended for the specific application consuming it.

Common JWT Algorithms

Our tool detects the signing algorithm specified in the header. The most common algorithms are:

• HS256 (HMAC with SHA-256): Symmetric algorithm. Both the issuer and verifier share the same secret key.
• RS256 (RSA Signature with SHA-256): Asymmetric algorithm. The issuer uses a private key to sign the token, and the verifier uses a public key to verify it.
• ES256 (ECDSA using P-256 and SHA-256): Asymmetric algorithm similar to RSA but faster and uses smaller keys.

JWT Expiration and Timestamps

JWT uses Unix epoch time (the number of seconds that have elapsed since January 1, 1970) for its time-based claims:

• exp (Expiration Time): The time after which the token must not be accepted.
• iat (Issued At): The time at which the token was issued.
• nbf (Not Before): The time before which the token must not be accepted.

Our JWT Decoder automatically parses these numeric values into human-readable local dates and clearly indicates if a token is currently active, expired, or not yet valid.