Connect with IAM role (recommended)

✦TL;DR

Set up cross-account IAM role delegation so Atlan connects to Amazon Athena with temporary credentials and no stored secret.

||

|Connect

Set up cross-account role delegation so Atlan connects to Athena with temporary credentials and no stored secret. Four phases - including the Atlan-side allowlist handshake that is the most commonly missed step.

New to IAM roles?

Read How IAM role delegation works first (5 minutes). It explains every term below - trust policy, external ID, node instance role, STS - and why this setup has two halves.

Prerequisites

• Someone with IAM administrator access in the AWS account that hosts Athena and the Glue Data Catalog.
• Your Athena region and the S3 output location your queries use (an S3 path like s3://example-corp-athena-results/ - find it in the Athena console under Settings, or ask your AWS admin).
• Your Atlan tenant URL (e.g. tenant.atlan.com) for the support ticket.
• If your organization uses Lake Formation or KMS-encrypted Glue catalogs: the admin for those too - see Permissions & the S3 results bucket.

Four phases at glance

Phase	What happens	Owner	Typical time
1. Get Atlan's identity	Ask support for your tenant's node instance role ARN	Atlan User + Atlan support	1 business day
2. Build the role	Create the IAM policy, role, and trust policy in your account	Your AWS admin	30–45 minutes
3. Allowlist	Atlan attaches a policy allowing its role to assume yours - the critical handshake	Atlan support	1–2 business days
4. Connect & verify	Enter the role ARN + external ID in Atlan and test	Atlan User	30 minutes

Phase 1 - Get Atlan's identity

Owner: Atlan User + Atlan support

Raise a support request from within Atlan: "We're setting up Amazon Athena with IAM role delegation on tenant tenant.atlan.com. Please share the node instance role ARN for this tenant."

Support replies with an ARN like arn:aws:iam::999999999999:role/example-tenant-nodeinstance-role (illustrative). This is the identity your trust policy will name in Phase 2.

Start the connection draft now

In Atlan, open New workflow → Athena Assets and go as far as the credential form. Choose IAM Role and click Generate next to External ID. Copy the generated external ID - your AWS admin needs it in Phase 2, and it must match what's saved in this form character-for-character.

Phase 2 - Build role in your account

Owner: Your AWS admin

Step 1. Create an IAM policy with the permissions Atlan needs (Glue + Athena + S3 results bucket - full JSON in Permissions & the S3 results bucket and in Set up Amazon Athena).

Step 2. Create an IAM role (type: Another AWS account), attach the policy, and set this trust policy:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::999999999999:role/example-tenant-nodeinstance-role" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "<external-id-generated-in-Atlan>" }
    }
  }]
}

The two silent killers

External ID mismatch - the value in this trust policy and the value saved in the Atlan connection form must be identical. If your admin generates their own external ID instead of using the one from the Atlan form (or vice versa), authentication fails with HEKA-401-00-001 and no further hint.

Retyped ARNs - copy-paste the node instance role ARN exactly. A wrong account number in the principal makes AWS reject the trust policy or the handshake fail later.

Step 3. Note your new role's ARN, e.g. arn:aws:iam::123456789012:role/atlan-athena-crawler (illustrative).

Phase 3 - Atlan allowlists your role

Owner: Atlan support

Atlan's node instance role must also be permitted on Atlan's side to assume your specific role. This is a manual step by Atlan - it does not happen automatically when you create the role.

Reply on your Phase 1 ticket with your role ARN: "Our role is created: arn:aws:iam::123456789012:role/atlan-athena-crawler. Please allowlist it for tenant tenant.atlan.com and confirm when done."

The lifecycle:

1. Role created - your AWS admin finished Phase 2
2. Awaiting allowlist - test authentication fails in this state; that's expected, not an error in your setup
3. Allowlisted - support confirms on the ticket; the STS handshake can now succeed
4. Ready - proceed to Phase 4

Per tenant, every time

Repeat this handshake for each Atlan tenant. A role allowlisted on your dev tenant will fail with [AAF-HDL-001] Authentication failed: invalid credentials on prod until prod's allowlist is in place. Mention all tenants you plan to connect in one ticket.

Phase 4 - Connect and verify

Owner: Atlan User

1. Open your draft connection (New workflow → Athena Assets).
2. Fill the credential form:
   • Host: athena.<region>.amazonaws.com (or the PrivateLink host - see Set up a private network link to Amazon Athena)
   • Authentication: IAM Role → paste your role ARN; confirm the external ID is the one your admin put in the trust policy
   • S3 Output Location: your results bucket path, e.g. s3://example-corp-athena-results/
   • Workgroup: leave as primary unless your admin says otherwise
3. Click Test Authentication.

Success checklist

• Test Authentication passes in the Atlan UI
• Preflight checks pass when you configure the crawler
• A crawl scoped to one small database completes
• A full crawl completes - the first real exercise of Glue, Athena JDBC, and S3 results paths together

All four green? Done. If any step fails, see Troubleshooting Athena connectivity. Remember: the auth test only proves the STS handshake - crawl failures after a passing test are usually permissions, not authentication.

Next steps

Crawl Amazon Athena: Configure and run the crawler to extract metadata from Athena