n8n 中文文档

AWS 凭证

n8n 提供两种 AWS 凭据类型:

  • AWS (IAM):使用访问密钥(Access Key ID 和 Secret Access Key)进行身份验证。
  • AWS (Assume Role):通过 AWS STS 担任 IAM 角色进行身份验证。n8n 用于调用 AssumeRole 的凭据可以手动输入,也可以从 n8n 运行环境中自动读取。

如果你在 AWS 基础设施(EKS、ECS 或 EC2)上自行托管 n8n,并希望避免在 n8n 中存储静态密钥,请参阅使用 AWS 系统凭据。

AWS (IAM) 凭证

您可以使用这些凭据来验证以下节点:

支持的身份验证方法

  • API访问密钥

相关资源

请参考 AWS 的身份和访问管理文档 了解有关该服务的更多信息。

使用 API 访问密钥

要配置此凭据,您需要一个 AWS 账户和:

  • 您的 AWS Region 区域
  • Access Key ID 访问密钥 ID:创建访问密钥时生成。
  • Secret Access Key 秘密访问密钥:创建访问密钥时生成。

要创建访问密钥并设置凭据:

  1. 在您的 n8n 凭据中,选择您的 AWS Region 区域。
  2. 登录 IAM 控制台{:target=_blank .external-link}。
  3. 在右上角的导航栏中,选择您的用户名,然后选择 Security credentials。
  4. 在 Access keys 部分,选择 Create access key。
  5. 在 Access key best practices & alternatives 页面上,选择您的用例。如果它没有提示您创建访问密钥,请选择 Other。
  6. 选择 Next。
  7. 为访问密钥设置一个 description 标签值以便更容易识别,例如 n8n integration。
  8. 选择 Create access key。
  9. 显示 Access Key ID 和 Secret Access Key 并将它们输入到 n8n 中。
  10. 要使用 Temporary security credential 临时安全凭据,请开启该选项并添加 Session token 会话令牌。请参考 AWS 临时安全凭据文档{:target=_blank .external-link} 了解更多关于使用临时安全凭据的信息。
  11. 如果您使用 Amazon Virtual Private Cloud (VPC){:target=_blank .external-link} 来托管 n8n,您可以在您的 VPC 和一些应用之间建立连接。使用 Custom Endpoints 自定义端点 为此连接输入相关的自定义端点。此设置适用于以下应用:

    • Rekognition
    • Lambda
    • SNS
    • SES
    • SQS
    • S3
    • SSM
    • Bedrock

    Bedrock 有两个 endpoint 字段:Bedrock Endpoint 用于列出可用模型,Bedrock Runtime Endpoint 供 AWS Bedrock Chat Model 和 Embeddings AWS Bedrock 节点执行推理使用。如果你通过不带 private DNS 的 VPC interface endpoint (PrivateLink){:target=_blank .external-link} 路由 Bedrock,请同时设置这两个字段。

您还可以通过 AWS CLI 和 AWS API 生成访问密钥。请参考 AWS 管理访问密钥文档 了解使用这些方法生成访问密钥的说明。

AWS(承担角色)凭证

您可以使用这些凭据通过 IAM 角色担任来验证以下节点,并增强安全性:

支持的身份验证方法

  • Role Assumption 角色担任

相关资源

请参考 AWS 的 IAM 角色文档 和 STS AssumeRole 文档 了解有关角色担任的更多信息。

了解 AWS 角色假设

AWS 角色担任允许您通过临时担任 IAM 角色来安全地访问 AWS 资源,而不是使用长期访问密钥。这遵循 AWS 安全最佳实践并实现:

  • Cross-account access 跨账户访问: 访问不同 AWS 账户中的资源
  • Enhanced security 增强安全性: 使用自动过期的临时凭据
  • Principle of least privilege 最小权限原则: 仅授予特定任务所需的权限
  • Audit trail 审计跟踪: 更好地跟踪谁访问了哪些资源

n8n 使用官方 AWS SDK 发起 STS AssumeRole 调用。它会在为节点请求签名时获取新的临时凭据,因此你无需管理其过期时间。这不同于 AWS (IAM) 凭据中的 Temporary security credential 临时安全凭据选项;该选项要求你输入 n8n 无法续期的静态 session token:token 过期后,必须输入新的 token。

