Skip to content

用于 OAuth 2.0 凭据的 JWE 令牌解密(JWE token decryption for OAuth 2.0 credentials)#

功能可用性

  • 从 n8n v2.21.0 起可用。
  • 在任何设置了 N8N_ENV_FEAT_OAUTH2_JWE 环境变量为 true 的 n8n 实例上可用。本地自托管实例可以直接设置。在云端，请联系 n8n 支持请求此功能。
  • 需要一个可以将令牌加密为 JWE 的身份提供者（IdP）。

预览功能

JWE 令牌解密处于预览状态，并受到环境标志的限制。字段名称、环境变量、JWKS 端点路径以及支持的算法在功能达到一般可用性之前可能会发生变化。在每次升级后，请固定你的 n8n 版本并重新测试你的 OAuth 2.0 凭据。

JWE 令牌解密允许你的身份提供者返回加密为 JWE 的 OAuth 2.0 访问令牌和 ID 令牌。你的 n8n 实例在 OAuth 回调时使用从不离开实例的私钥解密令牌。这可以保护令牌内容免受位于你的 IdP 和 n8n 之间的任何内容的影响，包括反向代理、浏览器和日志。

🌐 JWE token decryption lets your identity provider return OAuth 2.0 access and ID tokens encrypted as JWE. Your n8n instance decrypts the tokens on the OAuth callback using a private key that never leaves the instance. This protects token contents from anything that sits between your IdP and n8n, including reverse proxies, browsers, and logs.

JWE 令牌解密的工作原理(How JWE token decryption works)#

当你启用此功能时，n8n：

🌐 When you enable the feature, n8n:

  1. 在启动时生成 RSA 密钥对，并将私钥存储在数据库中，私钥已使用你的实例加密密钥加密。
  2. 在实例范围的 JWKS 端点上发布匹配的公钥，以便你的身份提供者可以获取它。
  3. 在 OAuth 回调中使用与 JWE 头中的 kid 匹配的私钥解密传入的 JWE 令牌。

身份提供者使用它从你的 JWKS 端点获取的公钥加密每个令牌。只有你的实例能够解密结果。

🌐 The IdP encrypts each token with the public key it fetched from your JWKS endpoint. Only your instance can decrypt the result.

在你开始之前(Before you begin)#

你需要：

🌐 You need:

  • N8N_ENV_FEAT_OAUTH2_JWE=true 在你的 n8n 实例上。自托管实例可以直接启用此功能。在云端，请联系 n8n 支持以请求此功能。
  • 所有 n8n 实例，包括主节点和工作节点，共享相同的 N8N_ENCRYPTION_KEY 值。n8n 使用此实例密钥来加密静态存储的 JWE 私钥。
  • 支持使用 RSA-OAEP-256 密钥加密算法的 JWE 加密令牌的身份提供者 (IdP)。

启用 JWE 令牌解密(Enable JWE token decryption)#

  1. 在所有 n8n 实例上设置以下环境变量，包括主实例和工作实例：

    1
    N8N_ENV_FEAT_OAUTH2_JWE=true

  2. 重启所有实例。启动时，n8n 会生成 RSA 密钥对，并在 JWKS 端点发布公钥。

  3. 要确认该功能已激活，请请求 JWKS 端点并检查它是否返回一个带有 "alg": "RSA-OAEP-256" 的密钥：

    1
    curl https://<your-n8n-host>/rest/.well-known/jwks.json

配置你的身份提供者(Configure your identity provider)#

在你的 IdP 上的 OAuth 2.0 客户端或应用配置中：

🌐 In the OAuth 2.0 client or application configuration on your IdP:

  1. 为 n8n 连接的客户端启用加密令牌。
  2. 将客户端的 JWKS URI 设置为你实例的 JWKS 端点。n8n 会在凭证上显示此 URL，因此在创建凭证后，你可以直接从那里复制它（参见下一节）。
  3. 选择 RSA-OAEP-256 作为密钥加密算法（alg）。将其与你的身份提供者（IdP）支持的任何内容加密算法（enc）配对，例如 A128CBC-HS256 或 A256GCM。

