外部密钥管理#

功能可用性

外部密钥（External secrets）在 Enterprise Self-hosted 和 Enterprise Cloud 计划中可用。
n8n 支持 AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager、Infisical 以及 HashiCorp Vault。
n8n 不支持 HashiCorp Vault Secrets。

你可以使用外部密钥存储来管理 n8n 的凭据。 n8n 默认会将其所有凭据以加密形式存储在其数据库中，并限制对这些凭据的访问。通过外部密钥功能，你可以将敏感的凭据信息存储在外部密钥库（vault）中，在需要时由 n8n 动态加载。这提供了额外的安全层，并允许你在集中式位置统一管理多个 n8n 环境所使用的凭据。

将 n8n 连接到你的密钥存储#

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

在 n8n 中，进入 设置（Settings） > 外部密钥（External Secrets）。
为你的密钥存储提供商选择 设置（Set Up）。
输入对应提供商的凭据：
- Azure Key Vault：提供你的 vault 名称、租户 ID（tenant ID）、客户端 ID（client ID） 和 客户端密钥（client secret）。请参考 Azure 文档了解如何注册 Microsoft Entra ID 应用并创建服务主体。n8n 当前仅支持单行文本格式的密钥值。
- AWS Secrets Manager：提供你的 访问密钥 ID（access key ID）、秘密访问密钥（secret access key） 和 区域（region）。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 Secrets Manager 密钥的权限。但你仍然需要允许 `secretsmanager:ListSecrets` 和 `secretsmanager:BatchGetSecretValue` 权限以访问所有资源。这些权限允许 n8n 检索基于 ARN 范围的密钥，但不会提供对密钥值的实际访问权限。

接下来，你需要将 `secretsmanager:GetSecretValue` 权限的作用范围（scope）限制为希望与 n8n 共享的具体 Amazon 资源名称（ARN）。请确保在每个资源 ARN 中使用正确的区域（region）和账户 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**，并选择你的 **认证方式（Authentication Method）**。输入相应的认证信息。可选地，提供命名空间（namespace）。
       * 请参考 HashiCorp 官方文档了解不同认证方式的配置方法：
         * Token 认证方式
         * AppRole 认证方式
         * Userpass 认证方式
       * 如果你使用了 Vault 的命名空间（namespace），可以在此指定 n8n 应连接的命名空间。更多信息请参阅 Vault Enterprise 命名空间文档。
     * Infisical：提供一个 **Service Token（服务令牌）**。关于如何获取该令牌，请参考 Infisical 的 Service token 文档。如果你是自托管 Infisical，请填写 **Site URL**。
Infisical 环境
创建令牌时，请确保选择了正确的 Infisical 环境。n8n 将从该环境中加载密钥，并无法访问其他环境中的密钥。n8n 仅支持具有单个环境访问权限的服务令牌。
Infisical 文件夹
n8n 不支持 Infisical 文件夹（folders） 功能。
     * Google Cloud Platform：提供一个具有至少以下角色的 **服务账号密钥（Service Account Key，JSON 格式）**：`Secret Manager Secret Accessor` 和 `Secret Manager Secret Viewer`。更多信息请参考 Google 的 服务账号文档。
  4. **保存**你的配置。
  5. 使用 **禁用 / 启用** 开关来启用该密钥提供者。

## 在 n8n 凭据中使用密钥 #
要在 n8n 凭据中使用来自密钥存储的密钥，请执行以下操作：
  1. 创建一个新的凭据，或打开一个已有的凭据。
  2. 在你想使用密钥的字段上：
    1. 将鼠标悬停在该字段上。
    2. 选择 **Expression（表达式）**。
  3. 在目标字段中输入引用密钥名称的 表达式（expression），格式如下：

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

---|--- 其中 <vault-name> 可以是 vault（HashiCorp）、infisical 或 awsSecretsManager。将 <secret-name> 替换为你的密钥管理工具中实际的密钥名称。


## 在 n8n 环境中使用外部密钥#
n8n 的 源代码控制与环境管理 功能允许你通过 Git 创建不同的 n8n 环境。该功能本身不支持在不同实例中使用不同的凭据（credentials）。你可以通过将每个 n8n 实例连接到不同的密钥管理库（vault）或项目环境，利用外部密钥存储来为不同环境提供各自的凭据。

例如，你有两个 n8n 实例：一个用于开发，另一个用于生产。你使用 Infisical 作为密钥管理工具。在 Infisical 中创建一个包含两个环境（development 和 production）的项目，并分别为这两个环境生成令牌（token）。使用开发环境的令牌连接你的开发版 n8n 实例，使用生产环境的令牌连接生产版 n8n 实例。

## 在项目中使用外部密钥#
要在 RBAC 项目 中使用外部密钥，项目成员中必须包含 实例所有者（instance owner）或实例管理员（instance admin）。

## 故障排查#

### Infisical 版本变更#
Infisical 的版本升级可能导致无法连接到 n8n。如果你的 Infisical 连接突然失效，请检查是否最近发生了版本更新。如果确认有版本变化，请将问题反馈至 help@n8n.io 以获得支持。

### 仅对由实例所有者或管理员拥有的凭据设置外部密钥#
由于实例所有者和管理员拥有较高权限，他们可以使用密钥表达式（secrets expression）修改其他用户所拥有的凭据。这在预览模式下看似正常工作，但在生产环境中运行工作流时，密钥可能无法正确解析。

因此，**应仅对由实例管理员或所有者拥有的凭据使用外部密钥**，以确保其在生产环境中能正确解析。

聊天查看文档
此页面 !Thumbs up有帮助  !Thumbs down无帮助
感谢您的反馈！
提交
 上一篇  教程：使用源代码控制创建环境   下一篇  日志流 
由  Material for MkDocs Insiders  驱动

外部密钥管理#

将 n8n 连接到你的密钥存储#

On this page