设置 AWS 代入角色凭证

要配置此凭据,您需要:

所需参数

  • Region 区域: 调用 STS 服务以担任角色的 AWS 区域。n8n 会调用该区域的 STS endpoint。这包括 AWS 中国区域(cn-*)和 AWS GovCloud(us-gov-*)分区(从 n8n 2.29.0 开始可用)。
  • Role ARN 角色 ARN: 您要担任的 IAM 角色的 Amazon Resource Name (ARN)。其格式为 arn:aws:iam::123456789012:role/MyRole。此角色必须具有允许您的凭据担任它的信任策略。
  • External ID 外部 ID: 角色信任策略所需的唯一标识符,用于防止"混淆代理"问题。这应该是您生成并在角色信任策略和此凭据中都配置的密钥值。将此值视为敏感信息。不要与您不信任的其他 n8n 用户共享。
  • Role Session Name 角色会话名称: 担任角色会话的名称(用于审计)。默认值是 n8n-session。此值出现在 AWS CloudTrail 日志中,因此您可以识别会话。

STS 凭证(选择一种方法)

您有两个选项来提供进行 STS AssumeRole 调用的凭据:

选项 1:使用系统凭据(建议用于服务器部署)

如果 n8n 服务器的运行环境已有 AWS 身份,请开启 Use System Credentials 使用系统凭据。n8n 随后会自动发现用于 AssumeRole 调用的凭据,无需在 n8n 中存储静态密钥。n8n 会按以下顺序尝试这些来源,并使用第一个返回凭据的来源:

  1. 环境变量(AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY,以及可选的 AWS_SESSION_TOKEN)
  2. EKS IAM Roles for Service Accounts (IRSA)
  3. EKS Pod Identity
  4. ECS 或 Fargate task role
  5. EC2 instance profile

此选项要求 n8n 管理员将环境变量 N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED 设置为 true,以启用系统凭据访问。有关设置详情和安全注意事项,请参阅使用 AWS 系统凭据。

选项 2:手动 STS 凭证

如果系统凭据不可用,请手动提供这些:

  • STS Access Key ID STS 访问密钥 ID: 具有担任目标角色权限的 IAM 用户或角色的访问密钥 ID。
  • STS Secret Access Key STS 秘密访问密钥: 与 STS 访问密钥 ID 对应的秘密访问密钥。
  • STS Session Token STS 会话令牌(可选):如果使用临时凭据进行 STS 调用,则为会话令牌。

可选参数

  • Custom Endpoints 自定义端点: 如果使用 Amazon VPC,您可以为 AWS 服务指定自定义端点:

    • Rekognition Endpoint Rekognition 端点
    • Lambda Endpoint Lambda 端点
    • SNS Endpoint SNS 端点
    • SES Endpoint SES 端点
    • SQS Endpoint SQS 端点
    • S3 Endpoint S3 端点
    • SSM Endpoint SSM 端点
    • Bedrock Endpoint Bedrock 端点(用于列出可用模型)
    • Bedrock Runtime Endpoint Bedrock Runtime 端点(用于 Bedrock 推理,例如通过 VPC interface endpoint (PrivateLink){:target=_blank .external-link})

设置步骤

  1. 在目标 AWS 账户中创建 IAM 角色。以下 trust policy 适用于 Option 2: Manual STS Credentials。如果使用 Option 1: Use system credentials,Principal 应为 n8n 自身运行时使用的角色。请参阅系统凭据的 trust policy。

```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::SOURCE-ACCOUNT:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "your-unique-external-id" } } } ] }

``` 2. 在 n8n 中配置凭据。 * 选择您的 AWS Region 区域 * 输入您创建的角色的 Role ARN 角色 ARN * 设置唯一的 External ID 外部 ID(与信任策略中的相同) * 选择您的 STS credentials method STS 凭据方法 * 输入 Role Session Name 角色会话名称(或使用默认值) 3. 使用内置测试功能测试凭据以验证角色担任是否有效。

