S3 Connection

Configure AWS IAM roles and permissions to connect your Amazon S3 bucket to UbiQuity Connectors.

CONNECTORS ARE COMING AUGUST 2026

This guide walks you through configuring your AWS account so that UbiQuity can securely connect to your Amazon S3 bucket. The setup involves creating an IAM role in your AWS account and granting UbiQuity permission to assume it - no long-lived access keys or secrets are required.

How it works

UbiQuity connects to your S3 bucket using cross-account IAM role assumption. When the connector runs, UbiQuity's service temporarily assumes a role in your AWS account using AWS STS. This means:

Credentials are temporary and expire after one hour. The connector refreshes them automatically
Access is scoped to only the S3 permissions you grant
Your UbiQuity Account ID acts as an External ID, preventing any other UbiQuity customer from assuming your role
No permanent access keys are stored in UbiQuity

Before you begin

You'll need the following before starting:

What you need

Description

Example

AWS Account ID

Your 12-digit AWS account identifier

123456789012

S3 Bucket Name

The bucket the connector will read from or write to

customer-data-imports

S3 Region

The AWS region where your bucket is hosted

ap-southeast-2

UbiQuity Account ID

Your Database ID in base64 format — find this in UbiQuity under API > API IDs > Database ID

xWqJBlwfjUOUcQjd5gt7vQ

Step 1: Create the IAM role

In your AWS account, create an IAM role with the following name:

ubiquity-connectors-s3-access-role

Important: This exact role name is required. UbiQuity's infrastructure uses a specific AssumeRole policy targeting arn:aws:iam::*:role/ubiquity-connectors-s3-access-role to avoid wildcard role names while supporting multiple customer accounts.

Step 2: Configure the trust policy

The trust policy controls who is allowed to assume the role. Apply the policy below, replacing YOUR_UBIQUITY_ACCOUNT_ID with your UbiQuity Database ID (found at API > API IDs > Database ID in the platform).

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::049579744830:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_UBIQUITY_ACCOUNT_ID"
        }
      }
    }
  ]
}

Why the External ID matters: All UbiQuity customers share the same UbiQuity AWS account. The External ID condition ensures that only your connectors, authenticated with your specific UbiQuity Account ID, can assume your role.

Step 3: Attach a permissions policy

Create a new IAM policy named ubiquity-s3-access-policy and attach it to the role from Step 1. Replace YOUR_BUCKET_NAME with your actual bucket name.

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    },
    {
      "Sid": "ObjectOperations",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}

What each permission is for:

s3:ListBucket — allows the connector to list objects in the bucket and verify the connection
s3:GetObject — allows the connector to read your data files for import
s3:PutObject — allows the connector to write files to your archive and error subdirectories after processing
s3:DeleteObject — used alongside PutObject to move processed files into your archive and error subdirectories

Note: Files are never permanently deleted. After processing, they are moved to an archive subfolder (or error subfolder if processing fails), preserving a full history of what was imported.

Step 4: Add the connector in UbiQuity

Once your IAM role is configured:

In UbiQuity, go to Database > Connectors > Add Connector
Select Amazon S3
Enter the following details:
- AWS Account ID — your 12-digit AWS account ID
- Region — the AWS region where your bucket is hosted (e.g. ap-southeast-2)
- Bucket Name — your S3 bucket name (case-sensitive)
- Prefix (optional) — a folder path to limit connector access to a specific location within the bucket (e.g. imports/)
Click Test Connection

A successful test will return: "Connection successful. Found X files in bucket."

Troubleshooting

"Access denied" or "Not authorised to perform sts:AssumeRole"

The connector cannot assume your IAM role. Check the following:

The role name is exactly ubiquity-connectors-s3-access-role (case-sensitive)
The trust policy Principal is arn:aws:iam::049579744830:root
The External ID in the trust policy matches your UbiQuity Account ID exactly — copy it directly from the platform to avoid whitespace issues

Role assumption succeeds but S3 operations fail

The connector can reach your account but cannot access the bucket. Check:

The ubiquity-s3-access-policy is attached to the role
Your bucket policy doesn't contain an explicit Deny that would override the IAM permissions
If your bucket uses SSE-KMS encryption, the KMS key policy must grant kms:Decrypt and kms:DescribeKey to the assumed role (see Encrypted buckets below)

"Bucket does not exist in region"

Double-check the bucket name — it is case-sensitive and must not contain spaces
Verify the region in UbiQuity matches the actual region of your bucket
Confirm the bucket exists in the same AWS account as the IAM role

"Invalid External ID" or "External ID mismatch"

Copy your UbiQuity Account ID directly from API > API IDs > Database ID in the platform
Check for any extra spaces or line breaks that may have been introduced when pasting

Additional configuration

Restricting access to a specific folder

If you'd prefer the connector to only access a specific prefix within your bucket rather than the full bucket, use this modified policy:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucket",
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME",
      "Condition": {
        "StringLike": {
          "s3:prefix": ["imports/ubiquity/*"]
        }
      }
    },
    {
      "Sid": "ObjectOperations",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/imports/ubiquity/*"
    }
  ]
}

Encrypted buckets

The connector supports S3 server-side encryption as follows:

SSE-S3 — supported out of the box (AWS default encryption)
SSE-KMS — supported, provided the KMS key policy grants kms:Decrypt and kms:DescribeKey to the assumed role. Add the following to your KMS key policy, replacing YOUR_AWS_ACCOUNT_ID:

json

{
  "Sid": "AllowUbiQuityConnectorDecrypt",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/ubiquity-connectors-s3-access-role"
  },
  "Action": [
    "kms:Decrypt",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}

SSE-C — not supported (requires client-managed keys)

Granting access to multiple buckets

Extend the permissions policy to include each bucket:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBuckets",
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::bucket-one",
        "arn:aws:s3:::bucket-two"
      ]
    },
    {
      "Sid": "ObjectOperations",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::bucket-one/*",
        "arn:aws:s3:::bucket-two/*"
      ]
    }
  ]
}

Note that buckets in different AWS regions will each need a separate connector configured in UbiQuity, but can share the same IAM role.

Revoking access

To remove UbiQuity's access at any time, you have three options:

Delete the role — immediately and permanently revokes access
Modify the trust policy — remove the UbiQuity statement or change the External ID to invalidate future sessions
Disable the connector in UbiQuity — prevents new connections being initiated; any active session will expire within the hour regardless

Need help?

If you run into issues during setup, contact our support team at support@ubiquity.co.nz with the following details:

Your AWS Account ID (12 digits)
Your S3 bucket name and region
Any error messages shown in UbiQuity or your AWS CloudTrail logs
Screenshots of your IAM role configuration

PreviousConnection Setup NextAzure Blob Storage Connection

Last updated 1 month ago

Was this helpful?