Skip to main content

Amazon S3

KoraBridge writes files under the bucket and optional prefix you give it. There are two ways to let it in: an IAM role in your AWS account (recommended), or an access key from an IAM user.

What you need​

  • Bucket URL. An s3:// bucket path with an optional prefix for KoraBridge output files.
  • Write access. Either an IAM role in your AWS account that trusts KoraBridge, or an access key pair with write access to the bucket.

Where to find it​

  • AWS IAM console or cloud admin. Your AWS admin creates the IAM role, or issues an access key for an IAM user.
  • S3 bucket details. Copy the bucket name and chosen folder path from AWS S3 or your S3-compatible provider.

Choose how KoraBridge connects​

KoraBridge assumes a role in your AWS account and receives short-lived credentials, so no long-lived key leaves your account. This mode is for Amazon S3 only.

Access key​

Use this when your organization allows long-lived IAM user keys, or for S3-compatible storage such as MinIO or Cloudflare R2.

Bucket URL​

Use s3://bucket-name/optional/prefix. KoraBridge writes files under the prefix, and the role's permissions are scoped to it. A bucket name without the s3:// prefix is rejected.

Region​

Required in both modes. The AWS region where the bucket lives. The connection test checks it against the bucket.

Create the IAM role in AWS​

Save the connection first. KoraBridge then shows a Create role in AWS button that sets up the role in your account, or the policies to create it by hand.

  1. Sign in to the right AWS account. Before you choose Create role in AWS, sign in to the account that owns the bucket. If your company uses AWS single sign-on, open your AWS access portal and choose that account. Check that the account number at the top right of the AWS console matches the bucket owner.
  2. Create the role. Choose Create role in AWS. It opens AWS in the account you are signed in to with everything filled in: a CloudFormation stack that creates the role with the trust and permissions policies. Review, tick the IAM acknowledgement, and choose Create stack.
  3. Paste the Role ARN. When AWS shows CREATE_COMPLETE, copy RoleArn from the Outputs tab into the Role ARN field in KoraBridge, save, then run Test connection.

The external ID​

KoraBridge generates an external ID for the connection the first time you save it in role mode. It is fixed for the life of the connection and cannot be edited. Your role's trust policy must require it with an sts:ExternalId condition. The create-role link fills this in for you, and the manual setup shows it. This stops anyone other than KoraBridge, acting for your connection, from using your role.

Set it up by hand​

Choose Set up manually instead of the button. It shows the trust policy and the permissions policy to create the role yourself in the IAM console.

Permissions the role needs​

The role must allow exactly these actions. Everything is scoped to your bucket and, if you set one, your prefix.

ActionResourceWhy
s3:ListBucketThe bucket, conditioned on s3:prefix matching <prefix>/* (no condition if the bucket URL has no prefix)List what is already there.
s3:GetBucketLocationThe bucketRequired. See the note below.
s3:GetObject, s3:PutObject, s3:DeleteObject<bucket>/<prefix>/*, or <bucket>/* with no prefixRead, write and clean up files.
warning

s3:GetBucketLocation is required. The S3 client checks the bucket exists and then asks for its location. Without that permission it concludes the bucket is missing and tries to create it, which fails with a misleading AccessDenied.

What Test connection checks​

Each test first confirms that AWS refuses to let KoraBridge use your role without the external ID, then uses the role with it. That proves only KoraBridge, with your external ID, can use the role. AWS does not record the refused attempt in your account, so your CloudTrail shows only successful AssumeRole calls from KoraBridge.

It then runs a real write probe under _kora_connection_test/ in your prefix:

  1. Check the bucket region matches the one you configured.
  2. List the write prefix.
  3. Look up a key that does not exist yet, as a first load does.
  4. Write a small test object.
  5. Read it back.
  6. Delete it. This is always attempted, even if an earlier step failed.

A failure names the action, the permission and the resource, for example that the role needs s3:ListBucket on your bucket. Pipeline runs skip the role check, so test the connection again whenever you change the Role ARN. A run will not start until a test has passed for the current Role ARN.

Long runs​

KoraBridge renews the role's temporary credentials while a pipeline loads, so the default one hour session works even for runs that last hours. Session duration is an advanced field that takes 900 to 43200 seconds and must not exceed the role's maximum session duration, so raise the role's maximum before you set a longer value.

The form also shows a read-only External ID field in role mode. Copy it into the role's trust policy if you set the role up by hand.

Access key​

Create an access key for an IAM user with write access to the bucket and prefix, then enter the two values. The user needs the same permissions as the role above.

AWS Access Key ID​

The key ID from your IAM user. KoraBridge stores it encrypted.

AWS Secret Access Key​

The secret that pairs with the key ID. It is shown by AWS only once, when you create the key.

Endpoint URL​

Leave blank for AWS S3. Set it only for S3-compatible storage such as MinIO or R2.

Common mistakes​

  • Entering a bucket name without the s3:// prefix.
  • Leaving the sts:ExternalId condition out of the role's trust policy. KoraBridge refuses a role that can be assumed without it.
  • Leaving out s3:GetBucketLocation or s3:ListBucket, which makes the connection test or the first load fail.
  • Using credentials or a role that cannot write files to the bucket or prefix.
  • Setting an endpoint URL for AWS S3. It is only for compatible services like MinIO or R2.