Skip to content

OAuth 2.0 凭据的 JWE token 解密#

功能可用性

  • 从 n8n v2.21.0 开始可用。
  • 适用于任何将 N8N_ENV_FEAT_OAUTH2_JWE 环境变量设为 true 的 n8n 实例。自托管实例可以直接设置。在 Cloud 上，请联系 n8n 支持请求启用。
  • 需要支持将 token 加密为 JWE 的身份提供程序（IdP）。

预览功能

JWE token 解密处于预览阶段，并由环境变量开关控制。在功能正式可用前，字段名称、环境变量、JWKS 端点路径以及支持的算法都可能变化。请固定你的 n8n 版本，并在每次升级后重新测试 OAuth 2.0 凭据。

JWE token 解密允许你的身份提供程序返回以 JWE 加密的 OAuth 2.0 access token 和 ID token。你的 n8n 实例会在 OAuth callback 中使用永不离开实例的私钥解密 token。这可以保护 token 内容不被位于 IdP 与 n8n 之间的任何组件读取，包括反向代理、浏览器和日志。

JWE token 解密如何工作#

启用此功能后，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 token 解密#

  1. 在所有 n8n 实例（包括主实例和 worker）上设置以下环境变量：

    1
    N8N_ENV_FEAT_OAUTH2_JWE=true

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

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

    1
    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。
Example: Okta
  1. 在 Okta admin console 中，打开 n8n 使用的 OAuth 2.0 应用，或创建新的 web application。
  2. 在应用的 OpenID Connect 设置下，启用 token encryption。
  3. 将 Key management algorithm 设为 RSA-OAEP-256，并选择一个内容加密算法（例如 A256GCM）。
  4. 将 JWKS URI 设为 n8n 在凭据 JWKS URI 字段中显示的值。

在 n8n 中配置凭据#

  1. 创建或编辑 OAuth 2.0 API 凭据。
  2. 打开 Encrypted Tokens (JWE) 加密 token (JWE) 开关。
  3. 如果尚未设置，请从 JWKS URI 字段复制值，并粘贴到 IdP 的 JWKS URI 设置中。
  4. 保存凭据并连接。n8n 会解密 IdP 返回的 token，并存储解密后的形式，供工作流使用。

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

JWKS 端点参考#

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

1
<instance-base-url>/<rest-endpoint>/.well-known/jwks.json
属性 值
默认路径 /rest/.well-known/jwks.json
身份验证 无（按设计公开可访问）
速率限制 每个 IP 每分钟 N8N_OAUTH_JWE_JWKS_PER_MINUTE 次请求（默认 60）
Cache headers Cache-Control: public, max-age=3600, must-revalidate
响应格式 JWK Set（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 响应。

相关资源#