# S3 Connection {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} 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 ```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 ```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: 1. In UbiQuity, go to **Database > Connectors > Add Connector** 2. Select **Amazon S3** 3. 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/`) 4. 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 ```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 ```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 ```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**](mailto: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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ubiquity.co.nz/documentation/data-and-integrations/connectors/connection-setup/s3-connection.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.