跳到主要内容

外部秘钥

功能可用性

  • 外部秘钥功能适用于 Enterprise 自托管和 Enterprise Cloud 方案。
  • n8n 支持以下秘钥提供商：AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager 和 HashiCorp Vault。
  • 从 n8n 2.10.0 版本起，你可以为每个秘钥提供商连接多个保险库（Vault）。旧版本每个提供商只支持一个保险库。
  • n8n 不支持 HashiCorp Vault Secrets。

Infisical 已弃用

Infisical 已被弃用。从 2.10.0 版本起，你将无法连接新的 Infisical 保险库，但现有的连接暂时仍会保留。

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

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

连接 n8n 到你的秘钥存储​

秘钥值

n8n 仅支持纯文本格式的秘钥值，不支持 JSON 对象格式。

  1. 在 n8n 中，前往 设置 > 外部秘钥。

  2. 点击 添加秘钥保险库。

  3. 为你的保险库输入一个唯一的名称。这将是在凭据的 } 表达式中引用该保险库时的第一段。

  4. 选择一个受支持的秘钥提供商。

  5. 输入你的提供商凭据：

    • 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 用户。你也可以更改限制范围，只授予 n8n 访问特定 AWS Secrets Manager 秘钥的权限。但你仍需要允许 secretsmanager:ListSecrets 和 secretsmanager:BatchGetSecretValue 权限以访问所有资源。这些权限允许 n8n 检索 ARN 范围内的秘钥，但不提供对秘钥值的访问权限。

接下来，你需要为 secretsmanager:GetSecretValue 权限设置范围，将其限定到你希望与 n8n 共享的特定 Amazon 资源名称（ARN）。请确保在每个资源 ARN 中使用正确的区域和账户 ID。你可以在 AWS 控制台的秘钥详情页面找到 ARN 信息。

更多 IAM 权限策略示例，请参阅 AWS 文档。

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

   * 请参阅 HashiCorp 文档了解你使用的身份验证方法：[Token 身份验证方法](<https://developer.hashicorp.com/vault/docs/auth/token>)、[AppRole 身份验证方法](<https://developer.hashicorp.com/vault/docs/auth/approle>)、[Userpass 身份验证方法](<https://developer.hashicorp.com/vault/docs/auth/userpass>)
   * 如果你使用 Vault 命名空间，可以输入 n8n 应连接的命名空间。有关 HashiCorp Vault 命名空间的更多信息，请参阅 [Vault Enterprise 命名空间](<https://developer.hashicorp.com/vault/docs/enterprise/namespaces>)。
 * **Google Cloud Platform**：为至少具有 `Secret Manager Secret Accessor` 和 `Secret Manager Secret Viewer` 角色的服务账号提供 **服务账号密钥**（JSON 格式）。有关服务账号的更多信息，请参阅 Google 的[服务账号文档](<https://cloud.google.com/iam/docs/service-account-overview>)。

6. 保存 你的配置。

  1. 只要该存储处于连接状态，你就可以在凭据中引用其秘钥。

共享保险库​

默认情况下，秘钥保险库是全局的：实例中的所有用户都可以使用引用该保险库秘钥的凭据。

实例管理员可以将保险库限制到特定的项目。将保险库分配给项目后，只有该项目的凭据才能引用其秘钥。你可以选择将保险库与单个项目绑定，或保持全局状态。

设置共享范围：

  1. 在 n8n 中，前往 设置 > 外部秘钥。
  2. 找到你要配置的保险库，选择 编辑。
  3. 在 共享 下，选择以下选项之一：
    • 全局（Global）：在整个 n8n 实例中共享此保险库，允许实例中的所有凭据引用这些秘钥。
    • 项目（Project）：将此保险库限制到特定项目，选择一个项目后，只有该项目的凭据才能访问这些秘钥。
  4. 保存 你的配置。

在 n8n 凭据中使用秘钥​

要在 n8n 凭据中使用存储中的秘钥：

  1. 创建一个新凭据，或打开一个现有凭据。
  2. 在你想使用秘钥的字段上：
    1. 将鼠标悬停在该字段上。
    2. 选择 表达式（Expression）。
  3. 在该字段中，输入引用秘钥名称的表达式：
{{ $secrets.<保险库名称>.<秘钥名称> }}

<保险库名称> 是你添加存储时输入的名称。将 <秘钥名称> 替换为你保险库中显示的秘钥名称。

在 n8n 环境中使用外部秘钥​

n8n 的源代码控制与环境功能允许你创建不同的 n8n 环境，由 Git 提供支持。该功能不支持在不同实例中使用不同的凭据。你可以通过外部秘钥保险库，将每个 n8n 实例连接到不同的保险库或项目环境，从而为不同的环境提供不同的凭据。例如，你有两个 n8n 实例，一个用于开发，一个用于生产。在你的秘钥提供商中，创建一个包含开发和生产两个环境的项目。为每个环境生成一个令牌。使用开发环境的令牌连接你的开发 n8n 实例，使用生产环境的令牌连接你的生产 n8n 实例。

在项目中使用外部秘钥​

要在 RBAC 项目中使用外部秘钥，你必须将实例所有者或实例管理员作为项目成员。

你可以使用共享保险库功能，将保险库限制到特定项目。分配给项目的保险库只能在该项目的凭据中使用。

故障排除​

只在实例所有者或管理员拥有的凭据上使用外部秘钥​

由于实例所有者和管理员拥有的权限，所有者和管理员可能会使用秘钥表达式更新另一个用户拥有的凭据。对于实例所有者或管理员来说，这在预览时看起来可以正常工作，但在工作流于生产环境运行时，秘钥将无法解析。

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