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) 자격 증명#

이 자격 증명을 사용하면 다음 노드를 인증할 수 있습니다:

• AWS Bedrock Chat Model
• AWS Certificate Manager
• AWS Cognito
• AWS Comprehend
• AWS DynamoDB
• AWS Elastic Load Balancing
• AWS IAM
• AWS Lambda
• AWS Rekognition
• AWS S3
• AWS SES
• AWS SNS
• AWS SNS Trigger
• AWS SQS
• AWS Textract
• AWS Transcribe
• Embeddings AWS Bedrock

지원되는 인증 방법#

• API 액세스 키

관련 자료#

이 서비스에 대한 자세한 내용은 AWS의 Identity and Access Management 문서를 참조하세요.

API 액세스 키 사용#

이 자격 증명을 구성하려면 AWS 계정과 다음이 필요합니다:

• AWS 리전(Region)
• 액세스 키 ID(Access Key ID): 액세스 키를 생성할 때 함께 생성됩니다.
• 시크릿 액세스 키(Secret Access Key): 액세스 키를 생성할 때 함께 생성됩니다.

액세스 키를 생성하고 자격 증명을 설정하려면:

1. n8n 자격 증명에서 AWS 리전을 선택합니다.

2. IAM 콘솔에 로그인합니다.

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. 액세스 키 ID와 시크릿 액세스 키를 확인하고 n8n에 입력합니다.

10. **임시 보안 자격 증명(Temporary security credential)**을 사용하려면 해당 옵션을 켜고 **세션 토큰(Session token)**을 추가합니다. 임시 보안 자격 증명 사용에 대한 자세한 내용은 AWS 임시 보안 자격 증명 문서를 참조하세요.

11. n8n을 호스팅하는 데 Amazon Virtual Private Cloud(VPC)를 사용하는 경우, VPC와 일부 앱 사이에 연결을 설정할 수 있습니다. 이 연결에 관련된 커스텀 엔드포인트를 입력하려면 Custom Endpoints를 사용하세요. 이 설정은 다음 앱에서 작동합니다:

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

    Bedrock에는 두 가지 엔드포인트 필드가 있습니다. Bedrock Endpoint는 사용 가능한 모델을 나열하는 데 사용되며, Bedrock Runtime Endpoint는 AWS Bedrock Chat Model 및 Embeddings AWS Bedrock 노드의 추론에 사용됩니다. 프라이빗 DNS 없이 VPC 인터페이스 엔드포인트(PrivateLink)를 통해 Bedrock을 라우팅하는 경우 두 필드를 모두 설정하세요.

AWS CLI 및 AWS API를 통해서도 액세스 키를 생성할 수 있습니다. 이러한 방법을 사용해 액세스 키를 생성하는 방법은 AWS 액세스 키 관리 문서를 참조하세요.

AWS (Assume Role) 자격 증명#

이 자격 증명을 사용하면 IAM 역할 위임(role assumption)을 통해 강화된 보안으로 다음 노드를 인증할 수 있습니다:

• AWS Bedrock Chat Model
• AWS Certificate Manager
• AWS Cognito
• AWS Comprehend
• AWS DynamoDB
• AWS Elastic Load Balancing
• AWS IAM
• AWS Lambda
• AWS Rekognition
• AWS S3
• AWS SES
• AWS SNS
• AWS SNS Trigger
• AWS SQS
• AWS Textract
• AWS Transcribe
• Embeddings AWS Bedrock

지원되는 인증 방법#

• 역할 위임(Role Assumption)

관련 자료#

역할 위임에 대한 자세한 내용은 AWS의 IAM Role 문서와 STS AssumeRole 문서를 참조하세요.

AWS 역할 위임 이해하기#

AWS 역할 위임(Role Assumption)을 사용하면 장기간 유효한 액세스 키를 사용하는 대신 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이 갱신할 수 없는 정적 세션 토큰을 입력하므로, 토큰이 만료되면 새 토큰을 입력해야 합니다.

AWS Assume Role 자격 증명 설정#

이 자격 증명을 구성하려면 다음이 필요합니다:

필수 매개변수#

• Region(리전): 역할을 위임받기 위해 STS 서비스를 호출할 AWS 리전입니다. n8n은 이 리전의 리전별 STS 엔드포인트를 호출합니다. AWS 중국(cn-*) 및 AWS GovCloud(us-gov-*) 파티션도 포함됩니다(n8n 2.29.0부터 사용 가능).
• Role ARN(역할 ARN): 위임받으려는 IAM 역할의 ARN(Amazon Resource Name)입니다. arn:aws:iam::123456789012:role/MyRole 형식입니다. 이 역할에는 사용자의 자격 증명이 이를 위임받을 수 있도록 허용하는 신뢰 정책(trust policy)이 있어야 합니다.
• External ID(외부 ID): "혼란스러운 대리인(confused deputy)" 문제를 방지하기 위해 역할의 신뢰 정책에서 요구하는 고유 식별자입니다. 사용자가 직접 생성하여 역할의 신뢰 정책과 이 자격 증명 양쪽에 동일하게 설정해야 하는 비밀 값이어야 합니다. 이 값은 민감 정보로 취급하세요. 신뢰하지 않는 다른 n8n 사용자와 공유하지 마세요.
• Role Session Name(역할 세션 이름): 위임받은 역할 세션에 대한 이름입니다(감사 목적으로 사용). 기본값은 n8n-session입니다. 이 값은 AWS CloudTrail 로그에 표시되어 세션을 식별할 수 있게 해줍니다.

