Skip to main content

How cross-account access works

TL;DR

Learn how Atlan reads Amazon S3 - IAM roles, trust policies, External IDs, and the four AWS doors every crawl must pass through.

Connect

This page explains IAM roles, trust policies, and the four AWS "doors" a crawl must pass through. No prior AWS knowledge is required.

Visitor badge​

Your S3 buckets live in your AWS account; Atlan runs in its own AWS account. AWS accounts are like separate office buildings - nobody from one building can enter another without arrangements.

A cross-account IAM role is a visitor badge you leave at your front desk:

  • The badge's trust policy is the guest list - it names exactly who may pick the badge up. You put Atlan's identity (its "Node Instance Role" - see Atlan identity details) on that list.
  • The badge's permission policy says what the visitor may do once inside - which buckets they may list and read.
  • An External ID is a passphrase the visitor must also say at the desk. It stops someone from tricking Atlan into picking up your badge on behalf of a different customer (AWS calls this the "confused deputy" problem). Strongly recommended for production.

When Atlan connects, it calls AWS's STS "AssumeRole" service - literally "let me borrow that badge". AWS hands back temporary credentials valid for about an hour. No permanent secret is ever created, and every borrow is logged in your CloudTrail.

Why your logs show a stranger called "atlan-test-credential-helper"

When you click Test connection, the borrowed badge is used under the session name atlan-test-credential-helper. That string appearing in an error or in CloudTrail is normal - it's Atlan's test process, not an unknown user.

Four doors every crawl passes through​

Diagram of the cross-account AWS access control flow: from Atlan's AWS account (which runs your tenant), the crawler workflows and Node Instance Role - Atlan's identity, the visitor - call STS AssumeRole to "borrow the badge" (+ External ID), then make S3 API calls with temporary credentials (~1 hour, TLS) into your AWS account, passing four doors: Door 1, the IAM role (the badge) whose trust policy checks whether Atlan is on the guest list and the External ID matches; Door 2, the permission policy deciding whether the badge may list buckets and read objects and their tags; Door 3, the bucket policy - the bucket's own rulebook, where an explicit Deny wins; and Door 4, the KMS key policy (encrypted buckets only) deciding whether the badge may use the decryption key

A crawl only works when all four doors open. Each door produces a different "Access Denied" - Troubleshooting S3 connectivity maps error text to door:

  1. The trust policy (Door 1). Fails as AccessDenied when calling the AssumeRole operation. Atlan isn't on the guest list - or the guest list is fine but Atlan's side hasn't been configured to try (see the two-sided handshake below).
  2. The permission policy (Door 2). Fails as not authorized to perform: s3:Something. One missing action out of the ten the crawler uses.
  3. The bucket policy (Door 3). A bucket can carry its own rulebook that overrides everything - one explicit Deny statement beats any number of Allows.
  4. The KMS key policy (Door 4). Encrypted objects need the key's permission too. Symptom: listing works, reading object details fails.
The handshake is two-sided - and Atlan's side needs a support ticket today

Your trust policy lets Atlan in, but Atlan's own account must also be configured to reach out to your specific role (its identity must be granted sts:AssumeRole on your role's ARN). Today that Atlan-side step is done by support when you share your role ARN on a ticket. If you skip it, nothing errors loudly - the borrow silently fails and the connection test reports a confusing AuthorizationHeaderMalformed error. This one gap drives more support requests than any AWS misconfiguration.

Glossary​

For definitions of every term used in these guides - IAM, ARN, IAM role, trust policy, permission policy, bucket policy, explicit Deny, STS/AssumeRole, External ID, node instance role, atlan-test-credential-helper, SSE-KMS, prefix, PermanentRedirect - see the Network connectivity glossary.

See also​