OAuth2 Validator icon

OAuth2 Validator

Validate OAuth2 access tokens against an issuer

Overview

This node validates OAuth2 access tokens against an OpenID Connect issuer. It is designed to verify the authenticity and integrity of bearer tokens typically used in API authorization headers. The node fetches the OpenID Connect configuration from a specified URL, retrieves the JSON Web Key Set (JWKS) for signature verification, and validates claims such as issuer, audience, and expiration.

Common scenarios where this node is beneficial include:

  • Securing API endpoints by validating incoming OAuth2 tokens.
  • Integrating with identity providers that support OpenID Connect.
  • Debugging or inspecting OAuth2 tokens in workflows.
  • Ensuring tokens are valid before proceeding with sensitive operations.

Practical example:

  • A workflow receives HTTP requests with bearer tokens in the Authorization header. This node validates those tokens to ensure they are issued by a trusted provider and have not expired before allowing further processing.

Properties

Name Meaning
Authorization Header The name of the HTTP header containing the authorization token (default: "authorization").
Token Prefix The prefix string to remove from the token value, e.g., "Bearer " for tokens like "Bearer token123".
Options Collection of optional settings:
- Clock Tolerance Number of seconds to allow as clock skew when validating token timestamps (default: 30).
- Default Key ID Default key ID to use if the token header does not specify one (optional).
- Include Token Claims Whether to include the decoded token claims in the output (boolean, default: false).
- Validate Audience Whether to validate the audience claim in the token (boolean, default: true).
- Validate Expiration Whether to validate the token's expiration time (boolean, default: true).
- Validate Issuer Whether to validate the issuer claim in the token (boolean, default: true).

Output

The node produces two outputs:

  1. Validated (main output):

    • Each item contains a json object with:
      • issuer: The expected issuer URL from the OpenID configuration.
      • subject: The subject (sub) claim from the token.
      • audience: The audience (aud) claim from the token.
      • issuedAt: The issued-at timestamp (iat) claim.
      • expiresAt: The expiration timestamp (exp) claim.
      • All original input JSON fields merged.
      • Optionally, if enabled, a claims field containing all decoded token claims.

  2. Failed (secondary output):

    • Items representing tokens that failed validation.
    • Each item includes a json object with:
      • error: Description of the error encountered.
      • issuer: The expected issuer URL.
      • Original input JSON fields merged.

The node does not output binary data.

Dependencies

  • Requires an OpenID Connect configuration URL provided via credentials.
  • Uses the OpenID Connect discovery document to obtain:
    • The issuer URL.
    • The JWKS URI for public keys.
  • Requires an API key credential that includes:
    • The OpenID Connect configuration URL.
    • Client secret (optional, required for decrypting JWE tokens).
    • Expected audience value.
  • Uses the jose library for JWT verification and decryption.
  • Network access to fetch the OpenID Connect configuration and JWKS.

Troubleshooting

  • Missing OpenID Connect URL: The node throws an error if the OpenID Connect configuration URL is not set in credentials.
  • Failed to fetch OpenID Connect configuration: Network issues or invalid URL can cause failure; check connectivity and URL correctness.
  • Invalid OpenID Connect configuration: If the fetched config lacks issuer or jwks_uri, the node will error.
  • Authorization header missing: If the specified header is not found in the input data, an error is thrown.
  • No token found after prefix removal: If the token is empty after removing the prefix, validation fails.
  • JWS verification failure: Indicates signature verification failed; could be due to wrong keys or tampered token.
  • JWE decryption failure: If the token is encrypted, a client secret must be configured; otherwise, decryption fails.
  • Issuer or audience mismatch: Validation errors occur if token claims do not match expected values.
  • Token expired or issued in the future: Time-based validations fail if token timestamps are invalid considering clock tolerance.

To resolve these:

  • Ensure credentials are properly configured with the OpenID Connect URL and client secret if needed.
  • Verify the input data contains the correct authorization header.
  • Confirm token prefixes match the actual token format.
  • Check system clock synchronization to avoid timing issues.
  • Review token issuer and audience claims against expected values.

Links and References

Discussion