JWT Decoder

The Structure and Encoding of JWT

A JSON Web Token consists of three parts separated by dots: Header.Payload.Signature. Each part is Base64URL encoded (a URL-safe variant of Base64 that replaces + with -, / with _, and removes padding =). This encoding makes JWTs safe to include in URLs and HTTP headers without special escaping.

The header typically contains two fields: "alg" specifies the signing algorithm (e.g., HS256 for HMAC-SHA256, RS256 for RSA-SHA256), and "typ" declares the token type (usually "JWT"). For example: {"alg": "HS256", "typ": "JWT"} encodes to eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.

The payload contains claims—statements about an entity (typically the user) and additional metadata. Standard claims include "iss" (issuer), "sub" (subject), "aud" (audience), "exp" (expiration time as Unix timestamp), "nbf" (not before time), and "iat" (issued at time). You can add custom claims like user roles or permissions.

The signature ensures the token hasn't been tampered with. For HMAC algorithms, you hash the encoded header and payload using a secret key: HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret). For RSA algorithms, you sign with a private key and verify with the corresponding public key.

Base64URL encoding is crucial for web compatibility. Standard Base64 uses + and / characters that have special meaning in URLs. Base64URL replaces these with - and _ respectively. The padding characters (=) are also removed since they can cause issues in URL query parameters. Decoders can infer the correct padding from the string length.

History and Development of JWT

JWT was standardized as RFC 7519 in May 2015, but the concepts emerged from earlier work on security tokens. The need arose from the shift toward stateless authentication in distributed systems and microservices architectures. Traditional session-based authentication required server-side storage and didn't scale well across multiple servers.

Before JWT, various proprietary token formats existed. Simple Web Token (SWT) used XML, and Security Assertion Markup Language (SAML) tokens were verbose and complex. JWT's JSON format made it more compact than XML alternatives and easier for JavaScript applications to parse—critical for single-page applications and mobile apps.

The OAuth 2.0 Authorization Framework (RFC 6749, 2012) adopted JWT as its standard token format through RFC 7523. OpenID Connect, built on OAuth 2.0, uses JWTs as ID tokens to convey user identity information. This standardization led to widespread adoption across identity providers like Auth0, Okta, and AWS Cognito.

The JSON Web Signature (JWS) specification (RFC 7515) and JSON Web Encryption (JWE) specification (RFC 7516) were developed alongside JWT. JWS defines how to digitally sign or MAC arbitrary content, while JWE defines encryption. JWT builds on JWS—a JWT is essentially a specific type of JWS with JSON content.

Criticisms of JWT emerged regarding security practices. In 2015, researchers identified vulnerabilities in some JWT implementations, including the "none" algorithm attack where attackers could remove the signature entirely. This led to improved libraries and best practices, emphasizing the importance of always validating the algorithm and never trusting the header blindly.

Signing Algorithms and Cryptography

HMAC (Hash-based Message Authentication Code) algorithms like HS256 use a shared secret key for both signing and verification. The same key is used by the token issuer and all verifiers. HS256 applies SHA-256 hashing: HMAC-SHA256(message, secret). This is fast and simple but requires securely distributing the secret to all parties that need to verify tokens.

RSA algorithms like RS256 use asymmetric cryptography with a private/public key pair. The token issuer signs with the private key, but anyone can verify using the public key. This is ideal for distributed systems where multiple services need to verify tokens but shouldn't be able to create them. RS256 uses RSASSA-PKCS1-v1_5 with SHA-256.

ECDSA (Elliptic Curve Digital Signature Algorithm) like ES256 offers similar security to RSA with smaller key sizes. ES256 uses the P-256 curve with SHA-256. A 256-bit ECDSA key provides security equivalent to a 3072-bit RSA key, resulting in smaller signatures and faster operations. ECDSA is increasingly popular for performance-sensitive applications.

The "none" algorithm allows unsigned JWTs, intended for situations where integrity is protected by other means. However, many security vulnerabilities stemmed from libraries accepting "none" when applications expected signed tokens. Modern best practices require explicitly whitelisting allowed algorithms and rejecting "none" unless specifically needed.

EdDSA (Edwards-curve Digital Signature Algorithm) using Ed25519 is a newer option offering excellent performance and security. It's deterministic (unlike ECDSA), has smaller keys and signatures, and is less prone to implementation errors. JWK (JSON Web Key) format standardizes how to represent public keys in JSON, making key distribution easier.

