@chez14org/n8n-nodes-oidc-auth-webhook

This is an n8n community node. It gives you a webhook trigger that only starts
the workflow when the caller presents a valid JWT bearer token — either a token
you've signed yourself (verified against a static public key) or a real OpenID
Connect ID token (verified against an issuer's published JWKS, resolved via its
.well-known/openid-configuration discovery document).

Typical use case: exposing an n8n webhook that should only be callable with a
Google ID token (e.g. minted via gcloud auth print-identity-token) or an ID
token obtained through oidc-agent
against another OpenID Provider, instead of a shared static secret.

n8n is a fair-code
licensed workflow automation
platform.

Installation Operations
Credentials Compatibility Usage
Resources Version history

Installation

Follow the installation
guide in the
n8n community nodes documentation.

This package ships a real npm runtime dependency
(jose, for JWT/JWKS verification). It works
normally on any self-hosted n8n instance, where npm/pnpm installs the
package's dependencies like any other npm package.

Operations

OIDC Auth Webhook is a trigger node (like n8n's built-in Webhook node) with
these settings:

On every incoming request the node:

1. Reads the Authorization: Bearer <token> header. Missing or malformed →
   401.

2. Verifies the token's signature against whichever credential is selected.

3. Checks aud (and, for OpenID Discovery, iss) via the JWT library's own
   claim validation, then checks any extra Required Claims you configured.

4. On success, starts the workflow with the request's headers, params,
   query, and body, plus a jwt object containing the verified claims:

   {
     "headers": { "...": "..." },
     "params": {},
     "query": {},
     "body": {},
     "jwt": {
       "valid": true,
       "claims": { "iss": "...", "aud": "...", "sub": "...", "...": "..." },
       "header": { "alg": "RS256", "...": "..." }
     }
   }
   

5. On any failure (missing token, bad signature, expired, wrong audience/issuer,
   claims mismatch, or an unreachable discovery document) the node responds
   401 with a JSON error body itself and the workflow does not run.

Credentials

Two separate credential types are provided, matched to the two ways you might
want to trust an incoming token. Pick one per node via the Authentication
property.

JWT Auth (Public Key)

Use this when you're issuing the tokens yourself (or otherwise have a fixed
public key to check against), rather than trusting a third-party identity
provider's live JWKS endpoint.

JWT Auth (OpenID Discovery)

Use this to trust a real OpenID Provider (Google, Auth0, Okta, Keycloak, your
own OIDC IdP, ...) without having to copy its signing keys in yourself.

The credential's connection test just confirms the discovery URL is reachable —
actual per-request token verification always happens in the webhook node itself.

How the JWKS lookup and caching works

Nothing is downloaded on every request. The first time a discovery URL or
public-key set is used, the node fetches what it needs and keeps it in memory
for the lifetime of the running n8n process:

• The discovery document (jwks_uri and issuer) is cached per discovery URL.
• The remote JWKS key set is cached per jwks_uri, reusing jose's built-in
  createRemoteJWKSet
  caching: keys are only re-fetched when a token references a key id (kid)
  that isn't in the cache yet, and re-fetches are rate-limited (~30s cooldown)
  so a forged kid can't be used to hammer the discovery endpoint.
• Public keys pasted into the JWT Auth (Public Key) credential are parsed once
  and cached by a hash of the PEM text + algorithm, so editing the credential
  naturally invalidates the cache.

There is intentionally no manual "clear cache" button or configurable TTL,
matching how tools like HashiCorp Vault's JWT/OIDC auth method and jose itself
handle this: key rotation on the provider's side (publishing a new key while
briefly keeping the old one) is what triggers a refresh. A change to the
discovery document itself (e.g. a provider migrating its JWKS endpoint) requires
an n8n restart to pick up.

Claim matching (Required Claims)

Required Claims uses "bound claims" semantics (the same idea as Vault's
bound_claims): a JSON object mapping a claim name to a single value (exact
match) or an array of values (OR), with all keys in the object required to match
(AND). See docs/claims.md for the full rules, a worked
examples table, and how this relates to the Verify Audience toggle above.

Compatibility

Requires n8n-workflow (peer dependency, any version the n8n instance provides)
and a recent self-hosted n8n. Not compatible with n8n Cloud's verified community
node program (see Installation).

Usage

Public key setup (self-signed tokens)

1. Generate a keypair and sign a test token, e.g.:

   openssl genrsa -out private.pem 2048
   openssl rsa -in private.pem -pubout -out public.pem
   

2. Add an OIDC Auth Webhook node, set Authentication to JWT (Public
   Key).
3. Create a JWT Auth (Public Key) credential, paste public.pem's contents,
   set Algorithm to match how you signed the token (e.g. RS256).
4. Call the webhook with Authorization: Bearer <token>.

OpenID Discovery setup (e.g. Google ID tokens)

1. Add an OIDC Auth Webhook node, set Authentication to JWT (OpenID
   Discovery).
2. Create a JWT Auth (OpenID Discovery) credential:
   • OpenID Configuration URL:
     https://accounts.google.com/.well-known/openid-configuration
   • Expected Audience: your OAuth client ID (the token's aud claim)
3. Activate the workflow — with the node's defaults this exposes it at
   https://domain.tld/webhook/oidc (replace domain.tld with your n8n
   instance's actual host).

Calling it with a Google ID token (gcloud)

curl https://domain.tld/webhook/oidc \
  -H "Authorization: Bearer $(gcloud auth print-identity-token --audiences=your-client-id)"

Calling it with oidc-agent

oidc-agent is a provider-agnostic
alternative: after registering an account once with oidc-gen <shortname>,
oidc-token <shortname> prints a fresh token for it.

curl https://domain.tld/webhook/oidc \
  -H "Authorization: Bearer $(oidc-token my-provider)"

Resources

• n8n community nodes
  documentation
• OpenID Connect Discovery
  1.0
• jose — the JWT/JWKS library this node uses
  internally
• oidc-agent — CLI tool for
  obtaining OIDC tokens

Version history

0.1.0

Initial release: the OIDC Auth Webhook trigger node, plus the JWT Auth (Public
Key) and JWT Auth (OpenID Discovery) credentials.