JWT Authentication: Do's and Don'ts
The Fundamental Vulnerability of the Web
The HTTP protocol is inherently stateless. When a user logs in to your website, the server has no memory of them the next time they click a link. Historically, we solved this with Session-Based Authentication. The server would generate a random ID, store it in a massive database table, and give the user a cookie containing that ID. On every single request, the server had to pause, query the database, and verify the session ID. At a small scale, this is fine. At a massive scale (think millions of concurrent users), querying a central session database for every single image load and API call becomes a crippling bottleneck.
The Stateless Revolution of JWT
JSON Web Tokens (JWT) solved the scaling crisis. A JWT is a self-contained, cryptographically signed document. It shifts the burden of proof from the server's database to the mathematical algorithm. When a user logs in, the server creates a JSON object (the payload) containing the user's ID and their roles (e.g., {"user_id": 123, "role": "admin"}). The server then cryptographically signs this JSON using a highly secret key and sends the resulting base64 encoded string to the client.
When the client makes their next request, they present the JWT. The server does NOT need to look up the database. It simply runs the mathematical signature verification using its secret key. If the math checks out, the server mathematically guarantees that the token is authentic and has not been tampered with. This completely eliminates the database bottleneck, allowing infinite horizontal scaling of web servers.
The Anatomy of a JWT
A JWT consists of three parts separated by dots (.):
- Header: Contains the algorithm used for signing (usually HS256 or RS256).
- Payload: The actual data claims (user ID, expiration timestamp). Warning: This is merely base64 encoded, not encrypted. Anyone who intercepts the token can read the data. Never put sensitive information like Social Security Numbers inside a JWT.
- Signature: The cryptographic hash created by combining the Header, Payload, and the Server's Secret Key.
The Devastating Storage Mistake
While the cryptography of JWTs is nearly unbreakable, developers routinely destroy their application's security by storing the JWT incorrectly on the client side. The most common, critical mistake is storing the token in localStorage or sessionStorage.
If you store a JWT in localStorage, it is accessible via JavaScript. If your application has a single Cross-Site Scripting (XSS) vulnerability (perhaps a user uploaded a malicious comment containing a hidden <script> tag), the hacker's script can easily execute localStorage.getItem('token') and silently transmit it to their servers. The hacker now possesses the token and has fully compromised the user's account.
The Golden Rule: You must store JWTs inside an HttpOnly, Secure, SameSite=Strict cookie. An HttpOnly cookie completely hides the data from JavaScript. Even if an XSS attack occurs, the malicious script cannot access the cookie, neutralizing the theft vector.
The Invalidation Nightmare
The greatest strength of a JWT (its statelessness) is also its fatal flaw. Because the server does not check a central database, a JWT cannot be easily revoked. If a user clicks "Log Out", or if a hacker steals an active token, the server has no built-in way to mathematically invalidate the token before its natural expiration date.
To mitigate this, enterprise architectures rely on the Access/Refresh Token Pattern:
- Access Token: The actual JWT used to hit APIs. It must have an extremely short lifespan (e.g., 10 to 15 minutes). If stolen, the hacker has a very tight window of opportunity.
- Refresh Token: A highly secure, opaque string (not a JWT) stored in an HttpOnly cookie and validated against a database. When the 15-minute Access Token expires, the client silently sends the Refresh Token to a dedicated authentication endpoint. The server verifies the Refresh Token in the database (which CAN be revoked if an account is compromised), and issues a brand new short-lived Access Token.
This hybrid approach perfectly balances the extreme high-performance of stateless API requests with the necessary security of central revocation controls.