Authentication Flow and Token Lifecycle

In a typical authentication flow, the client sends credentials (username/password) to the authentication server. Upon successful verification, the server creates a JWT with appropriate claims including user ID, roles, and expiration time. The server signs the token and returns it to the client, which stores it (typically in memory or localStorage).

For subsequent requests, the client includes the JWT in the Authorization header: Authorization: Bearer <token>. The resource server extracts the token, verifies the signature using the appropriate key, checks the expiration time, and validates other claims. If valid, the server processes the request; otherwise, it returns a 401 Unauthorized response.

Token expiration is crucial for security. Short-lived access tokens (15 minutes to 1 hour) limit the damage if stolen. Refresh tokens provide longer-lived credentials (days or weeks) that can be used to obtain new access tokens. The refresh token is typically stored more securely and may require additional verification like device fingerprinting.

Token revocation is challenging because JWTs are stateless—servers don't track which tokens are active. Strategies include maintaining a blacklist of revoked token IDs (requiring storage), using short expiration times and frequent refreshes, or implementing token versioning where users have a "token version" number that increments on logout or password change.

Refresh token rotation improves security by issuing a new refresh token each time it's used, invalidating the old one. If an attacker steals and uses a refresh token, the legitimate user's next refresh attempt will fail, alerting them to the compromise. Some systems implement detection of refresh token reuse to automatically revoke all tokens for that user.

Security Considerations and Best Practices

Never put sensitive information in JWT payload—it's only encoded, not encrypted. Anyone can decode a JWT and read its contents. Use JWE (JSON Web Encryption) if you need to include sensitive data. Store only non-sensitive identifiers and retrieve sensitive data from your database using those identifiers when needed.

Always validate the algorithm. Attackers have exploited vulnerabilities where applications accepted the algorithm specified in the token header without verification. Always whitelist expected algorithms (e.g., only allow RS256) and reject others. Never accept the "none" algorithm unless your application specifically requires unsigned tokens.

Validate all standard claims rigorously. Check "exp" (expiration) to ensure the token isn't expired. Verify "iss" (issuer) matches your authentication server. Check "aud" (audience) to ensure the token was intended for your application. Validate "nbf" (not before) to prevent tokens from being used too early. Add clock skew tolerance (a few minutes) to handle time synchronization issues.

Protect against Cross-Site Scripting (XSS) attacks. If stored in localStorage or sessionStorage, JWTs are vulnerable to XSS attacks where malicious JavaScript steals tokens. Consider using httpOnly cookies for token storage—JavaScript cannot access these, though they're vulnerable to CSRF attacks. Implement proper CSRF protections when using cookies.

Use appropriate key management. For HMAC, use cryptographically random secrets of sufficient length (at least 256 bits). For RSA, use at least 2048-bit keys (4096-bit for higher security). Rotate keys periodically and support multiple keys simultaneously during rotation. Use Hardware Security Modules (HSMs) or key management services for production applications handling sensitive data.

Advanced Features and Extensions

JSON Web Encryption (JWE) adds confidentiality to JWTs. While standard JWTs are signed (providing integrity and authenticity), JWE encrypts the content so only intended recipients can read it. JWE uses two-step encryption: generate a random Content Encryption Key (CEK), encrypt the JWT payload with the CEK using a symmetric algorithm, then encrypt the CEK using the recipient's public key.

JSON Web Key (JWK) standardizes representing cryptographic keys in JSON format. Public keys can be published at a .well-known/jwks.json endpoint, allowing token verifiers to dynamically fetch verification keys. JWK Sets contain multiple keys, enabling key rotation. The "kid" (key ID) header parameter identifies which key signed a particular token.

JWT can include custom claims for application-specific needs. Common custom claims include user roles, permissions, tenant IDs in multi-tenant applications, and feature flags. Keep the token size reasonable—HTTP header size limits typically range from 4KB to 8KB. Minimize claims to reduce token size and network overhead.

Token introspection (RFC 7662) provides a standardized way to query token metadata. An authorization server exposes an introspection endpoint that accepts a token and returns its active status and metadata. This is useful when servers need to verify tokens they didn't issue or when real-time revocation checking is required. However, it introduces latency and couples services to the authorization server.