👨‍💻
Application Security Handbook
  • Application Security Handbook
  • Web Application
    • Authentication
      • Authentication with Login and Password
      • Authentication with Phone Number
      • OAuth 2.0 Authentication
      • Multi-factor Authentication
      • Default Passwords
      • Password Change
      • Password Policy
      • Password Reset
      • Password Storage
      • One Time Password (OTP)
      • Email Address Confirmation
    • Authorization
    • Concept of Trusted Devices
    • Content Security Policy (CSP)
    • Cookie Security
    • Cryptography
      • Cryptographic Keys Management
      • Encryption
      • Hash-based Message Authentication Code (HMAC)
      • Hashing
      • Random Generators
      • Universal Unique Identifier (UUID)
    • Error and Exception Handling
    • File Upload
    • Input Validation
    • JSON Web Token (JWT)
    • Logging and Monitoring
    • Output Encoding
    • Regular Expressions
    • Sensitive Data Management
    • Session Management
    • Transport Layer Protection
    • Vulnerability Mitigation
      • Brute-force
      • Command Injection
      • Cross-Site Request Forgery (CSRF)
      • Cross-Site Scripting (XSS)
      • Mass Parameter Assignment
      • Parameter Pollution
      • Path Traversal
      • Regular Expression Denial of Service (ReDoS)
      • SQL Injection (SQLi)
      • XML External Entity (XXE) Injection
Powered by GitBook
On this page
  • Overview
  • JWT claims
  • JSON Object Signing and Encryption (JOSE) header
  • JSON Web Signature (JWS)
  • JSON Web Encryption (JWE)
  • General
  • JWS-related
  • JWE-related
  • References
  1. Web Application

JSON Web Token (JWT)

PreviousInput ValidationNextLogging and Monitoring

Last updated 1 year ago

Overview

This page contains recommendations for the secure use of JSON Web Tokens (JWTs).

JSON Web Token (JWT) represents a set of claims as a JSON object that is encoded in a JSON Web Signature (JWS) and/or JSON Web Encryption (JWE) structure. A JWT is represented as a sequence of URL-safe parts (JWT claims sets) separated by .. Each part contains a base64url-encoded value. For example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The number of parts in the JWT is dependent upon the representation of the resulting or .

JWT claims

The JWT claims set represents a JSON object whose members are the claims conveyed by a JWT. There are three classes of JWT claim names:

Registered claim names

Claim names in the table below are registered in the IANA "JSON Web Token Claims" registry. None of these claims are intended to be mandatory to use or implement in all cases, but rather they provide a starting point for a set of useful, interoperable claims. Applications using JWTs should define which specific claims they use and when they are required or optional.

Claim
Definition
Type
Description

iss

Issuer

String or URI

The iss claim identifies the principal that issued the JWT

sub

Subject

String or URI

The sub claim identifies the principal that is the subject of the JWT

aud

Audience

Array of strings (String or URI)

String or URI

The aud claim identifies the recipients that the JWT is intended for

exp

Expiration Time

NumericDate

The exp claim identifies the expiration time on or after which the JWT must not be accepted for processing

nbf

Not Before

NumericDate

The nbf claim identifies the time before which the JWT must not be accepted for processing

iat

Issued At

NumericDate

The iat claim identifies the time at which the JWT was issued

jti

JWT ID

String

The jti claim provides a unique identifier for the JWT

Public claim names

Claim names can be defined at will by those using JWTs. Claim name is a value that contains a collision-resistant name.

Private claim names

A producer and consumer of a JWT may agree to use private claim names: names that are not registered claim names or public claim names. Unlike public claim names, private claim names are subject to collision.

JSON Object Signing and Encryption (JOSE) header

The JSON Object Signing and Encryption (JOSE) header is a JSON object containing the parameters describing the cryptographic operations and parameters employed.

For a JWT object, the members of the JSON object represented by the JOSE header describe:

  • the cryptographic operations applied to the JWT,

  • (optionally) additional properties of a JWT.

JSON Web Signature (JWS)

JWT is a JWS using the JWS compact serialization.

JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. The JWS cryptographic mechanisms provide integrity protection for an arbitrary sequence of octets.

There are two closely related serializations for JWS which both share the same cryptographic underpinnings:

