JWT Complete Guide: Structure, Security & Best Practices

What is JWT?

JWT (JSON Web Token) is a way to securely transfer information between two parties. Think of it like a sealed envelope:

The contents are visible to anyone who looks, but the seal proves it hasn't been tampered with since it was created.

When you decode a JWT, you can read its contents. But only someone with the secret key can create a valid signature. If anyone modifies the data, the signature won't match, and the token will be rejected.

Why is JWT So Popular?

JWT Structure

Every JWT consists of three parts, separated by dots:

xxxxx.yyyyy.zzzzz
header.payload.signature

1. Header

Contains the token type (JWT) and the signing algorithm being used (e.g., HS256, RS256).

2. Payload

The actual data storage — user information like user ID, roles, permissions, and expiration time. These pieces of data are called "claims."

3. Signature

A cryptographic signature created using the header, payload, and a secret key. This is what makes the token tamper-proof.

Common Claims in the Payload

• iss (Issuer) — Who created the token
• sub (Subject) — Who the token is about (usually user ID)
• aud (Audience) — Who the token is intended for
• exp (Expiration) — When the token expires
• iat (Issued At) — When the token was created
• nbf (Not Before) — Token is not valid before this time

A Visual Example

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

{ "sub": "1234567890", "name": "Farvez", "role": "admin", "exp": 1716239022 }

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

JWT Creation Process

1. Create the Header — Specify the algorithm and token type.
2. Create the Payload — Add user data (claims) and an expiration time.
3. Combine Header and Payload — Base64 encode both and join them with a dot.
4. Generate the Signature — Use your secret key to sign the combined header and payload.
5. Return the JWT — The final token is: header.payload.signature

JWT Refresh Mechanism

Access tokens should be short-lived for security. Refresh tokens allow users to get new access tokens without re-authenticating:

Keep access tokens short-lived (15 minutes to 1 hour) and refresh tokens longer-lived (days to weeks) but stored securely.

Security Validation

When a JWT arrives at your server, here's how to validate it:

1. Split the JWT into header, payload, and signature
2. Recreate the expected signature using the header and payload
3. Compare — if signatures match and token is not expired, it's valid

Common JWT Mistakes

Real-World Use Cases

• Secure API Authentication — Stateless user verification without server sessions.
• Single Sign-On (SSO) — Multi-application access with a single login.
• Microservices Security — Service-to-service communication without central session stores.

Security Best Practices Checklist

• Enforce HTTPS — Never transmit JWTs over unencrypted connections
• Set brief expiration — Short-lived tokens limit damage from theft
• Use strong algorithms — HS256 or RS256, never "none"
• Secure storage — Use HTTP-only cookies, not localStorage
• Rotate secret keys — Regularly update your signing keys
• Validate all claims — Check issuer, audience, and expiration
• Keep payloads small — Only include necessary claims
• Implement token revocation — Have a strategy for invalidating tokens

Conclusion

Understanding JWT mechanics is crucial for implementing secure authentication. Remember: JWTs are not encrypted by default — they're signed. Anyone can read the payload, but only the server with the secret key can create valid signatures.

By avoiding common mistakes and following best practices, you can build secure, scalable authentication systems that serve your users well.