n8n-nodes-s3-tables

Custom n8n node that interacts with structured data stored in Amazon S3 using IAM role authentication.

Features

• Assume AWS IAM roles at runtime using STS
• Retrieve table rows from JSON objects stored in S3
• Append new rows to existing table objects
• Resolve table object locations through the AWS S3 Tables metadata API

Development

npm install
npm run build

The compiled files will be generated in the dist directory.

Usage

1. Run npm run build to generate the compiled artifacts in dist.
2. In your n8n instance, change to the custom modules directory (default ~/.n8n/custom) and install this project via npm install /path/to/n8n-s3-table-node or npm install BCusack/n8n-s3-table-node.
3. Restart n8n so it can load the new node.
4. Create AWS IAM Role credentials using the role you prepared below and select them on the AWS S3 Tables node inside your workflow.
5. In the node, choose whether to target a direct S3 object or resolve the object via S3 Tables Metadata.

Selecting a Table Source

• Direct S3 Object – Provide the bucket name and object key for the CSV/JSON data you manage manually.
• S3 Tables Metadata – Supply the table bucket ARN, namespace, and table name. The node calls GetTableMetadataLocation to resolve the current metadata file and uses that S3 object for reads and writes.

Local Testing

Following the n8n testing guide, you can link the package into a local n8n install without publishing it:

# inside this repository
npm run build
npm link

# inside your n8n custom directory (for example ~/.n8n/custom)
npm link n8n-nodes-s3-tables

# start n8n and search for "AWS S3 Tables"
n8n start

AWS IAM Role Setup

To allow the node to assume a role and access S3, create an IAM role configured for STS AssumeRole and grant it the required S3 permissions.

1. Create the IAM role
   • In the AWS console, go to IAM → Roles → Create role.
   • Choose Trusted entity type: AWS account and enter the account ID of the identity that n8n uses for authentication (for n8n Cloud, this is typically your own account; for self-hosted, use the account tied to your AWS access key).
   • Optional: Specify an External ID if you require a third-party identifier for additional security. Enter the same value in the node credentials.
2. Attach permissions
   • Grant the role the minimum needed Amazon S3 Tables actions (s3tables service prefix) along with the S3 data-plane permissions that back them. Update the resource ARNs with your table bucket name and namespace.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "AllowS3TablesMetadata",
			"Effect": "Allow",
			"Action": [
				"s3tables:GetTable",
				"s3tables:GetTableMetadataLocation",
				"s3tables:ListTables"
			],
			"Resource": "arn:aws:s3tables:{REGION}:123456789012:bucket/{BUCKET}/table/*"
		},
		{
			"Sid": "AllowS3TablesData",
			"Effect": "Allow",
			"Action": [
				"s3tables:GetTableData",
				"s3tables:PutTableData"
			],
			"Resource": "arn:aws:s3tables:{REGION}:123456789012:bucket/{BUCKET}/table/{TABLE_ID}"
		},
		{
			"Sid": "DataPlaneAccess",
			"Effect": "Allow",
			"Action": [
				"s3:GetObject",
				"s3:PutObject"
			],
			"Resource": "arn:aws:s3:::your-table-bucket/*"
		}
	]
}

3. Review the trust policy
   • A minimal trust relationship that allows an IAM user or role in your account to assume the S3 Tables role looks like this:

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

4. Record the details
   • Copy the role ARN and, if used, the external ID. Supply them in the node credentials along with the target region and optional session duration.
   • Ensure the IAM user or role that n8n runs under has permission to call sts:AssumeRole on the new role.

Once the role is in place, populate the AWS IAM Role credentials in n8n with:

• Role ARN: arn:aws:iam::123456789012:role/YourS3TablesRole
• Session Name: Optional label for CloudTrail/auditing.
• External ID: Value from the trust policy if configured.
• Region: AWS region where your bucket resides.
• Assume Role Duration: Optional session duration (15–720 minutes).

License

MIT