JWT Authentication Explained Simply
What is a JWT?
JSON Web Tokens (JWT) are an open, industry-standard method for representing claims securely between two parties. Despite their complex-sounding name, JWTs are incredibly simple.
A JWT is just a long, encoded string containing a JSON object. This JSON object carries information about a user (like their userId, role, and expirationDate). The entire string is cryptographically signed by the server, ensuring that nobody can tamper with the data without the server knowing.
The Anatomy of a JWT
A JWT is always composed of three parts, separated by dots (.):
header.payload.signature
- Header: Contains metadata about the type of token and the cryptographic algorithm used (e.g., HMAC SHA256 or RSA).
- Payload: This is the actual data (called "claims"). For example:
{"userId": "123", "role": "admin", "exp": 1691234567}. - Signature: This is the most critical part. The server takes the encoded Header, the encoded Payload, and a secret key (that only the server knows) and runs a hashing algorithm. If a hacker tries to modify the payload to change their role to
"admin", the signature will become invalid, and the server will instantly reject the token.
JWTs vs Session Cookies
Historically, web applications used stateful sessions. When you logged in, the server created a record in its memory or database mapping your Session ID to your user data. The server then sent the Session ID to your browser as a cookie.
The Problem with Sessions: If your application scales to millions of users across 10 different servers, Server A might not know about a session created on Server B. You are forced to use a shared centralized database (like Redis) just to look up user sessions on every single API request.
The JWT Solution: JWTs are stateless. The server does not need to store the token in a database. When a user sends a JWT in an API request, the server simply runs the cryptographic math to verify the signature. If the math checks out, the server trusts the payload (e.g., it trusts that the user really is userId: 123). This allows APIs to scale infinitely without hitting a database for authentication.
Security Best Practices
Despite their benefits, JWTs are frequently implemented insecurely. Here is how to secure them:
1. Never Store JWTs in LocalStorage
If you store a JWT in the browser's localStorage or sessionStorage, any malicious JavaScript running on your page (via a compromised NPM package or third-party script) can read the token and steal the user's identity. This is called a Cross-Site Scripting (XSS) attack.
The Fix: Always instruct your backend to send the JWT inside an HttpOnly cookie. HttpOnly cookies cannot be accessed or read by JavaScript, completely neutralizing XSS token theft.
2. Beware of CSRF Attacks
If you use cookies, you become vulnerable to Cross-Site Request Forgery (CSRF). A malicious website could trick a user's browser into sending an authenticated request to your API because the browser automatically attaches cookies to cross-domain requests.
The Fix: Use the SameSite=Strict attribute on your cookie, and ensure your backend enforces strict CORS policies.
3. Keep Expirations Short (The Access/Refresh Token Pattern)
Because JWTs are stateless, you cannot easily "revoke" them. If a hacker steals a JWT that lasts for a year, they have access for a year.
The Fix: Set your primary JWT (the Access Token) to expire very quickly (e.g., 15 minutes). Issue a secondary, stateful "Refresh Token" that lives in the database. When the 15-minute Access Token expires, the client silently sends the Refresh Token to get a new Access Token. If a user needs to be banned, you simply delete the Refresh Token from the database.
Conclusion
JWTs are powerful tools for building stateless, scalable microservices. By understanding how the cryptographic signature works and enforcing strict browser security standards like HttpOnly cookies, you can build enterprise-grade authentication systems.