n8n AWS SQS Plugin

An n8n community node that provides comprehensive AWS SQS (Simple Queue Service) integration with support for both same-account and cross-account access, featuring IMDSv2 authentication for EC2 instances.

Features

• Two Node Types:

  • AWS SQS Node: Manual message operations (send, receive, delete)
  • AWS SQS Trigger Node: Automated polling and triggering on new messages

• Authentication Methods:

  • IMDSv2 (Instance Metadata Service v2) for EC2 instances with IAM roles
  • AWS Access Keys for traditional authentication
  • Cross-account role assumption with optional External ID

• Flexible Message Handling:

  • Configurable polling intervals
  • Long polling support (up to 20 seconds)
  • Batch message processing
  • Auto-delete messages option
  • Message attributes support

Installation

npm install n8n-nodes-aws-sqs

Then restart your n8n instance. The AWS SQS nodes will appear in the node palette.

Configuration

Credentials Setup

1. Go to Credentials in your n8n instance
2. Create a new credential of type AWS SQS API
3. Configure authentication:

IMDSv2 Authentication (Recommended for EC2)

• Authentication Method: IMDSv2 (EC2 Instance Role)
• Region: Your AWS region
• Cross-Account Role ARN: (Optional) For cross-account access
• External ID: (Optional) If required by the cross-account role

Access Keys Authentication

• Authentication Method: Access Keys
• AWS Access Key ID: Your AWS access key
• AWS Secret Access Key: Your AWS secret key
• Session Token: (Optional) For temporary credentials
• Region: Your AWS region
• Cross-Account Role ARN: (Optional) For cross-account access

Required IAM Permissions

For the IAM role or user, ensure the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:DeleteMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:PurgeQueue"
      ],
      "Resource": "arn:aws:sqs:*:*:your-queue-name"
    }
  ]
}

For cross-account access, also add:

{
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "arn:aws:iam::TARGET-ACCOUNT:role/YOUR-CROSS-ACCOUNT-ROLE"
}

Usage

AWS SQS Node (Manual Operations)

Receive Messages

• Resource: Message
• Operation: Receive
• Queue Name or URL: my-queue or full SQS URL
• Max Number of Messages: 1-10 (default: 1)
• Visibility Timeout: 0-43200 seconds (default: 30)
• Wait Time Seconds: 0-20 seconds for long polling (default: 0)

Send Messages

• Resource: Message
• Operation: Send
• Queue Name or URL: my-queue or full SQS URL
• Message Body: The message content
• Delay Seconds: 0-900 seconds (default: 0)
• Message Attributes: Optional key-value pairs

Delete Messages

• Resource: Message
• Operation: Delete
• Queue Name or URL: my-queue or full SQS URL
• Receipt Handle: Handle from received message

AWS SQS Trigger Node (Automated Polling)

Perfect for workflows that need to react to new SQS messages:

• Queue Name or URL: my-queue or full SQS URL
• Polling Interval: 10-3600 seconds (default: 60)
• Max Messages Per Poll: 1-10 (default: 10)
• Visibility Timeout: 0-43200 seconds (default: 300)
• Wait Time Seconds: 0-20 seconds for long polling (default: 20)
• Auto Delete Messages: Automatically delete processed messages (default: true)

Advanced Options

• Stop Polling on Empty Queue: Stop when no messages are available
• Message Batch Processing: Process messages individually or in batches

Cross-Account Access Setup

To access SQS queues in another AWS account:

1. In the Target Account (where the SQS queue exists):

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

2. In the Source Account (where n8n runs):

   • Grant sts:AssumeRole permission for the target role
   • Configure the Cross-Account Role ARN in credentials

Examples

Example 1: Basic Message Processing

SQS Trigger → Process Message → Send Email

Example 2: Cross-Account Message Processing

1. Configure credentials with cross-account role
2. Set queue URL: https://sqs.region.amazonaws.com/TARGET-ACCOUNT/queue-name
3. Use SQS Trigger to automatically process messages

Example 3: Manual Message Operations

Manual Trigger → SQS Send → SQS Receive → Process Response

Best Practices

1. Use IMDSv2 when running on EC2 for security
2. Enable Long Polling (set Wait Time Seconds > 0) to reduce costs
3. Set appropriate Visibility Timeout to prevent message reprocessing
4. Use Auto Delete in trigger node to prevent duplicate processing
5. Monitor CloudWatch for queue metrics and errors
6. Test Cross-Account Access thoroughly in non-production first

Troubleshooting

Common Issues

1. "Access Denied" errors:

   • Check IAM permissions
   • Verify role assumption is working
   • Check External ID if using cross-account access

2. IMDSv2 not working:

   • Ensure EC2 instance has required IAM role
   • Check if IMDSv2 is enforced on the instance
   • Verify network connectivity to IMDS endpoint

3. Messages not appearing:

   • Check queue visibility timeout
   • Verify message is not in DLQ (Dead Letter Queue)
   • Check SQS queue permissions

4. Trigger not firing:

   • Verify polling interval settings
   • Check n8n logs for errors
   • Ensure queue has messages

Version History

• 1.0.0: Initial release with basic SQS operations and IMDSv2 support
  • AWS SQS Node for manual operations
  • AWS SQS Trigger Node for automated polling
  • Cross-account access support
  • IMDSv2 authentication

License

MIT License

Contributing

Pull requests are welcome! Please ensure all tests pass and follow the existing code style.

Support

For issues and feature requests, please use the GitHub issue tracker.