JWT Auth Validate icon

JWT Auth Validate

Validate JWT structure and claims without signature verification

Overview

This node validates the structure and claims of a JWT (JSON Web Token) without verifying its signature. It is useful when you want to quickly check if a JWT token is well-formed and meets certain claim requirements, such as expiration, issuer, audience, or custom claims, without needing the secret or public key for signature verification.

Common scenarios include:

  • Pre-validating tokens before passing them to other services.
  • Extracting and validating tokens from HTTP headers, JSON fields, or raw strings.
  • Decoding tokens safely or unsafely (decode only mode).
  • Ensuring tokens meet organizational policies on claims like issuer, audience, subject, and required claims.

Practical example:

  • An API gateway extracts a JWT from the Authorization header and uses this node to validate that the token is not expired, has the expected issuer and audience, and contains required claims like sub and email.
  • A workflow receives JSON data containing a JWT in a nested field and validates it before processing user requests.

Properties

Name Meaning
Token Source Where to extract the JWT token from. Options:
- Authorization Header (Bearer token)
- JSON Field (supports dot notation for nested fields)
- Raw String (directly provide the token string)
Header Name Name of the HTTP header containing the token (used if Token Source is Authorization Header). Default: "authorization"
Field Name JSON field containing the token (supports dot notation for nested fields) (used if Token Source is JSON Field). Default: "token"
Token Raw JWT token string (used if Token Source is Raw String)
Validation Options Collection of options to validate standard JWT claims:
- Check Expiration (boolean): Validate the exp claim (default true)
- Check Not Before (boolean): Validate the nbf claim (default true)
- Clock Tolerance (seconds): Allowed clock skew (default 5)
- Expected Issuer (string): Expected value of the iss claim
- Expected Audience (string): Expected value of the aud claim
- Expected Subject (string): Expected value of the sub claim
- Required Claims (string): Comma-separated list of claims that must be present
Additional Options Collection of additional settings:
- Custom Claims: List of custom claims to validate with name, expected value, and match type (exact, contains, regex)
- Decode Only (boolean): Only decode token without validation (unsafe)
- Include Token Header (boolean): Include JWT header in output
- Pass Through Original Data (boolean): Whether to pass through original input data in output (default true)

Output

The node produces two outputs:

  1. Valid output (first output):

    • JSON object with:
      • valid: true
      • payload: The decoded JWT payload (claims)
      • header: (optional) The decoded JWT header if requested
      • originalData: (optional) The original input JSON data passed through if enabled
      • note or warning: Informational messages about validation or decode-only mode

  2. Invalid output (second output):

    • JSON object with:
      • valid: false
      • error: Error message describing why validation failed (e.g., token missing, expired, claim mismatch)
      • itemIndex: Index of the input item that caused the error
      • originalData: (optional) The original input JSON data passed through if enabled

No binary data is produced by this node.

Dependencies

  • Uses the jose library for decoding JWT tokens and headers.
  • Utilizes internal utility classes for extracting tokens and validating claims.
  • No external API calls or credentials are required.
  • No special environment variables needed.

Troubleshooting

  • No token found: Ensure the token source setting matches where your JWT is located (header, JSON field, or raw string). Check header name or JSON field path correctness.
  • Invalid JWT structure: The token must have exactly three parts separated by dots (.). Verify the token format.
  • Token expired: The exp claim indicates the token is no longer valid. Adjust system clock or check token issuance.
  • Token not valid yet: The nbf claim indicates the token is not active yet. Check system clock and token timing.
  • Issuer/Audience/Subject mismatch: The token's claims do not match expected values. Confirm your validation options and token contents.
  • Required claims missing: The token lacks one or more claims specified as required.
  • Custom claim validation failed: One or more custom claims did not meet the expected criteria.
  • Decode only mode warning: When using decode only mode, the token is not validated and may be unsafe to trust.

To resolve errors, verify your input token, configuration of extraction method, and validation options carefully.

Links and References

Discussion