跳到主要内容

外部密钥#

功能可用性

  • 外部密钥功能适用于企业自托管和企业云方案
  • n8n 支持 AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager、Infisical 和 HashiCorp Vault
  • n8n 不支持 HashiCorp Vault Secrets

您可以使用外部密钥存储来管理 n8n 的凭据。

n8n 默认将所有凭据加密存储在其数据库中，并限制对其的访问。通过外部密钥功能，您可以将敏感凭据信息存储在外部保险库中，并让 n8n 在需要时加载。这提供了额外的安全层，使您能够在一个中心位置管理跨多个n8n 环境使用的凭据。

将 n8n 连接到密钥存储#​

密钥命名规范

密钥名称不能包含空格、连字符或其他特殊字符。n8n 支持包含字母数字字符（a-z、A-Z 和 0-9）和下划线的密钥名称。n8n 目前仅支持纯文本值的密钥，不支持 JSON 对象或键值对。

  1. 在 n8n 中，进入 设置 > 外部密钥

  2. 为您的存储提供商选择 设置

  3. 输入您的提供商凭据：

    • Azure Key Vault：提供您的保管库名称、租户 ID、客户端 ID 和客户端密钥。请参阅 Azure 文档以注册 Microsoft Entra ID 应用并创建服务主体。n8n 仅支持单行值的密钥

    • AWS Secrets Manager：提供您的访问密钥 ID、秘密访问密钥和区域。IAM 用户必须具有 secretsmanager:ListSecrets、secretsmanager:BatchGetSecretValue 和 secretsmanager:GetSecretValue 权限

      要授予 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密钥管理器密钥。仍需保留secretsmanager:ListSecrets和secretsmanager:BatchGetSecretValue权限以访问所有资源。这些权限允许n8n检索ARN限定范围的密钥，但不会提供对密钥值的访问权限。

接下来，需要将secretsmanager:GetSecretValue权限的作用域设置为要与n8n共享的特定亚马逊资源名称（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官方文档。

  • HashiCorp Vault：提供您的保险库实例的Vault URL，并选择身份验证方法。输入身份验证信息，可选择性地提供命名空间。

  • Infisical：提供服务令牌。获取令牌的相关说明请参阅Infisical的服务令牌文档。若自托管Infisical，请输入站点URL。

    Infisical环境

    创建令牌时请确保选择正确的Infisical环境。n8n将从此环境加载密钥，且无法访问其他Infisical环境中的密钥。n8n仅支持访问单一环境的服务令牌。

    Infisical文件夹

    n8n不支持Infisical文件夹功能。

  • Google Cloud Platform：提供至少具有Secret Manager Secret Accessor和Secret Manager Secret Viewer角色的服务账号对应的服务账号密钥（JSON格式）。更多信息请参阅Google的服务账号文档。

  1. 保存配置。
  2. 通过禁用/启用切换开关启用该提供商。

在n8n凭据中使用密钥#​

要在n8n凭据中使用密钥库中的密钥：

  1. 创建新凭据或打开现有凭据
  2. 在需要使用密钥的字段上：
    1. 将鼠标悬停于该字段
    2. 选择表达式
  3. 在需要使用密钥的字段中输入引用密钥名称的表达式：

{{ $secrets.<vault-name>.<secret-name> }}

<vault-name> 可设置为 vault（对应 HashiCorp）、infisical 或 awsSecretsManager。请将 <secret-name> 替换为您的密码库中显示的名称。

在 n8n 环境中使用外部密钥#​

n8n 的源代码控制与环境功能支持创建基于 Git 的不同 n8n 环境。该功能不支持在不同实例中使用不同的凭据。您可以通过将每个 n8n 实例连接到不同的密码库或项目环境，使用外部密钥库为不同环境提供不同的凭据。

例如：您有两个 n8n 实例，分别用于开发和生产环境，并使用 Infisical 作为密钥库。在 Infisical 中创建包含开发和生产环境的项目，为每个 Infisical 环境生成独立令牌。使用开发环境令牌连接开发版 n8n 实例，使用生产环境令牌连接生产版 n8n 实例。

在项目中使用外部密钥#​

若要在基于角色的访问控制（RBAC）项目中使用外部密钥，项目成员中必须包含实例所有者或实例管理员。

故障排除#​

Infisical 版本变更#​

Infisical 版本升级可能导致与 n8n 的连接异常。若连接失效，请检查近期是否发生版本变更。如存在此情况，请将问题反馈至 [email protected]。

仅对实例所有者或管理员持有的凭据设置外部密钥#​

由于实例所有者和管理员具备特殊权限，他们可能使用密钥表达式更新其他用户持有的凭据。此操作在预览模式下对所有者或管理员显示正常，但在生产环境运行工作流时密钥将无法解析。

请仅对实例管理员或所有者持有的凭据使用外部密钥，这可确保其在生产环境中正确解析。