JSON Web Token (JWT) Security

JWT_Security_checklist.md

Basic Check:

• JWTs should always use the appropriate signature scheme
• If a JWT contains sensitive data, it should be encrypted
• JWTs require proper cryptographic key management
• Using JWTs for sessions introduces certain risks

JWT integrity verification:

• symmetric signatures

• Asymmetric signatures

Best Practices:

• Always verify the signature of JWT tokens
• Avoid library functions that do not verify signatures (Example: The decode function of the auth0 Java JWT library)
• Check that the secret of symmetric signatures is not shared
• A distributed setup should only use asymmetric signatures

Validating JWT's:

The receiver of a JWT should always check these properties before using any of the claims.

• Check the exp claim to ensure the JWT is not expired (Alternatively verify lifetime using creation time in the iat claim)

• Check the nbf claim to ensure the JWT can already be used

• Check the iss claim against your list of trusted issuers

• Check the aud claim to see if the JWT is meant for you

Cryptographic key management:

The use of keys for signatures and encryption requires careful management. Keys should be stored in a secure location. Keys also need to be rotated frequently. As a result, multiple keys can be in use simultaneously. The application has to foresee a way to manage the JWT key material.

• Store key material in a dedicated key vault service
  • Keys should be fetched dynamically, instead of being hardcoded
• Use the kid claim in the header to identify a specific key
  • Keys should be fetched dynamically, instead of being hardcoded
• Public keys can be embedded in the header of a JWT
  • The jwk claim can hold a JSON Web Key-formatted public key
  • The x5c claim can hold a public key and X509-certificate
• Validate an embedded public key with a list of known keys
  • Failure to restrict keys causes an attacker’s JWT to be accepted
• The header can also contain a URL pointing to public keys
  • The jwk claim can hold a JSON Web Key-formatted public key
  • The x5c claim can hold a public key and X509-certificate
• Validate a key URL against a safe list of URLs / domains (Failure to restrict keys causes an attacker’s JWT to be accepted)

Using JWTs for authorization state

Many modern applications use JWTs to push authorization state to the client. Such an architecture benefits from a stateless backend, often at the cost of security. These JWTs are typically bearer tokens, which can be used or abused by whoever obtains them.

• It is hard to revoke a self-contained JWT before it expires

• JWTs with authorization data should have a short lifetime
• Combine short-lived JWTs with a long-lived session

Reference:

Description	Reference	Link
kid claim	kid is an optional header claim which holds a key identifier, particularly useful when you have multiple keys to sign the tokens and you need to look up the right one to verify the signature. The kid (key ID) Header Parameter is a hint indicating which key was used to secure the JWS.	Learn More
exp claim	The “exp” (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. The processing of the “exp” claim requires that the current date/time MUST be before the expiration date/time listed in the “exp” claim.	Learn More
nbf claim	"nbf" (Not Before) Claim. The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim.	Learn More
iss claim	The “iss” (issuer) claim identifies the principal that issued the JWT. The processing of this claim is generally application specific. The “iss” value is a case-sensitive string containing a StringOrURI value. Use of this claim is OPTIONAL.
aud claim	The Audience ( aud ) claim as defined by the spec is generic, and is application specific. The intended use is to identify intended recipients of the token. What a recipient means is application specific. An audience value is either a list of strings, or it can be a single string if there is only one aud claim
jwk claim	A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification.	Learn More
x5c claim	Header Parameter contains the X.509 public key certificate or certificate chain [RFC5280] corresponding to the key used to digitally sign the JWS.	Learn More

• https://tools.ietf.org/html/rfc7515