External JWT login support added for embedded n8n

afitzek

·Apr 1, 2026·#27881feat(core): Add embed auth controller and token exchange service skeleton (no-changelog)

This PR lays the groundwork for authenticating into embedded n8n instances using external JWT tokens — adding an auth controller, JWT verification pipeline, and supporting services.

n8n instances embedded in external applications can now authenticate users via external JWT tokens. A new embed auth controller exposes GET and POST endpoints at /auth/embed that accept external tokens, validate them through a complete verification pipeline, issue an n8n session cookie, and redirect the user to the app.

The verification pipeline decodes the JWT header to extract the key ID, looks up the trusted signing key, cryptographically verifies the signature, validates claims against a Zod schema, enforces a maximum 60-second lifetime for login tokens, and consumes the JTI to prevent replay attacks. This means external identity providers can issue short-lived tokens that n8n can trust without managing its own credentials.

Supporting services for key lookup, JTI storage, and identity resolution are wired as stubs — they return safe defaults or throw NotImplemented errors. The real implementations will arrive in follow-up tickets, but the verification flow is complete and testable. The entire feature is gated behind the N8N_ENV_FEAT_TOKEN_EXCHANGE environment variable.

This work is part of a broader initiative to support OAuth 2.0 token exchange (RFC 8693) for n8n embed scenarios, where organizations want to embed workflow automation into portals that already have authenticated users.

View Original GitHub DescriptionFact Check

Summary

Adds the foundation for the embed authentication flow, building on top of the token exchange controller (#27844):

Embed auth controller (/auth/embed): GET and POST endpoints that accept external JWTs, verify them via the token exchange service, issue an n8n session cookie, and redirect to the app. Marked skipAuth since the JWT itself is the authentication.
Token exchange service: Full JWT verification pipeline — decode header to extract kid, look up trusted key source, cryptographically verify signature, validate claims against Zod schema, enforce max token lifetime (60s for login tokens), and consume JTI to prevent replay attacks.
Supporting services (shell/stub): TrustedKeyService (key lookup by kid), JtiStoreService (replay prevention via JTI consumption), IdentityResolutionService (map external claims → n8n User).
API DTOs: EmbedLoginBodyDto and EmbedLoginQueryDto for input validation.
Module wiring: Token exchange module registers both the RFC 8693 controller and the new embed auth controller behind a feature flag (N8N_ENV_FEAT_TOKEN_EXCHANGE).
Unit tests: Controller tests and comprehensive token exchange service tests covering signature verification, claim validation, lifetime enforcement, and replay prevention.

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/IAM-457

Review / Merge checklist

PR title and summary are descriptive. (conventions)
Docs updated or follow-up ticket created.
Tests included.
PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)