A JWS represents the following logical values:

JWS JOSE header

For a JWS, the members of the JSON object(s) representing the JOSE header describe:

  • the digital signature or MAC applied to the JWS-protected header and payload,

  • (optionally) additional properties of a JWS.

JWS defines the following registered header parameter names:

Parameter
Definition
Type
Description

alg

Algorithm

String or URI

jku

JWK Set URL

URI

jwk

JSON Web Key

The jwk header parameter is the public key that corresponds to the key used to digitally sign the JWS

kid

Key ID

String

x5u

X.509 URL

URI

x5c

X.509 Certificate Chain

x5t

X.509 certificate SHA-1 thumbprint

String

The x5t header parameter is a base64url-encoded SHA-1 thumbprint (digest) of the DER encoding of the X.509 certificate corresponding to the key used to digitally sign the JWS

x5t#S256

X.509 Certificate SHA-256 Thumbprint

String

The x5t#S256 header parameter is a base64url-encoded SHA-256 thumbprint (digest) of the DER encoding of the X.509 certificate corresponding to the key used to digitally sign the JWS

typ

Type

The typ header parameter is used by JWS applications to declare the media type of this complete JWS. This is intended for use by the application when more than one kind of object could be present in an application data structure that can contain a JWS. To indicate that this object is a JWT, recommended to use the "JWT" value

cty

Content Type

The cty header parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of the secured content (the payload). In the normal case in which nested signing operations are not employed, the use of this header parameter is not recommended. In the case that nested signing is employed, this header parameter must be present; in this case, the value must be "JWT", to indicate that a nested JWT is carried in this JWT

crit

Critical

Array of the header parameter names present in the JOSE header

JWS payload

The sequence of octets to be secured (the message). The payload can contain an arbitrary sequence of octets.

JWS signature

A digital signature or MAC over the JWS-protected header and payload. Since JWT uses JWS compact serialization, JWS unprotected headers are not used.

JSON Web Encryption (JWE)

JWT is a JWE using the JWE compact serialization.

JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. The JWE cryptographic mechanisms encrypt and provide integrity protection for an arbitrary sequence of octets. JWE utilizes authenticated encryption to ensure the confidentiality and integrity of plaintext and the integrity of the JWE-protected header.

There are two closely related serializations for JWE which both share the same cryptographic underpinnings:

A JWE represents these logical values:

JWE JOSE header

For a JWE, the members of the JSON object(s) representing the JOSE header describe:

  • the encryption applied to the plain text,

  • (optionally) additional properties of a JWE.

JWE defines the following registered header parameter names:

Parameter
Definition
Type
Description

alg

Algorithm

String or URI

enc

Encryption Algorithm

String or URI

zip

Compression Algorithm

String

The zip applied to the plaintext before encryption, if any

jku

JWK Set URL

URI

jwk

JSON Web Key

The jwk header parameter is the public key that corresponds to the key used to encrypt the JWE; this can be used to determine the private key needed to decrypt the JWE

kid

Key ID

String

x5u

X.509 URL

URI

x5c

X.509 Certificate Chain

x5t

X.509 certificate SHA-1 thumbprint

String

The x5t header parameter is a base64url-encoded SHA-1 thumbprint (digest) of the DER encoding of the X.509 certificate corresponding to the key used to encrypt the JWE

x5t#S256

X.509 Certificate SHA-256 Thumbprint

String

The x5t#S256 header parameter is a base64url-encoded SHA-256 thumbprint (digest) of the DER encoding of the X.509 certificate corresponding to the key used to encrypt the JWE

typ

Type

The typ header parameter is used by JWE applications to declare the media type of this complete JWE. This is intended for use by the application when more than one kind of object could be present in an application data structure that can contain a JWE. To indicate that this object is a JWT, recommended to use the "JWT" value

cty

Content Type

The cty header parameter is used by JWE applications to declare the media type [IANA.MediaTypes] of the secured content (the plaintext). In the normal case in which nested encryption operations are not employed, the use of this header parameter is not recommended. In the case that nested encryption is employed, this header parameter must be present; in this case, the value must be "JWT", to indicate that a nested JWT is carried in this JWT

crit

Critical

Array of the header parameter names present in the JOSE header