安全最佳实践

  • 对每个凭证使用唯一的外部 ID,以防止未经授权的访问。
  • 轮换用于角色假设的 STS 凭据。
  • 将最小权限原则应用于假定凭据和目标角色。
  • 在共享实例上,请保持系统凭据访问处于禁用状态。请参阅使用 AWS 系统凭据。

使用 AWS 系统凭据(联合身份验证)

本节面向自行托管 n8n 实例的管理员。

提示

系统凭据访问仅适用于自行托管的 n8n,不适用于 n8n Cloud。

当 n8n 在 AWS 基础设施上运行时,基础设施本身可以提供 AWS 身份。无需创建、存储或轮换访问密钥。这是 EKS、ECS 和 EC2 上工作负载的标准身份验证方式,安全团队通常也会要求这样做(“零静态密钥”)。

n8n 使用官方 AWS SDK credential providers 读取这些系统凭据。开启 Use System Credentials 使用系统凭据后,n8n 会将其作为 AWS (Assume Role) 凭据的起始凭据。所有接受 AWS (Assume Role) 凭据的节点都支持这种方式,包括 AWS Bedrock AI 节点。

提示

系统凭据始终是担任角色的起点,绝不会作为 n8n 直接调用 AWS 时使用的身份。你仍必须输入 Role ARN 角色 ARN,且该角色必须信任 n8n 运行时使用的身份。

如果 n8n 当前运行所使用的角色已经具备工作流所需权限,请输入同一角色的 ARN,并允许该角色担任自身。请参阅系统凭据的 trust policy。

启用访问

系统凭据访问默认禁用。要启用它,请在每个 n8n 实例(主实例和 worker)上设置以下环境变量:

N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED=true

警告

启用后,任何能够创建 AWS (Assume Role) 凭据的 n8n 用户都可以使用服务器自身的 AWS 身份作为担任角色的起点。仅应在单租户、自行托管的实例上启用,而且你应信任所有能够创建凭据的用户。

要限制工作流可通过服务器身份执行的操作,请尽量减少服务器自身的 IAM 权限。理想情况下,只授予它对工作流应使用的特定角色执行 sts:AssumeRole 的权限,并为每个角色设置 External ID 保护。

支持的凭据来源

n8n 会按以下顺序尝试这些来源,并使用第一个返回凭据的来源:

顺序 来源 n8n 的检测方式 常见平台
1 环境变量 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY(可选 AWS_SESSION_TOKEN) 任意平台
2 EKS IAM Roles for Service Accounts (IRSA) AWS_ROLE_ARN 和 AWS_WEB_IDENTITY_TOKEN_FILE Amazon EKS
3 EKS Pod Identity AWS_CONTAINER_CREDENTIALS_FULL_URI Amazon EKS
4 ECS 或 Fargate task role AWS_CONTAINER_CREDENTIALS_RELATIVE_URI Amazon ECS / Fargate
5 EC2 instance profile EC2 instance metadata service (IMDSv2) Amazon EC2

请注意以下事项:

  • 配置相应平台功能后,AWS 会自动注入用于检测来源 2 至 4 的变量。你无需自行设置。
  • 如果在容器上设置了 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY,它们的优先级高于 IRSA、Pod Identity 和 instance role。如果希望使用联合身份来源,请移除这些变量。
  • n8n 会在需要时解析系统凭据,因此会自动获取轮换后或短期有效的来源凭据(例如 Kubernetes 轮换的 IRSA token)。
  • n8n 有意不支持从 ~/.aws 读取 AWS CLI profiles(AWS_PROFILE)。

在 Amazon EKS 中使用 IRSA

IAM Roles for Service Accounts 会将 IAM 角色与运行 n8n 的 Kubernetes service account 关联起来。使用角色 ARN(eks.amazonaws.com/role-arn)为 service account 添加注解。随后,EKS 会将 AWS_ROLE_ARN 和 AWS_WEB_IDENTITY_TOKEN_FILE 注入 pod,n8n 再通过区域 STS endpoint 交换 token。

在 Amazon EKS 中使用 Pod Identity

EKS Pod Identity 是 IRSA 的新替代方案。安装 Pod Identity Agent add-on,并在 n8n service account 和 IAM 角色之间创建 pod identity association。无需设置 OIDC provider。

