Skip to content

外部密钥管理#

功能可用性

  • 外部密钥管理功能适用于企业自托管版和企业云版计划。
  • 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 用户： 

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
      {
	"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 Secrets Manager 密钥。您仍然需要允许 secretsmanager:ListSecrets 和 secretsmanager:BatchGetSecretValue 权限来访问所有资源。这些权限允许 n8n 检索 ARN 范围内的密钥，但不提供对密钥值的访问权限。

      接下来，您需要将 secretsmanager:GetSecretValue 权限的范围设置为要与 n8n 共享的特定 Amazon 资源名称 (ARN)。确保在每个资源 ARN 中使用正确的区域和账户 ID。您可以在 AWS 仪表板中找到密钥的 ARN 详细信息。

      例如，以下 IAM 策略仅允许访问指定 AWS 账户和区域中名称以 n8n 开头的密钥：

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
      {
	"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 实例的 Vault URL，并选择您的 认证方法。输入您的认证详细信息。可选提供命名空间。

    • Infisical：提供 服务令牌。有关获取令牌的信息，请参考 Infisical 的服务令牌文档。如果您自托管 Infisical，请输入 站点 URL。

      Infisical 环境

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

      Infisical 文件夹

      n8n 不支持 Infisical 文件夹。

    • Google Cloud Platform：提供至少具有以下角色的服务账户的 服务账户密钥（JSON）：Secret Manager Secret Accessor 和 Secret Manager Secret Viewer。更多信息请参考 Google 的服务账户文档。

  4. 保存您的配置。

  5. 使用 禁用/启用 切换开关启用提供商。

在 n8n 凭据中使用密钥#

要在 n8n 凭据中使用来自密钥存储的密钥：

  1. 创建新凭据，或打开现有凭据。
  2. 在需要使用密钥的字段上：
    1. 将鼠标悬停在字段上。
    2. 选择 Expression（表达式）。
  3. 在需要使用密钥的字段中，输入引用密钥名称的表达式： 
    1
    {{ $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 的连接问题。如果您的 Infisical 连接停止工作，请检查是否有最近的版本变更。如果有，请将问题报告至 help@n8n.io。

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

由于实例所有者和管理员拥有的权限，所有者和管理员可以使用密钥表达式更新其他用户拥有的凭据。对于实例所有者或管理员来说，这在预览中看似有效，但当工作流在生产环境中运行时，密钥将无法解析。

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