n8n 中文文档

嵌入合作伙伴的 Token exchange

提示

功能可用性

Token exchange 可用于:

  • n8n Cloud: Enterprise
  • 自托管: Enterprise

将 N8N_ENV_FEAT_TOKEN_EXCHANGE 环境变量设置为 true 即可启用。自托管实例可以直接设置;在 n8n Cloud 上,请联系 n8n 支持提出请求。

本文适用于运行外部身份提供商(IdP)或生成签名 JWT 后端的嵌入合作伙伴。

提示

预览状态

Token exchange 是由环境变量控制的预览功能。在该功能正式发布之前,环境变量、端点路径和 JWT 声明约定可能会发生变化。请固定 n8n 版本,并在每次升级后重新测试集成。

OAuth 2.0 Token exchange(RFC 8693)允许嵌入合作伙伴对用户进行身份验证,并在嵌入式 n8n 实例中代表用户操作。Token exchange 支持两种用例:

  • iframe SSO:将外部 JWT 交换为 n8n 会话 cookie,以便当您在 iframe 中嵌入 n8n 时用户无缝登录。
  • 委托 API 访问:将外部 JWT 交换为 n8n 访问 token,以代表用户调用 n8n API,例如触发工作流或管理凭据。

两个流程以相同的方式开始。您的后端会铸造一个由私钥签名的短期 JWT。n8n 使用已注册的公钥验证 JWT、解析用户,然后返回会话 cookie 或访问 token。

开始之前

您需要:

  • 启用了 Token exchange 功能的 Enterprise 许可证。
  • 您的实例上设置的预览功能标志:N8N_ENV_FEAT_TOKEN_EXCHANGE=true。
  • 您的 IdP 已发布的 RSA 或 EC 密钥对,或 JWKS 终端节点。参见 生成密钥对。
  • n8n 实例通过 HTTPS 提供服务。浏览器通过普通的 HTTP 拒绝 SameSite=None; Secure 会话 cookie,因此如果没有它,iframe SSO 流会默默地失败。如果您在 TLS 终止代理后面运行 n8n,请确保代理设置 X-Forwarded-Proto 标头。

生成密钥对

您需要一个非对称密钥对。您的后端使用 私钥 签署 JWT,n8n 使用 公钥 验证它们。

RSA (RS256)

# Generate a 2048-bit RSA private key
openssl genrsa -out private.pem 2048

# Extract the public key
openssl rsa -in private.pem -pubout -out public.pem

EC (ES256)

# Generate an EC private key using P-256
openssl ecparam -name prime256v1 -genkey -noout -out private.pem

# Extract the public key
openssl ec -in private.pem -pubout -out public.pem

在您的后端保密 private.pem。您将 public.pem 的内容注册到 n8n 的可信密钥配置中。

如果您的 IdP 已发布 JWKS 端点(就像大多数 OAuth 2.0 和 OIDC 提供商所做的那样),您可以跳过密钥生成并将 n8n 指向 JWKS URL。参见 JWKS 密钥源。

环境变量

所有流程都需要的设置

# Enable the preview module
N8N_ENV_FEAT_TOKEN_EXCHANGE=true

# Register your public key(s) - see Configure trusted keys
N8N_TOKEN_EXCHANGE_TRUSTED_KEYS='[{ ... }]'

每个流程的开关

两个流是独立的。仅启用您使用的端点:

# Iframe SSO: enable the embed login endpoint (POST or GET /rest/auth/embed)
N8N_EMBED_LOGIN_ENABLED=true

# Delegated API access: enable the token exchange endpoint (POST /rest/auth/oauth/token)
N8N_TOKEN_EXCHANGE_ENABLED=true

嵌入登录端点不需要 N8N_TOKEN_EXCHANGE_ENABLED,令牌交换端点不需要 N8N_EMBED_LOGIN_ENABLED。

提示

基于文件的配置

您可以将 _FILE 添加到各个变量,以在单独的文件中提供其配置。有关更多详细信息,请参阅 将敏感数据保存在单独的文件中。

例如,对于大型或多行 JSON,将可信密钥存储在文件中并设置 N8N_TOKEN_EXCHANGE_TRUSTED_KEYS_FILE=/path/to/trusted-keys.json。

可选调整设置

这些都有合理的默认值。您通常不需要更改它们:

