JWT Token: Structure and Security

JWTs are compact, self-contained tokens that carry identity and permissions, but they’re only secure when properly signed and validated.

Overview

JWT stands for JSON Web Token and is a widely used format for transmitting claims between two parties. A JWT consists of three parts—header, payload, and signature—separated by periods and Base64Url-encoded. The header contains metadata like the algorithm and token type; the payload holds claims such as expiration time, issuer, and user ID; and the signature secures integrity and authenticity. JWTs are commonly used for API authentication and authorization, but they carry security risks if misused. Key practices include keeping expiration short, using strong algorithms, validating issuer and audience correctly, always using HTTPS, and never storing sensitive data in the payload, since it’s only encoded, not encrypted.

Key Components

The header typically contains two claims: alg for the algorithm used and typ for the token type. It’s Base64Url-encoded. The algorithm should be asymmetric like RS256 or a strong symmetric approach like HS256 with a long secret. The none algorithm must never be accepted.

Payload

The payload contains the claims. Standard claims include sub for subject, iss for issuer, aud for audience, exp for expiration, iat for issued at, nbf for not before, and jti for JWT ID. Application-specific claims like roles or permissions can be added. The payload is also Base64Url-encoded and readable by anyone who possesses the token.

Signature

The signature is created by combining the header and payload and signing them with the chosen algorithm and key. It ensures the token hasn’t been tampered with. The receiver verifies the signature using the issuer’s public or symmetric key.

Base64Url Encoding

Base64Url is a URL-safe variant of Base64 encoding. It replaces plus signs and forward slashes with different characters and removes padding. This enables compact representation of JSON data in tokens that can be transmitted in URLs and headers.

Signature Algorithms

RS256 uses RSA with SHA-256 and a key pair of private and public keys. The issuer signs with the private key; the receiver validates with the public key. HS256 uses a shared secret. Asymmetric approaches work better for distributed systems.

Claims and Expiration

Claims are the central data in a JWT. The exp claim defines expiration and is critical for limiting a token’s lifespan. Short validity reduces risk if a token is stolen. The iat and nbf claims help further restrict the valid period.

Token Validation

A resource server must check at least the following upon receiving a JWT: signature, expiration, issuer, audience, algorithm, and required claims. Missing or incorrect checks can lead to unauthorized access.

Token Transport

JWTs are typically transmitted in the Authorization header as a Bearer token. The header looks like this: Authorization: Bearer eyJhbGciOiJIUzI1NiIs.... Transport must always occur over HTTPS to prevent token theft.

Security Risks

Known risks include algorithm confusion, where an attacker changes the algorithm to none; weak keys with HS256; long validity periods; missing audience validation; and storing sensitive data in the payload. Additionally, stolen tokens can be used as long as they remain valid, so short lifespan is crucial.

JWK and JWKS

JWK stands for JSON Web Key; JWKS stands for JSON Web Key Set. JWKS is a collection of public keys that a resource server uses to validate JWTs. The authorization server typically publishes JWKS at a known URL, allowing keys to be automatically rotated.

Practical Example

An API client receives a JWT access token after successful login. The token consists of three Base64Url-encoded parts.

Decoded header:

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

Decoded payload:

{
  "sub": "user-98765",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1751300000,
  "iat": 1751296400,
  "scope": "read:orders write:orders"
}

The complete token is transmitted in the Authorization header:

GET /api/v1/orders
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

The resource server verifies the signature with the public key, validates exp, iss, aud, and scope, then grants access. If the token is expired or the signature is invalid, the server responds with 401 Unauthorized.

FAQ: JWT Token

1. What is a JWT?

JWT stands for JSON Web Token. It’s a compact token format consisting of a header, payload, and signature that carries claims for authentication and authorization.

2. How is a JWT structured?

A JWT consists of a header, payload, and signature separated by periods. All three parts are Base64Url-encoded.

3. What are claims?

Claims are the information contained in the payload. Important standard claims are sub, iss, aud, exp, iat, and nbf. Application-specific claims can be added as needed.

4. Is the JWT payload encrypted?

No, the payload is only Base64Url-encoded and readable by anyone who has the token. JWTs should not contain sensitive data unless they are encrypted as JWE.

5. What is the JWT signature?

The signature secures the header and payload using a cryptographic algorithm and key. It ensures the token has not been modified since issuance.

6. What’s the difference between RS256 and HS256?

RS256 is an asymmetric algorithm using private and public keys. HS256 is a symmetric algorithm using a shared secret. RS256 is better suited for distributed APIs.

7. What does the none algorithm mean?

The none algorithm means the token is unsigned. Servers must never accept such tokens because they can be easily manipulated.

8. What is algorithm confusion?

Algorithm confusion is an attack where an attacker changes the algorithm in the header and uses the public key as a symmetric secret to sign a forged token. Servers should strictly validate the algorithm.

9. What is JWKS?

JWKS stands for JSON Web Key Set. It’s a collection of public keys used by a resource server to validate JWTs. Keys can be fetched automatically from a URL.

10. Why should a JWT be short-lived?

Short validity reduces risk if a token is stolen. An attacker can only use a stolen token while it’s valid. After expiration, they need a fresh token.

11. What is a Bearer token?

A Bearer token is transmitted in the Authorization header with the Bearer scheme. Whoever holds the token is considered authorized. Bearer tokens must be protected carefully.

12. How do you validate a JWT?

A JWT is checked for signature, expiration, issuer, audience, algorithm, and required claims. Validation must happen server-side and include all standard checks.

13. What is a Refresh Token?

A Refresh Token is a long-lived token that a client uses to request a new JWT access token. Refresh tokens must be especially well protected and revocable.

14. Should JWTs be stored in the browser?

Access tokens in the browser should be short-lived and not kept in local storage for extended periods. Secure, httpOnly cookies or tokens with very short lifespans are better options.

15. What are common JWT security mistakes?

Typical errors include accepting the none algorithm, using weak keys, allowing long validity periods, skipping audience and issuer checks, storing sensitive data in the payload, and transmitting tokens unencrypted.

Next in the API learning path

The next article in the API learning path covers API Authentication and Authorization: Fundamentals, Differences, and Methods — exploring the distinction between authentication and authorization, along with the most important approaches.

References

Recommended books on API security

If you’d like to deepen your knowledge of JWT, token security, and API security, we recommend the following books:

IT CyberSecurity

Books about IT security, authentication, encryption and security best practices

The Web Application Hacker's Handbook von Dafydd Stuttard, Marcus Pinto

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Täglicher Artikel