STS 자격 증명 (방법 하나 선택)#

STS AssumeRole 호출을 하기 위한 자격 증명을 제공하는 방법은 두 가지입니다:

Option 1: 시스템 자격 증명 사용 (서버 배포에 권장)#

n8n 서버가 실행되는 환경에 이미 AWS ID가 있는 경우 Use System Credentials를 켜세요. 그러면 n8n이 n8n에 정적 키를 저장하지 않고도 AssumeRole 호출에 사용할 자격 증명을 자동으로 찾습니다. 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 태스크 역할
5. EC2 인스턴스 프로필

이 옵션을 사용하려면 n8n 관리자가 환경 변수 N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED를 true로 설정하여 시스템 자격 증명 액세스를 활성화해야 합니다. 설정 방법과 보안 고려 사항은 AWS 시스템 자격 증명 사용을 참조하세요.

Option 2: 수동 STS 자격 증명#

시스템 자격 증명을 사용할 수 없는 경우, 다음을 직접 제공하세요:

• STS Access Key ID: 대상 역할을 위임받을 권한이 있는 IAM 사용자 또는 역할의 액세스 키 ID입니다.
• STS Secret Access Key: STS 액세스 키 ID에 해당하는 시크릿 액세스 키입니다.
• STS Session Token(선택 사항): STS 호출에 임시 자격 증명을 사용하는 경우의 세션 토큰입니다.

선택 매개변수#

• Custom Endpoints: Amazon VPC를 사용하는 경우, AWS 서비스에 대한 커스텀 엔드포인트를 지정할 수 있습니다:

  • Rekognition Endpoint
  • Lambda Endpoint
  • SNS Endpoint
  • SES Endpoint
  • SQS Endpoint
  • S3 Endpoint
  • SSM Endpoint
  • Bedrock Endpoint(사용 가능한 모델을 나열하는 데 사용)
  • Bedrock Runtime Endpoint(예: VPC 인터페이스 엔드포인트(PrivateLink)를 통한 Bedrock 추론에 사용)

설정 단계#