Amazon ECS 和 Fargate

为 n8n task definition 分配 task role。

Amazon EC2

将 instance profile 附加到运行 n8n 的实例。n8n 使用 IMDSv2,因此禁用 IMDSv1 的实例也可以正常工作。

系统凭据的 trust policy

在 Role ARN 角色 ARN中输入的角色必须信任 n8n 运行时使用的身份:IRSA role、Pod Identity role、ECS task role 或 EC2 instance role。请使用该角色的 ARN 作为 Principal,不要使用账号 root。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/n8n-service-account-role"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-unique-external-id"
        }
      }
    }
  ]
}

要查找用作 Principal 的 ARN,请从 n8n 容器或实例内部运行 aws sts get-caller-identity。

如果 n8n 运行时使用的角色已具备工作流所需权限,请将同一角色用作 Role ARN 角色 ARN,并按上方示例将其自身 ARN 添加到 trust policy。即使角色担任自身,AWS 也要求这样配置。

n8n 运行时使用的角色还需要对目标角色拥有 sts:AssumeRole 权限。请只为工作流应使用的特定角色授予权限,不要对 * 授权。

AWS 中国区域和 GovCloud

提示

从 n8n 2.29.0 开始可用。在更早版本中,IRSA 无法用于 AWS 中国区域和 GovCloud 分区,因为 n8n 调用的是全局 STS endpoint。

系统凭据和角色担任适用于所有 AWS 分区。n8n 会调用凭据所在区域的 STS endpoint:AWS 中国区域(cn-*)为 sts.{region}.amazonaws.com.cn,AWS GovCloud(us-gov-*)为 sts.us-gov-{east,west}-1.amazonaws.com。

代理行为

如果实例使用 HTTP(S) proxy(HTTPS_PROXY、HTTP_PROXY、NO_PROXY),n8n 会通过该 proxy 路由 STS 调用(web identity exchange 和 AssumeRole)。对 link-local metadata service(EC2 IMDS、ECS 和 Pod Identity endpoints)的请求始终直接发送,绝不经过 proxy。这些地址只能从 host 本身访问。

相关环境变量

变量 默认值 用途
N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED false 允许 AWS (Assume Role) 凭据中的 Use System Credentials 使用系统凭据选项读取服务器的 AWS 身份。
N8N_AWS_SYSTEM_CREDENTIALS_SDK_SOURCES all 过渡性设置,从 n8n 2.29.0 开始可用。控制哪些系统凭据来源通过 AWS SDK 解析,而不是通过 n8n 的旧版 resolver 解析。可接受 all、none,或由 environment、roleForServiceAccount、podIdentity、containerMetadata、instanceMetadata 组成的逗号分隔子集。仅当升级后 AWS 身份验证中断时才更改此设置。n8n 将在未来版本中移除此 flag。
N8N_AWS_LEGACY_SIGNER false 过渡性设置,从 n8n 2.30.0 开始可用。设置为 true 后,将使用旧版 aws4 signer 为 AWS 请求签名,而不是 AWS 的 Signature V4 实现。仅在升级后 AWS 请求失败时将其用于回滚。n8n 将在未来版本中移除此 flag。

故障排除

  • “Access to AWS system credentials disabled, contact your administrator.”:Use System Credentials 使用系统凭据选项已开启,但服务器上的 N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED 未设置为 true。
  • 使用了错误的身份:环境变量的优先级高于 IRSA,IRSA 高于 Pod Identity、ECS 和 EC2。最常见的原因是容器中遗留了 AWS_ACCESS_KEY_ID。请参阅支持的凭据来源。
  • EKS 上的凭据测试失败:检查 service account annotation(IRSA)或 pod identity association,并确认 pod 收到了注入的环境变量(kubectl exec <pod-name> -- env | grep AWS)。
  • 调用 sts:AssumeRole 时出现 AccessDenied:n8n 找到了系统凭据,但目标角色拒绝了这些凭据。检查该角色的 trust policy 是否指定了 n8n 运行时使用的身份,以及 External ID 外部 ID是否与 policy 的 condition 匹配。请参阅系统凭据的 trust policy。
不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。