Access AWS resources from your Decodable account

Decodable can interact with resources in AWS on your behalf. This might include things like a source connector reading data from an S3 bucket, or writing data to an AWS Kinesis stream.

Access is configured through an IAM role—not individual AWS user accounts. The IAM role has a trust policy that links your Decodable account ID with the Decodable AWS account (which runs your connector), enabling Decodable to act on your behalf using the IAM role

A diagram showing the overview of how access to AWS resources is managed using IAM roles and policies.

You must configure three things:

A trust policy, which grants access from the Decodable account to your IAM role.
A permission policy, which grants access to the specific AWS resources from your IAM role. Refer to the specific documentation for a connector to see what permissions are required.
An IAM role that has both of these policies. You will use the ARN of this role when configuring connectors.

You will usually have one permission policy per Decodable resource (such as a connector) that needs access to AWS, whilst the IAM role may be used more than once depending on your specific security requirements.

The information on this page is for managed Decodable only. If you’re using Bring-Your-Own-Cloud (BYOC) then authorization is managed directly through your own account. Contact Decodable support for more details.

Trust policy

A Trust Policy allows access from Decodable’s AWS account to your IAM role.

The Principal is Decodable’s AWS account, and is a fixed value of arn:aws:iam::671293015970:root.
The ExternalId must match your Decodable account name.

A diagram showing the relationship between your Decodable account

The following is an example of a Trust Policy:

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

Trust Policy with multiple Decodable accounts

To allow several Decodable Accounts (say, in different AWS Regions) to write to the same bucket, use an array of Account names for the ExternalId value:

{ "sts:ExternalId": ["my-acct-1", "my-acct-2"] }

See The confused deputy problem for more information about why the ExternalId value is required.

Permission policy

Consult the specific requirements detailed on the connector page to see what permissions are required.

Example steps for setting up an IAM role

How you implement the IAM role and associated trust and permission policies will be specific to your AWS account’s resource security strategies and organisational policies. Here is a simplified example of how it can be applied in an isolated account.

You should always follow security best-practices. The below is intended as a simple example only.

Trust policy

Assuming your Decodable account name is acme-corp-01, write a trust policy:

trust-policy.json

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

IAM role

Create an IAM role with the trust policy. This enables Decodable to assume this IAM role and thus the subsequent permissions that will be associated with it. There are different ways of creating IAM roles in AWS. Here is how to do it with the AWS CLI:

aws iam create-role \
        --role-name acme-corp-decodable-role \
        --assume-role-policy-document file://./trust_policy.json

In the output of this command will be the ARN of the role that has been created:

{
    "Role": {
        "Path": "/",
        "RoleName": "acme-corp-decodable-role",
        "Arn": "arn:aws:iam::123456789:role/acme-corp-decodable-role",
[…]

Permission policy

Let’s say we’re creating an S3 sink. We’ll write a permission policy to enable write access to the analytics warehouse under the inventory path:

s3-analytics-permission.json

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

Associate this policy with the IAM role using the AWS CLI:

aws iam put-role-policy \
        --role-name "acme-corp-decodable-role" \
        --policy-name "analytics-inventory-s3" \
        --policy-document file://./s3-analytics-permission.json