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 会:
- 在启动时生成 RSA 密钥对,并使用实例加密密钥加密私钥后存储到数据库。
- 在实例级 JWKS 端点发布匹配的公钥,供 IdP 获取。
- 在 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 令牌解密
-
在所有 n8n 实例(包括主实例和 worker)上设置以下环境变量:
sh N8N_ENV_FEAT_OAUTH2_JWE=true -
重启所有实例。启动时,n8n 会生成 RSA 密钥对,并在 JWKS 端点发布公钥。
-
要确认功能已启用,请请求 JWKS 端点,并检查它是否返回一个带有
"alg": "RSA-OAEP-256"的 key:sh curl https://<your-n8n-host>/rest/.well-known/jwks.json
配置您的身份提供商
在 IdP 的 OAuth 2.0 客户端或应用配置中:
- 为 n8n 连接的客户端启用加密 token。
- 将客户端的 JWKS URI 设置为你的实例 JWKS 端点。n8n 会在凭据中显示这个 URL,因此你创建凭据后可以直接从那里复制(见下一节)。
- 选择
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 中配置凭证
- 创建或编辑 OAuth 2.0 API 凭证。
- 打开 Encrypted Tokens (JWE) 加密令牌 (JWE)。
- 复制 JWKS URI 字段中的值并将其粘贴到 IdP 上的 JWKS URI 设置中(如果您尚未执行此操作)。
- 保存凭据并连接。 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 响应。
相关资源
- 安全性:审计、加固和限制自托管实例。
- HTTP Request 凭据:使用 OAuth2:设置通用 OAuth 2.0 凭据。
- 部署环境变量:查看
N8N_ENV_FEAT_OAUTH2_JWE和N8N_OAUTH_JWE_JWKS_PER_MINUTE的参考信息。 - 轮换加密密钥:轮换用于保护静态 JWE 私钥的数据加密密钥。
- JSON Web Encryption (RFC 7516):JWE 规范。