JWE Encrypted Key

Authenticated Encryption with Associated Data (AEAD) is an algorithm that encrypts a plaintext, allowing additional authenticated data to be specified, and providing built-in integrity checking for the content of a ciphertext and additional authenticated data. AEAD algorithms accept two inputs, a plaintext and an additional authenticated data value, and produce two outputs, a ciphertext and an authentication tag value.

Content encryption key is a symmetric key for the AEAD algorithm used to encrypt a plaintext and produce a ciphertext and an authentication tag.

An encrypted value of a content encryption key. The JWE encrypted key value is specified as an empty sequence of octets for some algorithms.

JWE Initialization Vector

An initialization vector, that is used as an initialization vector value when encrypting a plaintext. Some algorithms may not use an initialization vector, in which case this value is the empty octet sequence.

JWE Ciphertext

A value resulting from authenticated encryption of plaintext with additional authenticated data.

JWE Authentication Tag

Authentication Tag is an output of an AEAD operation that ensures the integrity of the ciphertext and the additional authenticated data.

A value resulting from authenticated encryption of plaintext with additional authenticated data. Some algorithms may not use an authentication tag, in which case this value is the empty octet sequence.

General

Clarification

The kid (key ID) claim is used by the relying application to perform a key lookup. This value can contain a payload to exploit SQL or LDAP injection, Path Traversal or Command Injection vulnerabilities.

Similarly, blindly following the jku (JWK set URL) or x5u (X.509 URL) claim, which may contain an arbitrary URL, could result in Server-Side Request Forgery attacks.

  • Define a list of allowed algorithms that can be used to secure JWT. Do not use block lists.

  • Do not use weak or deprecated algorithms.

  • Disable support for all algorithms in your library except those on an allow list.

  • Validate the alg or enc claims to make sure a JWT is secured by an allowed algorithm.

  • Use each key for exactly one algorithm. Validate it when the cryptographic operation is performed.

Clarification
  • If the exp (expiration date) claim is used, validate that JWT has not expired. Reject expired JWTs.

  • If the iss claim is used, validate that the cryptographic keys used for cryptographic operations in the JWT belong to the issuer. Reject the JWT if they do not.

  • If the sub claim is used, validate that the subject (user) corresponds to a valid subject and/or issuer:subject pair in an application.

  • If the same issuer can issue JWTs that are intended for use by more than one relying party or application:

    • Reject the JWT if the aud claim is not present.

    • Reject the JWT if the aud claim is not associated with the recipient.

  • If the jku claim is used, validate that jku contains a URI from an allow list.

Clarification

The jku claim contains a URI that refers to a resource for a set of public keys (as a JWK set), one of which corresponds to the key used to digitally sign the JWS or one of which the JWE was encrypted. If the jku claim is not properly validated, an attacker can set the jku value to their server that hosts a public key. As a result, they will be able to sign or encrypt JWTs with their corresponding private key.

  • If the jwk claim is used, validate that jwk contains a public key from an allow list.

Clarification

The jwk claim specifies a JSON Web Key (JWK) representing a public key. This public key is considered a trusted key for verification. An attacker could exploit this by forging valid JWS objects by removing the original signature, adding a new public key to the header, and then signing the object using the (attacker-owned) private key associated with the public key embedded in that JWS header.

  • Reject the entire JWT if any of the validations fail (including all cryptographic operations).

JWS-related

  • Disable support of the None algorithm in production. Make sure the None algorithm is disabled by default.

Clarification

The None algorithm allows using JWT tokens without signature. An attacker can abuse the None algorithm support to craft arbitrary JWTs.

For example, the JWT below is a valid JWT that uses the None algorithm and the third part (signature) is empty. In this case, integrity protection is completely absent.

eyJhbGciOiJub25lIn0.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.
  • Make sure the JWT's signature is validated and it is not possible to use a JWT without a signature or with an invalid signature.

  • Disable support of the None algorithm in all environments.

JWE-related

  • Make sure the internal signature is validated after decryption.

References

Depending upon whether the JWT is a or , the corresponding rules for the JOSE header values apply.

The is a compact, URL-safe representation intended for space-constrained environments such as HTTP Authorization headers and URI query parameters.

