jwt

22 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

JWT structure: three base64url parts separated by dots

A signed JWT consists of three base64url-encoded parts separated by dots: {base64url(json(header))}.{base64url(json(claims))}.{base64url(signature)}. The first part is the protected header, the second part is the claims, and the third part is the signature that protects both the header and claims.

JWT protected header contains token type and cryptographic algorithms

The JWT header contains information about the token such as the type of token (IANA media type) and the cryptographic algorithms used to protect the token.

JWT claims are the content information often about a user or application

The JWT claims are a list of claims, usually about the subject. Standard claims are registered in the JWT IANA Registry.

JWT signature uses either public-key digital signature or MAC

The JWT signature is either a public-key digital signature using a public/private key pair, or a MAC using a shared secret. The signature protects both the protected headers and the claims.

Recommended JWT public-key signature algorithms: EdDSA, ECDSA, RSASSA-PSS

Recommended signature schemes for public-key JWTs are: EdDSA (identifiers EdDSA, Ed448, Ed25519, with limited support), ECDSA (ES256, ES384, ES512), and RSASSA-PSS (PS256, PS384, PS512). RSASSA-PKCS1-v1_5 (RS256, RS384, RS512) is not recommended. EdDSA has limited support in JWT implementations. ECDSA signature generation must use deterministic ECDSA as defined in RFC 6979 on embedded systems where randomness quality may be problematic.

Post-quantum and hybrid ML-DSA signature schemes for JWT have limited or draft support

Post-quantum signatures (ML-DSA-44, ML-DSA-65, ML-DSA-87) and hybrid signatures (ML-DSA-44-Ed25519, ML-DSA-44-ES256, etc.) are designed to resist quantum computers but produce very large signatures resulting in large JWTs. Post-quantum signatures have very limited support at best, and hybrid signatures are still in draft status. Usage is probably not justified unless signatures with long validity are needed.

Recommended JWT MAC signature algorithm: HMAC with SHA-2

The only recommended MAC signature scheme for JWT is HMAC with SHA-2 using identifiers HS256, HS384, HS512.

JWT public-key: do not reuse key pair for another purpose

Do not reuse the key pair for another purpose such as encryption. Using the same key for authenticating different types of JWTs is fine as long as this does not introduce a risk of token type confusion. Do not publish your private key.

JWT MAC secret: minimum 160 bits entropy and same size as output

The HMAC secret must have at least 160 bits of entropy. The secret must have at least the same size as the output: 256 bits for HS256, 384 bits for HS384, 512 bits for HS512. For HMAC, the secret should be at least as long as the output size per RFC 2104 section 3.

JWT MAC secret: do not reuse with another audience or issuer

Do not reuse the same HMAC secret with another audience or issuer. Each (issuer, audience) pair must use a different secret, otherwise an audience could forge a token impersonating the issuer.

JWT MAC secret must be generated with cryptographically secure generator

The HMAC secret must be generated using a local, cryptographically secure secret generator such as secrets.token_bytes(). Do not use passwords as MAC secrets, do not hardcode secrets, and do not use non-secure randomness sources like random.randbytes().

JWT MAC secret: do not reuse for another purpose or publish

Do not reuse the same HMAC secret for another purpose such as encryption. Do not publish your secret key.

Disable alg:none in JWT parser to prevent unsecured JWTs

Some JWT libraries used to accept unsecured JWTs with 'alg':'none' by default, allowing attackers to forge their own JWTs. Ensure that 'alg':'none' is not accepted by your JWT parser. It should be disabled by default in recent implementations.

JWT key confusion: attacker uses public key as MAC secret

Key confusion or algorithm confusion occurs when JWT implementations accept a public key intended for public-key digital signatures and use it as a secret key for MAC verification. An attacker could forge a MAC-based JWT by using the issuer's public key as if it were a secret key for HS256 or similar MAC algorithm.

Mitigate JWT key confusion by hardcoding accepted algorithms

Mitigate key confusion attacks by: using a library with strong typing of key types; choosing the key based on the requested signature algorithm; validating that the key used for validation is consistent with the signature algorithm; or hardcoding the accepted algorithms and not mixing public-key digital signature algorithms with MAC algorithms.

JWT revocation via Token Status List aggregates revocation status

Token Status List (TSL) can be used for JWT revocation: the JWT contains a 'status' claim with the URI of a TSL and an index; the TSL aggregates revocation status of several tokens in compressed form; the token consumer can fetch the TSL to obtain the JWT's revocation status.

JWT denylist implementation uses jti and iss claims

A JWT denylist can be implemented using the 'jti' and 'iss' claims as the key. Store the tuple (jti, iss) in the denylist along with the token's 'exp' claim for expiration. Depending on the application and JWT type, other claims might be more suitable.

JWT denylist: do not use raw token or SHA-256 hash as key

Using the raw JWT or a secure hash of the JWT (SHA-256(token)) as the denylist key is not safe and might expose the application to denylist bypass through JWT malleability. An attacker with a revoked JWT could modify an alternative representation that still passes signature verification due to non-strict JWT parsing or ECDSA signature malleability.

JWT replay protection alternatives to denylist

Before implementing a JWT denylist, consider better solutions: Token Status List for issuer-based revocation; using 'nonce' bound to session in JWT claims for freshness protection (as in OpenID Connect); using short expiration time in JWT for token reuse mitigation; using sender-constrained JWT such as DPoP or TLS-bound JWT to mitigate token exfiltration risk.

Consider session management alternatives before using JWT for stateless sessions

JWTs are often suggested for stateless user sessions, but this usage is frowned upon. If you use JWTs for user sessions, you need a solution for managing session invalidation such as a deny list of revoked sessions, which defeats the benefits of stateless sessions. Consider using a plain session system following the session management cheat sheet instead.

Digital signature advantages over MAC for JWT

When using digital signatures for JWT: the issuer can reuse the same public key for many different audiences; audiences only need public information to validate token authenticity, removing secret leakage risk; public keys can be easily distributed by publishing at public HTTPS URI; key rotation is simpler. However, traditional digital signature schemes might be broken by post-quantum computers.

MAC advantages for JWT are limited to specific cases

MACs are much faster than digital signatures but this is usually negligible in practice. MAC may be interesting only when: the issuer is the sole audience of the token, or the issuer is the audience. In these cases, digital signatures might still be easier for secret rotation/distribution.

Give your agent this brain