变量 默认值 说明
N8N_TOKEN_EXCHANGE_MAX_TOKEN_TTL 900(15 分钟) 已签发 n8n token 的最大生命周期(秒)。实际到期时间取该值、主体 token 的剩余生命周期和参与者 token 的剩余生命周期(如有)中的最小值。
N8N_TOKEN_EXCHANGE_KEY_REFRESH_INTERVAL_SECONDS 300(5 分钟) 当端点未提供缓存生命周期时刷新 JWKS 密钥的回退间隔。每个实例在启动时都会刷新密钥;在多主部署中,只有 leader 实例会定期刷新。
N8N_TOKEN_EXCHANGE_JTI_CLEANUP_INTERVAL_SECONDS 60(1 分钟) n8n 清理过期 replay protection 记录的频率。
N8N_TOKEN_EXCHANGE_JTI_CLEANUP_BATCH_SIZE 1000 每次清理运行删除的最大过期记录数。
N8N_TOKEN_EXCHANGE_EMBED_LOGIN_PER_MINUTE 20 嵌入登录端点的速率限制(每个 IP 每分钟的请求数)。
N8N_TOKEN_EXCHANGE_TOKEN_EXCHANGE_PER_MINUTE 20 Token exchange 端点的速率限制(每个 IP 每分钟的请求数)。

配置可信密钥

N8N_TOKEN_EXCHANGE_TRUSTED_KEYS 环境变量接受 JSON 受信任密钥源数组。每个条目都会告诉 n8n 如何验证来自 IdP 的 JWT。

有两种源类型:static(内联公钥)和 jwks(远程 JWKS 端点)。您可以在同一个数组中混合使用这两种类型。

静态密钥源

当您生成自己的密钥对并想要直接嵌入公钥时,请使用此选项。

{
    "type": "static",
    "kid": "my-key-1",
    "algorithms": ["RS256"],
    "key": "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...contents-of-public.pem...\n-----END PUBLIC KEY-----",
    "issuer": "https://your-backend.example.com",
    "expectedAudience": "https://your-n8n.example.com",
    "allowedRoles": ["global:member"]
}
字段 必需 说明
type 是 必须是 "static"。
kid 是 密钥 ID。必须与传入 JWT 中的 kid 标头匹配。
algorithms 是 允许的签名算法数组,例如 ["RS256"]。参见 支持的算法。
key 是 PEM 编码的公钥。在 JSON 中使用 \n 进行换行。
issuer 是 传入 JWT 中预计有 iss 声明。
expectedAudience 否 如果设置,则 JWT aud 声明必须与此值匹配。如果未设置,n8n 会完全跳过受众验证。始终在生产中使用特定于实例的值(例如 n8n 基础 URL)进行设置。
allowedRoles 否 如果设置,则只能通过 role 声明分配这些角色。如果您特意希望集成来管理管理员用户,则仅包含 global:admin。参见 角色处理。

JWKS 密钥源

当您的 IdP 发布 JWKS 端点时使用此选项。

{
    "type": "jwks",
    "url": "https://idp.example.com/.well-known/jwks.json",
    "issuer": "https://idp.example.com",
    "expectedAudience": "https://your-n8n.example.com",
    "allowedRoles": ["global:member"]
}
字段 必需 说明
type 是 必须是 "jwks"。
url 是 JWKS 端点的 URL。
issuer 是 传入 JWT 中预计有 iss 声明。
expectedAudience 否 如果设置,则 JWT aud 声明必须与此值匹配。如果未设置,n8n 会完全跳过受众验证。始终在生产中使用特定于实例的值(例如 n8n 基础 URL)进行设置。
allowedRoles 否 如果设置,则只能通过 role 声明分配这些角色。参见 角色处理。
cacheTtlSeconds 否 JWKS 端点不发送 Cache-Control: max-age 标头时的回退缓存持续时间。当标头存在时,它优先。默认为 3600 秒。有效值限制在 60 到 86400 秒之间。

完整示例

[
    {
        "type": "static",
        "kid": "my-static-key-1",
        "algorithms": ["RS256"],
        "key": "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...your-key-here...\n-----END PUBLIC KEY-----",
        "issuer": "https://your-backend.example.com",
        "expectedAudience": "https://your-n8n.example.com",
        "allowedRoles": ["global:member"]
    },
    {
        "type": "jwks",
        "url": "https://idp.example.com/.well-known/jwks.json",
        "issuer": "https://idp.example.com",
        "expectedAudience": "https://your-n8n.example.com"
    }
]