??? 注意 “示例：Okta”

1
2
3
4
1. 在 Okta 管理控制台中，打开 n8n 使用的 OAuth 2.0 应用，或创建一个新的 Web 应用。
2. 在应用的 OpenID Connect 设置中，启用令牌加密。
3. 将 **密钥管理算法** 设置为 `RSA-OAEP-256`，并选择一个内容加密算法（例如 `A256GCM`）。
4. 将 **JWKS URI** 设置为 n8n 在凭证的 **JWKS URI** 字段中显示的值。

在 n8n 中配置凭证(Configure the credential in n8n)#

  1. 创建或编辑一个 OAuth 2.0 API 凭证。
  2. 打开加密令牌 (JWE)。
  3. 如果你还没有这样做，请从 JWKS URI 字段复制值，并将其粘贴到你的 IdP 的 JWKS URI 设置中。
  4. 保存凭据并连接。n8n 会解密你的身份提供者返回的令牌，并将解密后的形式存储以在工作流中使用。

你的 IdP 的响应必须至少包含一个 JWE 加密的令牌（访问令牌、ID 令牌或两者）。如果响应完全是明文，n8n 会以错误 Expected at least one JWE-encrypted token but received only plaintext 拒绝它。

🌐 The response from your IdP must contain at least one JWE-encrypted token (access token, ID token, or both). If the response is fully plaintext, n8n rejects it with the error Expected at least one JWE-encrypted token but received only plaintext.

JWKS 端点参考(JWKS endpoint reference)#

n8n 在以下位置公开实例的公钥：

🌐 n8n exposes the instance's public encryption keys at:

1
<instance-base-url>/<rest-endpoint>/.well-known/jwks.json
属性 值
默认路径 /rest/.well-known/jwks.json
认证 无（公开访问，按设计）
速率限制 每个 IP 每分钟 N8N_OAUTH_JWE_JWKS_PER_MINUTE 次请求（默认 60）
缓存头 Cache-Control: public, max-age=3600, must-revalidate
响应格式 JWK 集 (RFC 7517 §5)

如果你自定义了 N8N_ENDPOINT_REST，请在路径中将 rest 替换为你的值。

🌐 If you customized N8N_ENDPOINT_REST, substitute your value for rest in the path.

支持的算法(Supported algorithms)#

n8n 支持用于密钥加密的 RSA-OAEP-256。在加密令牌时，将你的 IdP 配置为使用此 alg 值。n8n 不限制内容加密算法（enc）；可以使用你的 IdP 支持的任何值。

🌐 n8n supports RSA-OAEP-256 for key encryption. Configure your IdP to use this alg value when encrypting tokens. n8n doesn't restrict content encryption algorithms (enc); use any value your IdP supports.

JWKS 模式保留了椭圆曲线算法（ECDH-ES 及其变体），但 n8n 尚未生成 EC 密钥。

🌐 The JWKS schema reserves elliptic-curve algorithms (ECDH-ES and variants), but n8n doesn't yet generate EC keys.

故障排除(Troubleshooting)#

  • 加密令牌（JWE）切换开关没有出现在凭证上。 请确认你已在每个 n8n 实例上设置了 N8N_ENV_FEAT_OAUTH2_JWE=true，并且已重启所有实例。
  • 错误 Expected at least one JWE-encrypted token but received only plaintext。 身份提供者返回了明文令牌。请确认你已在身份提供者中为客户端启用了令牌加密，并且身份提供者已从你的 JWKS 端点获取了密钥。
  • 身份提供者无法获取 JWKS URI。 请检查 JWKS 端点是否可以从你的身份提供者访问。反向代理和身份验证中间件有时会阻止 /rest/.well-known/jwks.json。该端点必须可以在无需身份验证的情况下公开访问。
  • 身份提供者（IdP）获取 JWKS 频率过高，从而被限制。 增加你 n8n 实例上的 N8N_OAUTH_JWE_JWKS_PER_MINUTE，或者配置你的 IdP 在整个 max-age 窗口期间缓存 JWKS 响应。