1. 대상 AWS 계정에 IAM 역할을 생성합니다. 이 신뢰 정책은 Option 2: 수동 STS 자격 증명용입니다. Option 1: 시스템 자격 증명 사용을 사용하는 경우 Principal은 n8n 자체가 실행되는 역할입니다. 시스템 자격 증명용 신뢰 정책을 참조하세요.

   {
     "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을 입력합니다
   • 고유한 External ID를 설정합니다(신뢰 정책에 설정한 값과 동일해야 함)
   • STS 자격 증명 방법을 선택합니다
   • Role Session Name을 입력합니다(또는 기본값 사용)

3. 내장 테스트 기능을 사용해 자격 증명을 테스트하여 역할 위임이 정상적으로 작동하는지 확인합니다.

보안 모범 사례#

• 무단 액세스를 방지하기 위해 각 자격 증명마다 고유한 External ID를 사용하세요.
• 역할 위임에 사용하는 STS 자격 증명을 정기적으로 교체(rotate)하세요.
• 위임하는 자격 증명과 대상 역할 모두에 최소 권한 원칙을 적용하세요.
• 공유 인스턴스에서는 시스템 자격 증명 액세스를 비활성화한 상태로 유지하세요. AWS 시스템 자격 증명 사용을 참조하세요.

AWS 시스템 자격 증명 사용 (연합 인증)#

이 섹션은 셀프 호스팅 n8n 인스턴스의 관리자를 위한 내용입니다.

n8n이 AWS 인프라에서 실행되는 경우 인프라 자체가 AWS ID를 제공할 수 있습니다. 생성하거나 저장하거나 교체해야 하는 액세스 키가 없습니다. 이는 EKS, ECS, EC2의 워크로드를 인증하는 표준 방식이며, 보안 팀에서 종종 요구합니다("zero static keys").

n8n은 공식 AWS SDK 자격 증명 공급자로 이러한 시스템 자격 증명을 읽고, Use System Credentials를 켠 경우 AWS (Assume Role) 자격 증명의 시작 자격 증명으로 사용합니다. 이는 AWS Bedrock AI 노드를 포함하여 AWS (Assume Role) 자격 증명을 허용하는 모든 노드에서 작동합니다.

액세스 활성화#

시스템 자격 증명에 대한 액세스는 기본적으로 비활성화되어 있습니다. 활성화하려면 모든 n8n 인스턴스(메인 및 워커)에 다음 환경 변수를 설정하세요:

N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED=true

지원되는 자격 증명 소스#

n8n은 다음 소스를 순서대로 시도하며, 자격 증명을 반환하는 첫 번째 소스를 사용합니다:

유의할 점:

• 플랫폼 기능을 구성하면 AWS가 소스 2~4의 감지 변수를 자동으로 주입합니다. 직접 설정하지 않습니다.
• 컨테이너에 AWS_ACCESS_KEY_ID와 AWS_SECRET_ACCESS_KEY를 설정하면 IRSA, Pod Identity, 인스턴스 역할보다 우선합니다. 연합 소스를 사용하려면 이 변수를 제거하세요.
• n8n은 시스템 자격 증명이 필요할 때 이를 확인하므로, 교체되거나 수명이 짧은 소스 자격 증명(예: Kubernetes가 교체하는 IRSA 토큰)도 자동으로 반영됩니다.
• ~/.aws의 AWS CLI 프로필(AWS_PROFILE) 읽기는 의도적으로 지원하지 않습니다.

IRSA를 사용하는 Amazon EKS#

IAM Roles for Service Accounts는 IAM 역할을 n8n을 실행하는 Kubernetes 서비스 계정에 연결합니다. 서비스 계정에 역할 ARN(eks.amazonaws.com/role-arn)을 어노테이션으로 지정하세요. 그러면 EKS가 AWS_ROLE_ARN과 AWS_WEB_IDENTITY_TOKEN_FILE을 파드에 주입하고, n8n은 리전별 STS 엔드포인트와 토큰을 교환합니다.

Pod Identity를 사용하는 Amazon EKS#

EKS Pod Identity는 IRSA의 새로운 대안입니다. Pod Identity Agent 애드온을 설치하고 n8n 서비스 계정과 IAM 역할 사이에 Pod Identity 연결을 생성하세요. OIDC 공급자 설정은 필요하지 않습니다.

Amazon ECS 및 Fargate#

n8n 태스크 정의에 태스크 역할을 할당하세요.

Amazon EC2#

n8n을 실행하는 인스턴스에 인스턴스 프로필을 연결하세요. n8n은 IMDSv2를 사용하므로 IMDSv1을 비활성화한 인스턴스에서도 작동합니다.

시스템 자격 증명용 신뢰 정책#

Role ARN으로 입력하는 역할은 n8n이 실행되는 ID(IRSA 역할, Pod Identity 역할, ECS 태스크 역할 또는 EC2 인스턴스 역할)를 신뢰해야 합니다. Principal에는 계정 루트가 아니라 해당 역할의 ARN을 사용하세요.

{
  "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을 추가하세요. 역할이 자기 자신을 위임받는 경우에도 AWS는 이를 요구합니다.

n8n이 실행되는 역할에는 대상 역할에 대한 sts:AssumeRole 권한도 필요합니다. *가 아니라 워크플로가 사용해야 하는 특정 역할에 대해 부여하세요.

AWS 중국 및 GovCloud#

시스템 자격 증명과 역할 위임은 모든 AWS 파티션에서 작동합니다. n8n은 자격 증명의 리전에 해당하는 리전별 STS 엔드포인트를 호출합니다. AWS 중국(cn-*)에서는 sts.{region}.amazonaws.com.cn, AWS GovCloud(us-gov-*)에서는 sts.us-gov-{east,west}-1.amazonaws.com입니다.

프록시 동작#

인스턴스가 HTTP(S) 프록시(HTTPS_PROXY, HTTP_PROXY, NO_PROXY)를 사용하는 경우, n8n은 STS 호출(웹 ID 교환 및 AssumeRole)을 프록시를 통해 라우팅합니다. 링크 로컬 메타데이터 서비스(EC2 IMDS, ECS 및 Pod Identity 엔드포인트)로 가는 요청은 프록시를 거치지 않고 항상 직접 전송됩니다. 이 주소는 호스트 자체에서만 접근할 수 있습니다.

관련 환경 변수#

문제 해결#

• "Access to AWS system credentials disabled, contact your administrator.": Use System Credentials 옵션은 켜져 있지만 서버에 N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED가 true로 설정되어 있지 않습니다.
• 잘못된 ID가 사용됨: 환경 변수가 IRSA보다 우선하고, IRSA는 Pod Identity, ECS, EC2보다 우선합니다. 컨테이너에 남아 있는 AWS_ACCESS_KEY_ID가 가장 흔한 원인입니다. 지원되는 자격 증명 소스를 참조하세요.
• EKS에서 자격 증명 테스트 실패: 서비스 계정 어노테이션(IRSA) 또는 Pod Identity 연결을 확인하고, 파드가 주입된 환경 변수를 받았는지 확인하세요(kubectl exec <pod-name> -- env | grep AWS).
• sts:AssumeRole 호출 시 AccessDenied: n8n이 시스템 자격 증명을 찾았지만 대상 역할이 이를 거부했습니다. 역할의 신뢰 정책이 n8n이 실행되는 ID를 지정하는지, External ID가 정책 조건과 일치하는지 확인하세요. 시스템 자격 증명용 신뢰 정책을 참조하세요.