支持的算法

n8n 仅接受非对称算法。它不包括 HMAC 和 none。

系列 算法
RSA RS256, RS384, RS512
RSA-PSS PS256, PS384, PS512
椭圆曲线 ES256、ES384、ES512
Edwards 曲线 EdDSA

对于静态密钥,配置中的算法必须全部属于同一系列并与密钥类型匹配。对于 JWKS 密钥,n8n 自动从 JWK alg 和 kty 或 crv 字段推断算法。

必需和可选的 JWT 声明

必需声明

您的 IdP 令牌必须包含以下声明,n8n 才能接受它们:

声明 类型 描述
sub 字符串 主题标识符。 IdP 处的唯一用户 ID。
iss 字符串 (URL) 发行人。必须与您的可信密钥配置中的 issuer 匹配。
aud 字符串或字符串数组 受众。必须在场。仅当在可信密钥源上配置 expectedAudience 时,n8n 才会验证该值。
iat 编号 发布时间为时间戳(Unix 纪元秒)。
exp 数字 过期时间戳(Unix 纪元秒)。
jti 字符串 唯一令牌 ID。 n8n 仅接受每个值一次(重放保护)。

可选声明

声明 类型 描述
email 字符串(有效电子邮件) 用户的电子邮件,用于匹配现有 n8n 用户。 JIT 配置所需,用户 n8n 首次登录尚不知道。除非您确定每个用户都已存在,否则始终发送它。
given_name 字符串 名字,同步到 n8n 用户配置文件。
family_name 字符串 姓氏,已同步到 n8n 用户配置文件。
role 字符串 要分配的 n8n 角色,例如 global:member 或 global:admin。参见用户配置。
nbf 数字 不在时间戳之前。

iframe SSO 流程

在 iframe 中嵌入 n8n 时使用此流程。 n8n 使用会话 cookie 透明地让用户登录。

sequenceDiagram
    participant Browser as User browser
    participant Backend as Your backend
    participant n8n as n8n instance

    Browser->>Backend: 1. Load iframe
    Backend->>Backend: 2. Mint JWT (private key)
    Backend-->>Browser: 3. Return auto-submitting form (token)
    Browser->>n8n: 4. POST /rest/auth/embed (token in body)
    n8n->>n8n: 5. Verify JWT
    n8n->>n8n: 6. Resolve user
    n8n->>n8n: 7. Set session cookie
    n8n-->>Browser: 8. Redirect (with session cookie)
    Browser->>n8n: 9. User is logged in, loads n8n UI

第 1 步:在后端创建 JWT

您的后端创建一个使用您的私钥签名的短期 JWT。

const fs = require('fs');
const jwt = require('jsonwebtoken');
const { randomUUID } = require('crypto');

const privateKey = fs.readFileSync('private.pem', 'utf8');
const now = Math.floor(Date.now() / 1000);

const token = jwt.sign(
    {
        sub: 'user-id-in-your-system',           // unique user identifier
        iss: 'https://your-backend.example.com', // must match trusted key config
        aud: 'https://your-n8n.example.com',     // must match expectedAudience (if set)
        iat: now,
        exp: now + 30,                           // short-lived: 30 seconds
        jti: randomUUID(),                       // unique per request
        email: '[email protected]',               // required for first-time users
        given_name: 'Jane',                      // optional
        family_name: 'Doe',                      // optional
        role: 'global:member',                   // optional
    },
    privateKey,
    { algorithm: 'RS256', header: { kid: 'my-key-1' } }
);

警告

最长 60 秒生命周期

对于嵌入登录流程,JWT 生命周期 (exp - iat) 不得超过 60 秒。 n8n 在服务器端强制执行此操作。

步骤 2:将 token 发送到嵌入端点

将令牌作为表单提交发送到 POST /rest/auth/embed。将 iframe src 指向后端返回自动提交表单的页面:

<form method="POST" action="https://your-n8n.example.com/rest/auth/embed">
    <input type="hidden" name="token" value="<jwt>">
    <input type="hidden" name="redirectTo" value="/workflow/abc123">
</form>
<script>document.forms[0].submit();</script>

可选的 redirectTo 字段仅接受以 / 开头的相对路径。对于绝对 URL 或其他任何内容,n8n 回退到 /。

