Articles in this section

Configuring Your AWS S3 Destination

# In this article

# Prerequisites

AWS S3 authentication uses role-based access, by default–to grant access, you must prepopulate the trust policy with the data-syncing service account identifier, similar to the following example JSON object:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sts:AssumeRoleWithWebIdentity"
      ],
      "Principal": {
        "Federated": "accounts.google.com"
      },
      "Condition": {
        "StringEquals": {
          "accounts.google.com:oaud": "<some_organization_identifier>",
          "accounts.google.com:sub": "<some_service_account_identifier>"
        }
      }
    }
  ]
}

# Step 1: Create a destination S3 bucket

  1. Navigate to the S3 service page.

  2. Click Create bucket.

  3. Enter a Bucket name and modify settings, as needed, noting the bucket name and AWS region.

TIP

AWS recommends the following bucket settings:

  • Set Object Ownership to "ACLs disabled"
  • Set Block Public Access settings to "Block all public access"
  1. Click Create bucket.

TIP

Use a unique bucket for these transfers to:

  • Prevent resource contention with other workloads
  • Avoid accidental data loss from mixed lifecycle or cleanup rules
  • Improve security by reducing surface area and enabling tighter, destination-scoped policies

# Step 2: Create a policy and IAM role

# Create the policy

  1. Navigate to the IAM service page, click the Policies navigation tab, and click Create policy.

  2. Click the JSON tab, and paste the following policy, with the bucket name used in the previous step.

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

IMPORTANT

  • By default, a connection test is performed against the destination during initial configuration and s3:DeleteObject is required to clean up test artifacts. Once the test has been performed successfully and the destination added, this action can be safely removed, as S3 destinations are append-only by default.

  • You can optionally encrypt S3 destinations with KMS encryption (CMK)–SSE-C encryption isn't currently supported. For KMS encryption, add the following statement to the Statement array of your IAM policy to allow data encryption/decryption with your KMS key:

    {
  "Effect": "Allow",
  "Action": [
    "kms:GenerateDataKey",
    "kms:Decrypt"
  ],
  "Resource": "arn:aws:kms:REGION_NAME:ACCOUNT_ID:key/KEY_ID"
}

    Where you replace REGION_NAME, ACCOUNT_ID, and KEY_ID with your values.

  1. Proceed through the remaaining wizard steps to review the policy.

  2. Choose the policy name, add a description, and click Create policy.

# Create the role

  1. Navigate to the IAM service page, click the Roles navigation tab, and click Create role.

  2. Select Custom trust policy and paste the provided trust policy to enable AssumeRole access to this role, and click Next.

  3. Add the permissions policy created above and click Next.

  4. Enter a Role name (such as, transfer-role) and click Create role.

  5. Search for and click the created role in the Roles list and note the ARN value.

NOTE

AWS recommends role based authentication, however, if you want to use HMAC Access Key ID & Secret Access Key, instead, follow these steps:

  1. Navigate to the IAM service page, click the Users navigation tab, and click Add users.

  2. Enter a User name for the service (such as, transfer-service), and click Next.

  3. Under Select AWS access type, select the Access key - Programmatic access option, and click Next: Permissions.

  4. Click the Attach existing policies directly option, search for and select the policy name created in the previous step, and click Next: Tags.

  5. Click Next: Review and click Create user.

  6. In the Success screen, record the Access key ID and the Secret access key.

# Step 3: Create a new destination

Create a new destination for data writing.

  1. Log in to Iterable as a user with the Manage Integrations project permission and open the project you're working on.

  2. Go to Integrations > Data Sync.

  3. Select the name of the destination that you're connecting to, then click Continue.

  4. Provide the following details:

    • Destination name – A name for the destination.
    • Folder prefix – The folder for the destination.
    • Auth Method – Choose one of the following:
      • IAM Role – Recommended. Uses service account impersonation. Enter the Custom Trust Policy and IAM Role ARN.
      • User/Password – Key-based authentication. Enter the password for the destination service account, the Bucket Access ID, and the Bucket Secret Key.
    • S3 bucket name – The staging bucket for data transfers.
    • S3 bucket region – The region where your staging bucket is located.
    • File format – The file format for the destination (Parquet is recommended).
    • Disable manifest files – If you don't want to create a manifest file for batch of data.

  5. Click Create Destination.

# Permissions checklist

Verify that the following permissions are applied in your project:

  • IAM policy on the role allows:

    • s3:PutObject on arn:aws:s3:::BUCKET_NAME*
    • s3:DeleteObject on arn:aws:s3:::BUCKET_NAME* (only required for initial connection test; may be removed after setup)
    • kms:GenerateDataKey and kms:Decrypt on your CMK ARN (only required if using KMS encryption [CMK])

  • Bucket exists in the intended region; folder prefix (if any) is configured as desired

  • Trust policy allows the data transfer service to assume the role

# FAQ

Q: How is the S3 connection secured?

A: Recommended: Role-based access using an IAM Role with a scoped permissions policy. The role is assumed via a trust policy and short-lived credentials, so no long-lived access keys are required. Optionally, if your policies require it, you can configure access with HMAC access keys. For at-rest encryption, S3-managed encryption or KMS CMKs are supported (see the KMS note, above, for required actions). Grant only the minimum permissions needed (PutObject and DeleteObject) to initially test the connection.

Q: What permissions are required?

A: The connection identity needs s3:PutObject and s3:DeleteObject permissions on the destination bucket. s3:DeleteObject is only required for the initial connection test and can be removed afterward for append-only destinations.

Q: What credentials and connection details are required?

A: You'll need to provide the bucket name, bucket region, and IAM role ARN (or HMAC access keys if using key-based authentication).

Q: Do you support KMS encryption?

A: Yes. S3 destinations support KMS CMK encryption. SSE-C encryption isn't currently supported. When using KMS encryption, ensure your IAM policy includes kms:GenerateDataKey and kms:Decrypt permissions on your CMK ARN.

Related articles