Anatomy of a JWT: header, payload, and signature
A JWT consists of three parts separated by dots: header.payload.signature. The header (base64url encoded) declares the signing algorithm and token type, typically {`{"alg":"HS256","typ":"JWT"}`}. The payload contains the claims: information about the user and token metadata. The signature is generated by signing header+payload with a secret (HS256) or private key (RS256, ES256), guaranteeing integrity but not content confidentiality.
The standard registered claims in RFC 7519 include: iss (issuer), sub (subject - usually user ID), aud (audience - who should consume the token), exp (expiration timestamp), nbf (not before), iat (issued at), and jti (unique JWT ID for revocation). These claims have universal meaning and should be used before custom claims for maximum compatibility between libraries.
The payload is not secret. It's base64-encoded, not encrypted. Anyone with access to the token can read its content at jwt.io or by decoding manually. Never include passwords, private keys, medical data, or sensitive information in the payload. What the signature does guarantee is that content wasn't altered: if someone modifies the payload, the signature no longer matches and the token is rejected by the validator.
HS256 vs RS256: when to use each algorithm
HS256 (HMAC-SHA256) uses a shared secret. The same string signs and verifies the token. It's ideal when whoever issues and validates is the same service: a monolithic API signing its own tokens. The advantage is simplicity and speed. The disadvantage: if three services need to validate tokens, all must have the secret, multiplying leak risk. Any compromised service can forge tokens.
RS256 (RSA with SHA-256) uses a key pair: private to sign, public to verify. The issuer keeps the private key in maximum security. Validators only need the public one (it's not secret). This is ideal for microservices architectures or federated systems like OAuth/OIDC: Google issues tokens, a thousand applications validate them without sharing secrets. Public keys are distributed via standard JWKS (JSON Web Key Set) endpoint.
ES256 (ECDSA) is similar to RS256 but with elliptic curves. Signatures are much shorter (64 bytes vs 256+ for RSA), reducing JWT size. Comparable or better performance. Adoption is growing but RS256 remains more universal. For new production, ES256 is an excellent choice. For integration with legacy systems, RS256 guarantees maximum compatibility. Never use 'none' as algorithm: historic vulnerability exploited in 2015 that still appears in CTFs.
Common security errors with JWT
The most expensive mistake is not validating the signature. Some libraries allow decoding without validating (decode vs verify function). If your code only decodes but doesn't verify, anyone can invent a payload, encode it in base64, and send it. Your API would accept it as valid. Always use verify functions that validate the signature against your secret or public key before trusting the received payload content.
Another error is accepting the header algorithm without validating. CVE-2015-9235 vulnerability: attacker sends token with alg='none' and many libraries accepted it. Worse variant: changing HS256 to RS256 using the public key as HMAC secret. Solution: hardcode the expected algorithm in your validation code. Don't trust the incoming token's header. If you expect RS256, explicitly reject any other algorithm even if signed correctly.
The third error is long-duration tokens without revocation. JWTs are stateless: once issued, valid until exp. If you issue a 30-day token and the user changes password or reports theft, the token remains valid. Solution: short tokens (15 min) with long-duration refresh token, blacklist of revoked jti in Redis, or validation against credentials version database. Without revocation strategy, JWTs lose advantages over traditional sessions with signed cookies.
Real use cases: when to USE and when NOT to use JWT
JWT shines in authentication between services. Microservices that call each other can sign requests without managing shared sessions. Public APIs with OAuth 2.0 use JWT as access tokens. Single Sign-On (SSO) with OIDC distributes signed identity tokens that each application validates independently. For machine-to-machine, JWT is the de facto standard in modern serverless and multi-cloud architectures.
JWT is NOT ideal for traditional user sessions in monolith. A session cookie with opaque identifier pointing to Redis is simpler, allows instant revocation, and doesn't expose metadata. If your app is a Rails or Django monolith with one server, you gain nothing with JWT versus classic session. The complexity of handling refresh tokens, revocation, and key rotation doesn't compensate for simple cases without real federated dependencies.
Another problematic case is JWT in cookies with sensitive data. If you store roles and permissions in the token, each change requires re-issuing the token. If admin revokes permissions, the user keeps access until exp. For apps with volatile permissions, better consult the authoritative source (DB) on each request. The token only confirms identity; permissions are verified in real time. This loses performance but gains real operational security and consistency.