还有一个 GET /rest/auth/embed?token=<jwt>&redirectTo=/workflow/abc123 变体。首选 POST 形式:使用 GET 时,令牌会出现在服务器和代理日志、浏览器历史记录以及可能的 Referer 标头中。如果您必须使用 GET,请确保您的基础设施从日志中清除查询字符串。

步骤 3:n8n 验证并发出会话

n8n 验证 JWT 签名,解析或配置用户(请参阅 用户配置),设置安全会话 cookie (SameSite=None; Secure),并重定向到指定路径。

第三方 cookie 限制

当 n8n 在与您的产品不同的可注册域上运行时,会话 cookie 是第三方 cookie。浏览器隐私功能,例如 Safari 的智能跟踪预防和 Chrome 的第三方 cookie 限制,可以对其进行阻止或分区,从而破坏 iframe 登录。将 n8n 托管在产品网站的子域上(例如 automation.your-product.example.com),以避免出现这种情况。

委托 API 访问流程

当您的后端需要代表用户调用 n8n API 时,请使用此流程,例如触发工作流程或以编程方式管理凭据。

此流程支持可选的参与者 token进行委托。参与者(例如服务帐户或管理员)代表主体(最终用户)操作。这可以启用审计归因,因此 n8n 会记录谁执行了操作以及代表谁执行操作。

当您提供参与者 token 时,n8n 会使用参与者的身份和权限授权 API 调用。n8n 仅为审计归因记录主体,主体不会限制 token 的功能。这与 RFC 8693 不同,后者通常仍将主体视为有效委托人。请为参与者配置 n8n 角色,只授予集成所需的权限。

sequenceDiagram
    participant Backend as Your backend
    participant n8n as n8n instance

    Backend->>Backend: 1. Mint subject JWT (+ optional actor JWT)
    Backend->>n8n: 2. POST /rest/auth/oauth/token (token-exchange grant)
    n8n->>n8n: 3. Verify JWTs
    n8n->>n8n: 4. Resolve users
    n8n->>n8n: 5. Issue n8n access token
    n8n-->>Backend: 6. access_token, token_type, expires_in
    Backend->>n8n: 7. Call n8n APIs with Bearer token

第 1 步:在后端创建 JWT

创建代表最终用户的主题令牌。嵌入流程的 60 秒限制在此不适用。颁发的 n8n 访问令牌在主体令牌的剩余生命周期、参与者令牌的剩余生命周期(如果存在)和 N8N_TOKEN_EXCHANGE_MAX_TOKEN_TTL(默认 15 分钟)中的最短时间后过期。

const now = Math.floor(Date.now() / 1000);

const subjectToken = jwt.sign(
    {
        sub: 'end-user-id',
        iss: 'https://your-backend.example.com',
        aud: 'https://your-n8n.example.com',
        iat: now,
        exp: now + 900,                         // bounds the issued token's lifetime
        jti: randomUUID(),
        email: '[email protected]',
        role: 'global:member',
    },
    privateKey,
    { algorithm: 'RS256', header: { kid: 'my-key-1' } }
);

对于委托,您还可以创建一个代表执行操作的服务或管理员的参与者 token。参与者的 n8n 角色决定已签发 token 的权限,因此请尽可能使用低权限角色:

const actorToken = jwt.sign(
    {
        sub: 'service-account-id',
        iss: 'https://your-backend.example.com',
        aud: 'https://your-n8n.example.com',
        iat: now,
        exp: now + 900,
        jti: randomUUID(),
        email: '[email protected]',
    },
    privateKey,
    { algorithm: 'RS256', header: { kid: 'my-key-1' } }
);

步骤 2:兑换 n8n 访问 token

curl -X POST https://your-n8n.example.com/rest/auth/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=<subject-jwt>" \
    -d "actor_token=<actor-jwt>"

请求字段(application/x-www-form-urlencoded):

字段 必需 描述
grant_type 是 必须是 urn:ietf:params:oauth:grant-type:token-exchange。
subject_token 是 代表最终用户的 JWT。
subject_token_type 否 token 类型标识符。n8n 接受并忽略此字段。RFC 8693 要求该字段,因此如果使用符合规范的客户端库,请发送 urn:ietf:params:oauth:token-type:jwt。
actor_token 否 代表参与者的 JWT。
actor_token_type 否 参与者 token 类型标识符。与 subject_token_type 一样,n8n 接受并忽略此字段。
requested_token_type 否 请求的 token 类型标识符。n8n 接受并忽略此字段,始终签发访问 token。
scope 否 请求的范围(最多 1024 个字符)。记录在已发行的令牌和审核事件中,但不强制执行。
audience 否 目标受众(最多 1024 个字符)。n8n 接受并忽略此字段。
resource 否 目标资源 URI,以空格分隔(最多 2048 个字符)。记录在已发行的令牌和审核事件中,但不强制执行。

