外部秘密
提示
Feature availability 功能可用性
外部密钥可用于:
- n8n Cloud: Enterprise
- Self-hosted: Enterprise
n8n 支持以下密钥提供商:1Password(使用 Connect Server)、AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager、HashiCorp Vault 和 Infisical。n8n 不支持 HashiCorp Vault Secrets。
- 从 n8n 2.10.0 开始,您可以为每个密钥提供程序连接多个保管库。旧版本仅支持每个提供商一个保管库。
- 从 n8n 2.13.0 开始,如果启用,项目编辑者可以在其项目中使用外部密钥,项目管理员还可以管理项目保管库。
存储在外部密钥存储中的凭证仅会在凭据字段中解析,不会在其他支持表达式的字段中解析。
您可以使用外部机密存储来管理 n8n 的凭据[^1]。
n8n 将所有凭据加密存储在其数据库中,并默认限制对它们的访问。借助外部机密功能,您可以将敏感凭证信息存储在外部保管库中,并让 n8n 在需要时加载它。这提供了额外的安全层,并允许您在一个中心位置管理跨多个 n8n 环境 使用的凭据。
全球金库
默认情况下,密钥保管库是全局的:整个实例中的用户都可以使用引用该保管库密钥的凭据。
在个人项目中,只有实例所有者和管理员可以在凭据中使用全局保管库中的密钥。
项目金库
实例管理员可以与特定的项目共享保管库。将保管库分配给项目后,只有该项目的凭据才能引用其机密。您可以选择将 Vault 绑定到单个项目或保持全局。
要更改保管库范围:
- 在 n8n 中,转到 Settings 设置 > External Secrets 外部密钥。
- 找到要配置的保管库并选择 Edit 编辑。
- 在 Share 共享 下,选择以下选项之一:
- Global 全局:在整个 n8n 实例中共享此保管库。这允许实例中的凭据引用这些密钥。
- Project 项目:将此保管库限制为特定项目。选择项目后,只有该项目中的凭据可以访问这些密钥。
- Save 保存 配置。
将 n8n 连接到您的秘密存储
提示
Secret values 秘密价值观
n8n 仅支持机密的纯文本值,而不支持 JSON 对象。
- 在 n8n 中,转到 Settings 设置 > External Secrets 外部密钥。
- 点击 Add secrets vault 添加密钥保管库。
- 为您的保管库输入一个唯一名称。该名称将作为在凭据中使用
{{ $secrets.<vault-name>... }}表达式引用此保管库时的第一个段。 - 选择一个受支持的密钥提供商。
- 输入您提供商的凭据。有关详细信息,请参阅下面的提供商特定部分。
- Save 保存 您的配置。
只要保持此存储连接,您就可以在凭据中引用其中的密钥。
1密码
提示
1Password Connect Server required 1 需要密码连接服务器
n8n 与 1Password Connect Server 集成,这是一个用于机器访问 1Password 的自托管 API。这与个人或团队 1Password 帐户不同。您必须部署并运行 Connect Server 才能使用此提供程序。
提供您的 Connect Server URL 和 Access Token 访问令牌。Connect Server URL 是您的服务器可访问的地址(例如 http://localhost:8080)。Access Token 是您为 Connect Server 集成创建的令牌。
n8n 会读取该令牌可访问的所有保管库和项目。每个 1Password 项目都会成为一个密钥,其字段可作为属性访问。使用 {{ $secrets.<vault-name>.<item-title>.<field-label> }} 访问特定字段的值。
AWS Secrets Manager
选择一种身份验证方法:
- IAM User IAM 用户: 提供 IAM 用户的 access key ID 访问密钥 ID、secret access key 秘密访问密钥 和 region 区域。
- Auto Detect 自动检测: n8n 使用 AWS SDK 默认凭据提供程序链,从 n8n 运行所在的环境中自动查找凭据(例如环境变量、共享凭据文件或 EC2/ECS/EKS 实例角色)。如果 n8n 已在具有 AWS 凭据的环境中运行,可以使用此方法,无需管理长期访问密钥。
无论选择哪种方法,底层 IAM 身份都必须拥有 secretsmanager:ListSecrets、secretsmanager:BatchGetSecretValue 和 secretsmanager:GetSecretValue 权限。
警告
Auto Detect 和使用 Auto Detect 时的密钥范围
n8n 不会为该保管库接收任何凭据输入,而是解析运行环境中可用的身份。这意味着同一 n8n 实例上使用 Auto Detect 配置的每个保管库都会共享同一个 IAM 身份和权限集。您无法为不同的 Auto Detect 保管库分配不同的 IAM 范围(例如,将一个保管库限制为某个项目的密钥,将另一个保管库限制为其他项目的密钥)。
如果需要按保管库、项目或团队限制密钥访问,请改用 IAM User IAM 用户:为每个保管库创建单独的 IAM 用户和访问密钥,并为每个用户附加 ARN 范围策略(请参阅下方按 ARN 限制范围的策略示例)。Auto Detect 最适合单个全局保管库,或所有共享该保管库的项目都应使用相同 AWS 访问权限的设置。
要让 n8n 访问您 AWS Secrets Manager 中的所有密钥,您可以将以下策略附加到 IAM 用户:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AccessAllSecrets",
"Effect": "Allow",
"Action": [
"secretsmanager:ListSecrets",
"secretsmanager:BatchGetSecretValue",
"secretsmanager:GetResourcePolicy",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:ListSecretVersionIds"
],
"Resource": "*"
}
]
}
您也可以更严格地控制,让 n8n 仅访问特定的 AWS Secret Manager 密钥。您仍然需要允许 secretsmanager:ListSecrets 和 secretsmanager:BatchGetSecretValue 权限来访问所有资源。这些权限允许 n8n 检索按 ARN 限定范围的密钥,但不提供对密钥值的访问。
接下来,您需要将 secretsmanager:GetSecretValue 权限的范围设置为您希望与 n8n 共享的密钥的特定 Amazon 资源名称(ARN)。确保在每个资源 ARN 中使用正确的区域和账户 ID。您可以在 AWS 控制台的密钥仪表板中找到 ARN 详细信息。
例如,以下 IAM 策略仅允许访问您指定的 AWS 账户和区域中名称以 n8n 开头的密钥:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ListingSecrets",
"Effect": "Allow",
"Action": [
"secretsmanager:ListSecrets",
"secretsmanager:BatchGetSecretValue"
],
"Resource": "*"
},
{
"Sid": "RetrievingSecrets",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": [
"arn:aws:secretsmanager:us-west-2:123456789000:secret:n8n*"
]
}
]
}
有关更多 IAM 权限策略示例,请参阅 AWS 文档。
Azure 密钥保管库
提示
Feature availability 功能可用性
Azure Cloud 设置从 n8n 2.35.0 起可用。早期版本只能连接 Azure Public Cloud。现有配置不受影响:它们会继续使用 Azure Public Cloud。
提供您的 tenant ID 租户 ID、client ID 客户端 ID 和 client secret 客户端密钥。请参阅 Azure 文档以注册 Microsoft Entra ID 应用并创建服务主体。n8n 仅支持密钥的单行值。
选择托管 Key Vault 的 Azure Cloud 环境。该设置会确定保管库 URL 和 Microsoft Entra 授权主机:
| Azure Cloud | 保管库 URL 后缀 | Entra 授权主机 |
|---|---|---|
| Azure Public Cloud(默认) | vault.azure.net |
https://login.microsoftonline.com |
| Azure US Government | vault.usgovcloudapi.net |
https://login.microsoftonline.us |
| Azure China | vault.azure.cn |
https://login.partner.microsoftonline.cn |
| Custom | 提供完整 URL | 提供主机 |
对于 Azure Public Cloud、Azure US Government 和 Azure China,请提供 Vault Name 保管库名称。n8n 会根据名称和所选云环境的后缀构建保管库 URL。
对于 Custom,请提供完整的 Vault URL(例如 https://my-vault.vault.usgovcloudapi.net),而不是保管库名称。您还可以设置可选的 Authority Host 授权主机(例如 https://login.microsoftonline.us),以便针对其他 Microsoft Entra 授权主机进行身份验证。将 Authority Host 留空以使用默认值(https://login.microsoftonline.com)。Custom 适用于 Azure Stack 或代理环境等设置。
GCP 机密管理器
提供一个具有至少以下角色的服务账户的 Service Account Key 服务账户密钥(JSON):Secret Manager Secret Accessor 和 Secret Manager Secret Viewer。有关更多信息,请参阅 Google 的服务账户文档。
HashiCorp Vault
提供您保管库实例的 Vault URL,并选择您的 Authentication Method 认证方法。输入您的认证详细信息。可选提供命名空间。
- 有关您的认证方法,请参阅 HashiCorp 文档:
- 如果您使用保管库命名空间,可以输入 n8n 应连接到的命名空间。有关 HashiCorp Vault 命名空间的更多信息,请参阅 Vault Enterprise 命名空间。
手动 KV 安装配置
默认情况下,n8n 通过读取 sys/mounts 自动发现 KV 密钥引擎。如果您的 Vault 令牌没有访问 sys/mounts 的权限,您可以手动指定 KV 引擎挂载路径和版本:
- KV Mount Path KV 挂载路径:您的 KV 密钥引擎的挂载路径(例如
secret/)。设置后,n8n 会跳过sys/mounts自动发现并直接使用此路径。留空则使用自动发现。 - KV Version KV 版本:KV 引擎版本(
v1或v2)。默认为v2。仅在指定 KV Mount Path KV 挂载路径 时适用。
您的 Vault 令牌仍然需要对 KV 路径本身的读取和列表访问权限。以下示例展示了在 secret/ 挂载的 KV v2 的最小 Vault 策略:
# Read and list secrets at the "secret/" KV v2 mount <a href="#read-and-list-secrets-at-the-secret-kv-v2-mount" id="read-and-list-secrets-at-the-secret-kv-v2-mount"></a>
path "secret/data/*" {
capabilities = ["read"]
}
path "secret/metadata/*" {
capabilities = ["read", "list"]
}
对于 KV v1,您只需要一个策略路径:
# Read and list secrets at the "kv/" KV v1 mount <a href="#read-and-list-secrets-at-the-kv-kv-v1-mount" id="read-and-list-secrets-at-the-kv-kv-v1-mount"></a>
path "kv/*" {
capabilities = ["read", "list"]
}
Infisical
提示
Feature availability 功能可用性
Infisical 密钥管理支持从 n8n 2.26.0 起可用。
要连接 Infisical,请提供以下信息:
- Site URL 站点 URL:Infisical 实例的基础 URL。默认为
https://app.infisical.com。仅在你自托管 Infisical 时需要更改。 - Project ID 项目 ID:要读取密钥的 Infisical 项目 ID。
- Environment 环境:环境 slug,例如
dev、staging或prod。 - Secret Path 密钥路径:项目内要读取密钥的路径。默认为
/。 - Authentication Method 身份验证方法:选择 Universal Auth(推荐)或 Access Token。
n8n 建议使用通用身份验证,它使用 Infisical 机器身份。令牌在过期前会自动刷新。
在 Infisical 中,授予机器身份角色以读取目标项目中的机密。内置 Viewer 角色有效,您也可以创建一个自定义角色,向 secrets 授予目标环境和秘密路径上的 Read Value 读取值 和 Describe Secret 描述秘密 权限。请参阅 Infisical 的 项目角色文档。
Universal Auth
提供:
- Client ID 客户ID:机器身份的客户端ID。
- Client Secret 客户秘密:机器身份的客户端密钥。
在 Infisical 中,创建一个机器身份,将其附加到具有上述角色的项目中,然后复制客户端 ID 和客户端密钥。请参阅 Infisical 的 通用授权文档。
Access Token
提供:
- Access Token 访问令牌:机器身份内部发行的令牌。
在 Infisical 中,创建一个机器身份,将其附加到具有上述角色的项目,然后单击 Add Auth Method 并选择 Token Auth。请参阅 Infisical 的 令牌身份验证文档。
在 n8n 凭证中使用机密
要在 n8n 凭据中使用存储中的密钥:
- 创建一个新凭据,或打开一个现有凭据。
- 在要使用秘密的字段上:
- 将鼠标悬停在字段上。
- 选择 Expression 表达。
- 在要使用机密的字段中,输入引用机密名称的表达式[^2]:
js {{ $secrets.<vault-name>.<secret-name> }}<vault-name>是您添加存储时输入的名称。将<secret-name>替换为它在您的保管库中显示的名称。
在 n8n 环境中使用外部机密
n8n 的源代码控制和环境 功能允许您创建由 Git 支持的不同 n8n 环境。该功能不支持在不同实例中使用不同的凭据。您可以使用外部机密保管库,通过将每个 n8n 实例连接到不同的保管库或项目环境来为不同环境提供不同的凭据。
例如,您有两个 n8n 实例,一个用于开发,一个用于生产。在您的密钥提供商中,创建一个包含开发和生产两个环境的项目。为每个环境分别生成 token。使用开发环境的 token 连接开发实例,使用生产环境的 token 连接生产实例。
在项目中使用外部机密
您可以将保管库共享给项目,这样只有该项目中的凭据可以引用其中的密钥。设置步骤请参阅项目保管库。项目范围的保管库从 n8n 2.11.0 起可用。
项目角色的访问权限
提示
Feature availability 功能可用性
向项目编辑者和项目管理员授予外部密钥访问权限的功能从 n8n 2.13.0 起可用。在 n8n 2.13.0 之前,在 RBAC 项目 中使用外部密钥需要 实例所有者或实例管理员 作为项目成员。
从 n8n 2.13.0 开始,实例所有者和管理员可以授予 项目编辑者 和 项目管理员 外部密钥的访问权限。
要启用此功能:
- 转到 Settings 设置 > External Secrets 外部密钥。
- 开启 Enable external secrets for project roles 为项目角色启用外部密钥。
启用后,项目编辑者可以:
- 查看与项目共享的可用外部密钥保管库(在 Project 项目 > Settings 设置 中)。
- 在凭据中使用项目保管库中的密钥。
项目管理员拥有相同的访问权限,此外还可以:
- 为项目创建新的保管库(在 Project 项目 > Settings 设置 中)。
- 更新和删除分配给项目的保管库。
提示
Global vault access 全球金库访问
在 Settings 设置 > External Secrets 对外秘密 中创建的全局保管库在 Project 项目 > Settings 设置 中可见,但对于项目角色是只读的。只有实例管理员可以修改或删除全局保管库。
自定义角色
为了进行更细粒度的访问控制,实例所有者和管理员可以创建自定义项目角色。转至 Settings 设置 > Roles 角色 > Project roles 项目角色 > Create role 创建角色。在权限列表中,配置:
- Secrets vaults 密钥保管库:控制保管库管理(查看、创建、编辑、删除和同步保管库)。
- Secrets 密钥:控制该角色是否可以在凭据表达式中使用密钥。
两种权限都是独立的。例如,角色可能只需要 Secrets 秘密 权限即可在凭证中使用机密,而无需管理保管库。有关可用范围的完整列表,请参阅 秘密保管库范围。
故障排除
秘密在生产中无法解析
提示
Feature availability 功能可用性
项目编辑者或管理员在启用密钥访问 后,可从 n8n 2.13.0 起在自己的凭据中使用外部密钥。以下限制仅适用于旧版本或选择加入开关关闭时。
在 n8n 2.13.0 之前的版本中(或当 Enable external secrets for project roles 为项目角色启用外部密钥 关闭时),只有实例所有者和管理员可以在运行时解析密钥。如果所有者或管理员使用密钥表达式更新了其他用户的凭据,它可能在预览中正常工作但在生产环境中失败。
在这种情况下,仅在实例所有者或管理员拥有的凭证中使用外部机密。
有关保护和共享凭据的其他方式,请参阅管理凭据。
[^1]:在 n8n 中,凭据存储身份验证信息以连接特定的应用程序和服务。使用身份验证信息(用户名和密码、API 密钥、OAuth 密钥等)创建凭据后,您可以使用关联的应用程序节点与服务交互。 [^2]:在 n8n 中,表达式允许您通过执行 JavaScript 代码动态填充节点参数。您可以使用 n8n 表达式语法,使用来自先前节点、其他工作流程或 n8n 环境的数据来定义值,而不是提供静态值。
如果使用 terraform-aws-n8n 模块在 AWS 上部署 n8n,请参阅在 AWS 上配置 Enterprise 功能。