JWT Auth

Sign, decode, verify, and validate JWT tokens

Actions4

Overview

This node provides functionality to work with JWT (JSON Web Tokens) including signing, decoding, verifying, and validating tokens. It is useful in scenarios where you need to authenticate or authorize users or services by issuing tokens, inspecting token contents, or ensuring token integrity and validity.

Practical examples:

Sign: Create a JWT token for user authentication with custom claims.
Decode: Extract information from a JWT without verifying its signature, e.g., to read user roles.
Verify: Confirm the token’s signature against a JWKS endpoint and validate claims like issuer and audience.
Validate: Check the token structure and claims without verifying the signature, useful for quick sanity checks.

Properties

Name	Meaning
Token Source	Where to extract the JWT token from. Options: Authorization Header (Bearer token), JSON Field, Raw String
Header Name	Name of the header containing the token (used if Token Source is Authorization Header)
Field Name	JSON field containing the token (supports dot notation; used if Token Source is JSON Field)
Token	Raw JWT token string (used if Token Source is Raw String)
Options	Collection of additional options depending on operation:
- Include Issued At	Whether to include the `iat` claim when signing
- Complete	Return header and signature along with payload when decoding
- Clock Tolerance (seconds)	Allowed clock skew for expiration (`exp`) and not before (`nbf`) claims during verify/validate
- Ignore Expiration	Whether to ignore token expiration during verify/validate
- Ignore Not Before	Whether to ignore the `nbf` claim during verify/validate
- Required Claims	Comma-separated list of claims that must be present during verify/validate
- Pass Through	Whether to pass through the original input data alongside the output

Output

The node outputs JSON objects representing the result of the chosen operation:

Sign: Outputs an object containing the signed JWT token string, the payload used, and the algorithm.
```
{
  "token": "<signed JWT token>",
  "payload": { /* JWT claims */ },
  "algorithm": "alg"
}
```

Decode: Outputs the decoded JWT payload. If the "Complete" option is enabled, it also includes the JWT header and signature parts.

// Without complete
{
  /* decoded payload claims */
}

// With complete
{
  "header": { /* JWT header */ },
  "payload": { /* JWT payload */ },
  "signature": "<signature part>"
}

Verify: Outputs an object indicating validity, the verified payload, and header. Throws errors if verification fails.
```
{
  "valid": true,
  "payload": { /* verified claims */ },
  "header": { /* JWT header */ }
}
```

Validate: Outputs an object indicating validity, the decoded payload and header, and a note that signature was not verified.

{
  "valid": true,
  "payload": { /* decoded claims */ },
  "header": { /* JWT header */ },
  "note": "Structure and claims validated (signature NOT verified)"
}

If the "Pass Through" option is enabled, the original input JSON data is included under the originalData key in the output.

The node does not output binary data.

Dependencies

Requires an API key credential for signing operations.
Requires a JWKS URL credential for verifying JWT signatures.
Uses the external jose library for JWT operations.
Makes HTTP requests to fetch JWKS keys for verification.
Requires proper configuration of credentials with keys, algorithms, and URLs as applicable.

Troubleshooting

No token found: Occurs if the token cannot be extracted from the specified source (header, JSON field, or raw string). Ensure the token is correctly provided and the correct source and field/header names are set.
Invalid JWKS response: missing keys array: The JWKS endpoint did not return a valid keys array. Verify the JWKS URL and its response format.
Token expired at ...: The token's expiration time has passed. Either renew the token or enable "Ignore Expiration" if appropriate.
Token not valid until ...: The token's "not before" claim indicates it is not yet valid. Adjust system clocks or enable "Ignore Not Before" if needed.
Invalid JWT structure: The token does not have the expected three parts separated by dots. Check the token format.
Unsupported key type: The signing key type is not supported. Use a supported key format such as passphrase, PEM, or JWK.
Missing required claims: The token does not contain all claims specified in "Required Claims". Adjust the token or the required claims list.