The Ubiquity of Bearer Tokens
JSON Web Tokens (JWT) have become the de facto standard for stateless authentication in modern web applications. However, their simplicity often hides subtle edge cases that can frustrate developers during integration.
1. Clock Skew and the nbf Claim
One of the most common issues developers face when integrating third-party authentication providers is the dreaded "Token not active yet" error. This occurs when the issuer's server clock is slightly ahead of your server's clock.
When an issuer creates a token with a nbf (Not Before) or iat (Issued At) claim, they stamp it with their current time. If your server receives that token and your system clock is slightly behind, standard verification libraries will reject the token. To fix this, always configure a reasonable "clock skew" allowance (e.g., 60 seconds) in your JWT validation library.
2. Base64 vs Base64URL Padding
JWTs use Base64URL encoding, which replaces standard Base64 characters (+ and /) with URL-safe alternatives (- and _) and strips the trailing = padding characters.
A frequent mistake when writing custom decoders is attempting to use standard decoding functions (like JavaScript's atob()) directly on a JWT payload. If the string lacks proper padding or contains URL-safe characters, the function will throw a `DOMException`. You must normalize the string by restoring standard characters and appending the correct number of `=` symbols before decoding.
3. Treating Payloads as Encrypted Secrets
Perhaps the most dangerous mistake is assuming that because a JWT looks like random gibberish, it is encrypted. It is not.
A standard JWT is merely encoded. Anyone who intercepts the token can decode the header and payload in milliseconds. You must never place sensitive information—such as internal IP addresses, database IDs that shouldn't be public, or personal identifiable information (PII)—directly into the payload unless you are specifically using JSON Web Encryption (JWE).
4. "alg": "none" Vulnerabilities
In the early days of JWT, many libraries suffered from a critical vulnerability where an attacker could modify the header to "alg": "none", strip the signature, and bypass authentication. Modern libraries reject this by default, but you must always explicitly specify the allowed algorithms (e.g., strictly RS256) when configuring your verification middleware.