n8n 中文文档

OAuth 2.0 凭证的 JWE 令牌解密

提示

Feature availability 功能可用性

  • JWE token 解密从 n8n 2.21.0 起可用。
  • 可在 N8N_ENV_FEAT_OAUTH2_JWE 环境变量设置为 true 的任何 n8n 实例上使用。自托管实例可以直接设置。在云端,请联系 n8n 支持来请求。
  • 需要可以将令牌加密为 JWE 的身份提供商 (IdP)。

提示

预览状态

JWE token 解密处于 Preview 状态,并由环境变量控制。在该功能正式发布之前,字段名称、环境变量、JWKS 端点路径和支持的算法可能会发生变化。请固定 n8n 版本,并在每次升级后重新测试 OAuth 2.0 凭据。

JWE 令牌解密可让您的身份提供商返回加密为 JWE 的 OAuth 2.0 访问和 ID 令牌。您的 n8n 实例使用永远不会离开实例的私钥来解密 OAuth 回调上的令牌。这可以保护令牌内容免受 IdP 和 n8n 之间任何内容的影响,包括反向代理、浏览器和日志。

JWE 令牌解密的工作原理

启用此功能后,n8n 会:

  1. 在启动时生成 RSA 密钥对,并使用实例加密密钥加密私钥后存储到数据库。
  2. 在实例级 JWKS 端点发布匹配的公钥,供 IdP 获取。
  3. 在 OAuth callback 中使用与 JWE header 中 kid 匹配的私钥解密传入的 JWE token。

IdP 会使用从你的 JWKS 端点获取的公钥加密每个 token。只有你的实例可以解密结果。

开始之前

你需要:

  • 在 n8n 实例上设置 N8N_ENV_FEAT_OAUTH2_JWE=true。自托管实例可以直接启用。在 Cloud 上,请联系 n8n 支持请求启用。
  • 所有 n8n 实例(主实例和 worker)共享同一个 N8N_ENCRYPTION_KEY 值。n8n 使用这个实例密钥加密静态存储的 JWE 私钥。
  • 一个支持使用 RSA-OAEP-256 密钥加密算法的 JWE 加密 token 的 IdP。

启用 JWE 令牌解密

  1. 在所有 n8n 实例(包括主实例和 worker)上设置以下环境变量:

    sh N8N_ENV_FEAT_OAUTH2_JWE=true

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

  3. 要确认功能已启用,请请求 JWKS 端点,并检查它是否返回一个带有 "alg": "RSA-OAEP-256" 的 key:

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

配置您的身份提供商

在 IdP 的 OAuth 2.0 客户端或应用配置中:

  1. 为 n8n 连接的客户端启用加密 token。
  2. 将客户端的 JWKS URI 设置为你的实例 JWKS 端点。n8n 会在凭据中显示这个 URL,因此你创建凭据后可以直接从那里复制(见下一节)。
  3. 选择 RSA-OAEP-256 作为密钥加密算法(alg)。再搭配 IdP 支持的任意内容加密算法(enc),例如 A128CBC-HS256 或 A256GCM。
示例:Okta 1. 在 Okta 管理控制台中,打开 n8n 使用的 OAuth 2.0 应用程序,或创建一个新的 Web 应用程序。 2. 在应用程序的 OpenID Connect 设置下,启用令牌加密。 3. 将 **Key management algorithm 密钥管理算法** 设置为 `RSA-OAEP-256` 并选择内容加密算法(例如 `A256GCM`)。 4. 将 **JWKS URI** 设置为凭证 **JWKS URI** 字段中显示的值 n8n。

在n8n 中配置凭证

  1. 创建或编辑 OAuth 2.0 API 凭证。
  2. 打开 Encrypted Tokens (JWE) 加密令牌 (JWE)。
  3. 复制 JWKS URI 字段中的值并将其粘贴到 IdP 上的 JWKS URI 设置中(如果您尚未执行此操作)。
  4. 保存凭据并连接。 n8n 解密 IdP 返回的令牌并存储解密的表单以在工作流程中使用。

IdP 的响应必须至少包含一个 JWE 加密 token(access token、ID token,或两者都有)。如果响应完全是明文,n8n 会拒绝它,并返回错误 Expected at least one JWE-encrypted token but received only plaintext。

JWKS 端点参考

n8n 在以下位置公开实例的加密公钥:

<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。

支持的算法

n8n 支持使用 RSA-OAEP-256 进行密钥加密。请配置 IdP 在加密 token 时使用此 alg 值。n8n 不限制内容加密算法(enc);可使用 IdP 支持的任何值。

JWKS schema 预留了椭圆曲线算法(ECDH-ES 及其变体),但 n8n 目前还不会生成 EC key。

故障排除

  • 凭据上未显示 Encrypted Tokens (JWE) 开关。确认你已在每个 n8n 实例上设置 N8N_ENV_FEAT_OAUTH2_JWE=true,并且已重启所有实例。
  • 出现错误 Expected at least one JWE-encrypted token but received only plaintext。IdP 返回了明文 token。确认你已在 IdP 中为该客户端启用 token encryption,并且 IdP 已从你的 JWKS 端点获取 key。
  • IdP 无法获取 JWKS URI。检查 IdP 是否可以访问 JWKS 端点。反向代理和身份验证中间件有时会阻止 /rest/.well-known/jwks.json。该端点必须无需身份验证即可公开访问。
  • IdP 过于频繁地获取 JWKS 并触发速率限制。提高 n8n 实例上的 N8N_OAUTH_JWE_JWKS_PER_MINUTE,或配置 IdP 在完整的 max-age 窗口内缓存 JWKS 响应。

相关资源

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