The represents JWSs as JSON objects and enables multiple signatures and/or MACs to be applied to the same content.

The alg header parameter identifies the cryptographic algorithm used to secure a JWS. You can find a list of possible values in the specification in

The jku header parameter is a URI that refers to a resource for a set of JSON-encoded public keys (as set), one of which corresponds to the key used to digitally sign the JWS

The kid header parameter is a hint indicating which key was used to secure the JWS. When used with a , the kid value is used to match a JWK kid parameter value

The x5u header parameter is a URI that refers to a resource for the in PEM-encoded form corresponding to the key used to digitally sign the JWS

The x5c header parameter contains the corresponding to the key used to digitally sign the JWS

The crit header parameter indicates that extensions and/or are being used that must be understood and processed

The is a compact, URL-safe representation intended for space-constrained environments such as HTTP Authorization headers and URI query parameters.

The represents JWEs as JSON objects and enables the same content to be encrypted to multiple parties.

The alg header parameter identifies the cryptographic algorithm used to encrypt or determine the value of the Content Encryption Key (a symmetric key for the AEAD algorithm). You can find a list of possible values in the specification in

The enc header parameter identifies the content encryption algorithm used to perform authenticated encryption on the plaintext to produce the ciphertext and the authentication tag. This algorithm must be an AEAD algorithm with a specified key length. You can find a list of possible values in the specification in

The jku header parameter is a URI that refers to a resource for a set of JSON-encoded public keys (as set), one of which the JWE was encrypted; this can be used to determine the private key needed to decrypt the JWE

The kid header parameter is a hint indicating which key was used to encrypt the JWE. When used with a , the kid value is used to match a JWK kid parameter value

The x5u header parameter is a URI that refers to a resource for the in PEM-encoded form corresponding to the key used to encrypt the JWE

The x5c header parameter contains the corresponding to the key used to encrypt the JWE

The crit header parameter indicates that extensions and/or are being used that must be understood and processed

Use well-known and up-to-date libraries to implement JWT support. You can find a list of libraries and a description of the provided functionality at .

Do not trust any data that is passed in a JWT. Implement comprehensive input validation for each value that is read from a JWT, see the page.

JWT claims can be used to deliver a payload to exploit vulnerabilities in an application. Implement protection against these attacks in addition to input validation, see the section.

If there is a way to force an application to use a key that is intended for a different algorithm, an attacker can abuse this behaviour to craft valid JWTs, see

Implement proper error and exception handling to avoid situations where the absence of a signature causes JWT validation to be bypassed, see the page.

Comply with requirements from the page.

Comply with requirements from the page when JWTs need to be stored securely in the browser.

Log errors that occur when validating JWTs and working with them, see the page.

Do not pass any sensitive data in the JWT header or payload, see the page.

If a keyed-MAC algorithm is used comply with requirements from the page.

Do not pass any sensitive data in the JWT header, see the page.

JWS Compact Serialization
JWS JSON Serialization
JWE Compact Serialization
JWE JSON Serialization
https://jwt.io/libraries
Input Validation
Vulnerability Mitigation
Application Security Cheat Sheet: JSON Web Token Vulnerabilities - Using the same keys for different algorithms
Error and Exception Handling
Cryptography: Cryptographic Keys Management
Cookie Security
Logging and Monitoring
Sensitive Data Management
Hash-based Message Authentication Code (HMAC)
Sensitive Data Management
RFC7519: JSON Web Token (JWT)
RFC7515: JSON Web Signature (JWS)
RFC7516: JSON Web Encryption (JWE)
RFC 8725: JSON Web Token Best Current Practices
JWS using the JWS compact serialization
JWE using the JWE compact serialization
Registered Claim Names
Public Claim Names
Private Claim Names
JWS
JWE
JWA
section 3.1
JWK
JWK
JWK
X.509 public key certificate or certificate chain
Array of certificate value strings
X.509 public key certificate or certificate chain
IANA.MediaTypes
IANA.MediaTypes
JWA
JWA
section 4.1
JWA
section 5.1
JWK
JWK
JWK
X.509 public key certificate or certificate chain
Array of certificate value strings
X.509 public key certificate or certificate chain
IANA.MediaTypes
IANA.MediaTypes
JWA