警告

范围不强制执行

已签发的访问 token 携带代理用户的全部权限:发送参与者 token 时使用参与者权限,否则使用主体权限。n8n 仅为审计记录 scope 和 resource,不会据此限制 token。要限制集成可执行的操作,请改用低权限参与者和 allowedRoles 设置。

成功响应(200 OK):

{
    "access_token": "<n8n-jwt>",
    "token_type": "Bearer",
    "expires_in": 900,
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

第 3 步:使用访问 token

在后续的 n8n API 调用中包含该令牌:

curl https://your-n8n.example.com/api/v1/workflows \
    -H "Authorization: Bearer <access-token>"

token 会在 expires_in 秒后过期。过期后请申请新的 token。不要重复使用原来的外部 JWT,因为每个 jti 只能使用一次。

用户配置

当您交换令牌时,n8n 按以下顺序将外部身份解析为 n8n 用户:

  1. 已知身份:n8n 在身份存储中查找 sub 声明。如果之前的 exchange 已将此 sub 链接到 n8n 用户,n8n 就会返回该用户。
  2. 电子邮件回退:如果 sub 未知,但 JWT 包含 email 声明,n8n 会搜索具有该电子邮件地址的现有用户。找到后,n8n 会将外部身份链接到该用户。
  3. 即时(JIT)配置:如果两者都不匹配,n8n 会自动创建新用户。JWT 必须包含 email 声明才能完成此操作。n8n 创建的新用户会禁用密码登录,因此只能通过 Token exchange 进行身份验证。

角色处理

如果包含 role 声明,您的 IdP 就是用户全局角色的事实来源:n8n 会在每次 exchange 时应用该角色,覆盖 n8n UI 中分配的角色。除非您在 IdP 中管理角色,否则请忽略此声明。

场景 行为
新用户,无 role 声明 已分配 global:member。
新用户,有效的 role 声明 分配声明中的角色。如果角色无法识别、为 global:owner 或不在 allowedRoles 中,则 exchange 失败。
现有用户,无 role 声明 角色不变。
现有用户,有效的 role 声明 如果角色不同则更新。如果角色不在 allowedRoles 中,则 exchange 失败。
现有用户、无法识别或 global:owner 角色声明 忽略声明并记录服务器端警告。登录继续,角色不变。
现有用户为 global:owner 完全跳过角色同步。Owner 角色无法通过 Token exchange 更改。

个人资料同步

n8n 在每次登录时将 given_name 和 family_name 声明同步到用户配置文件。仅当值与存储的值不同时,它才会应用更改,并截断长度超过 32 个字符的值。

安全注意事项

短期 token

  • 用于嵌入流程的外部 JWT 生命周期不得超过 60 秒(exp - iat <= 60)。
  • 对于 Token exchange 流程,已签发 n8n token 的到期时间取主体 token 剩余生命周期、参与者 token 剩余生命周期(如有)和 N8N_TOKEN_EXCHANGE_MAX_TOKEN_TTL(默认 900 秒)中的最小值。
  • 在 Token exchange 流程中,如果计算出的已签发 token 剩余生命周期不足 5 秒,n8n 会拒绝请求。

重放保护

每个外部 JWT 必须包含唯一的 jti(JWT ID)声明。n8n 会记录每个 jti,并拒绝任何使用过的 jti。n8n 会自动清理过期的 jti 记录。

仅支持非对称签名

n8n 仅接受非对称算法(RSA、EC、EdDSA)。它在设计上拒绝 HMAC 算法,例如 HS256 和 none。这可确保 n8n 永远不需要访问您的签名密钥。

受众限制

请始终在每个可信密钥源上设置 expectedAudience。如果未设置,n8n 会跳过受众验证,来自已配置发行者的任何有效 token 都可以交换,包括 IdP 为其他服务或其他 n8n 实例铸造的 token。请使用实例专属值,例如 n8n 基础 URL。

角色限制

可信密钥源上的 allowedRoles 字段限制可通过 Token exchange 分配的角色。使用该字段执行最小权限原则,例如将嵌入集成限制为只能配置 global:member 用户。OAuth 的 scope 和 resource 请求字段不会限制权限。参见步骤 2:兑换 n8n 访问 token。

限制嵌入来源

嵌入会话 cookie 使用 SameSite=None,因此浏览器会在任何第三方 iframe 上下文中发送它。请限制可嵌入 n8n 实例的网站:配置反向代理,发送仅列出产品来源的 Content-Security-Policy: frame-ancestors 标头。切勿全局禁用 frame protection。

密钥轮换和泄露

要在不停机的情况下轮换密钥,请向 N8N_TOKEN_EXCHANGE_TRUSTED_KEYS 添加带新 kid 的条目,将后端切换为使用新密钥签名,然后删除旧条目。如果私钥泄露,请立即删除其条目。这会阻止新的 exchange,但已签发的 n8n token 和会话在到期前仍然有效,并受较短 token 生命周期限制。

审计归因

n8n 会为所有 Token exchange 活动发出审计事件:

事件 说明
n8n.audit.token-exchange.succeeded Token exchange 成功。
n8n.audit.token-exchange.failed Token exchange 失败(包含失败原因)。
n8n.audit.token-exchange.embed-login 嵌入登录成功。
n8n.audit.token-exchange.embed-login-failed 嵌入登录失败(有失败原因)。
n8n.audit.token-exchange.user-provisioned 通过 JIT 配置创建的新用户。
n8n.audit.token-exchange.identity-linked 现有用户链接到新的外部身份。
n8n.audit.token-exchange.role-updated 通过 Token exchange 更改用户角色。

使用参与者 token 流程时,n8n 会同时记录主体(被代表者)和参与者(执行操作的人),从而在审计日志中实现完整归因。

验证设置

铸造一个一次性 JWT 并进行交换。将步骤 1 示例保存为 mint-token.js,在末尾添加 console.log(token);,然后运行:

node mint-token.js

然后调用 Token exchange 端点:

curl -X POST https://your-n8n.example.com/rest/auth/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    -d "subject_token=<jwt>"

包含 access_token 的 200 响应可确认密钥、声明和配置均正常。对于嵌入流程,请在浏览器中向 POST /rest/auth/embed 提交新 token,并确认 n8n UI 能够加载。

故障排除

症状 可能原因
两个端点上的 404 预览标志 N8N_ENV_FEAT_TOKEN_EXCHANGE 不是 true,或许可证不包含 Token exchange 功能。n8n 根本不会加载该模块。
501 - Token exchange is not enabled on this instance N8N_TOKEN_EXCHANGE_ENABLED 不是 true。
501 - Embed login is not enabled on this instance N8N_EMBED_LOGIN_ENABLED 不是 true。
400 - unsupported_grant_type grant_type 字段缺失或不完全是 urn:ietf:params:oauth:grant-type:token-exchange。
400 - invalid_grant,描述为 Token exchange failed Token exchange 端点上的 token 验证失败:签名无效、未知 kid、缺少 kid 标头、重放 jti、token 过期或即将过期、受众不匹配或角色不允许。n8n 按设计返回通用描述,具体原因请查看 n8n 服务器日志。
400 - invalid_request,描述为 Token claims validation failed Token exchange 端点上的 JWT 缺少必需声明(sub、iss、aud、iat、exp、jti),或声明类型错误。
嵌入端点返回 401 响应包含具体失败消息,例如 Token has already been used(重放 jti)、Token lifetime exceeds maximum allowed(嵌入 token 必须满足 exp - iat <= 60 秒)或 Token header missing kid。
嵌入端点返回 500 JWT 缺少必需声明或声明类型错误。
iframe 中显示原始 JSON 错误 嵌入登录失败返回 JSON 响应,而不是错误重定向。请根据上表检查消息。
嵌入登录后未设置会话 cookie 实例未通过 HTTPS 提供服务,或 TLS 终止代理未转发 X-Forwarded-Proto。浏览器会拒绝普通 HTTP 上的 SameSite=None; Secure cookie。第三方 cookie 限制也可能阻止 cookie,请参阅第三方 cookie 限制。
首次登录时未创建用户 JWT 缺少 JIT 配置所需的 email 声明。
角色未应用 对于现有用户,n8n 会忽略无法识别的角色声明和 global:owner 角色声明,并记录服务器端警告。allowedRoles 中缺少的有效角色会导致 exchange 失败。参见角色处理。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。