## How IAM role delegation works

URL: https://docs.atlan.com/apps/connectors/database/amazon-athena/concepts/how-iam-role-delegation-works

> Learn how Atlan borrows an identity in your AWS account for Amazon Athena, why there are two halves to set up, and the four traffic paths a healthy connection uses.

This page explains how Atlan borrows an identity in your AWS account, why there are two halves to set up, and the four traffic paths a healthy Athena connection uses. No prior AWS knowledge is required.

## Visitor badge

With access keys, you hand Atlan a permanent key to your building. With **role delegation**, you instead leave a **visitor badge** at the front desk: Atlan shows its own company ID, the front desk checks it against the guest list, and issues a badge that *expires after an hour* and only opens the doors you chose.

In AWS terms:

- The **IAM role** you create is the visitor badge - a bundle of permissions with no password of its own.
- The role's **trust policy** is the guest list - it names exactly which outside identity (Atlan's *node instance role*) may pick up the badge.
- The **external ID** is a code word you can add to the guest list - even the right visitor is turned away without it.
- AWS **STS** (Security Token Service) is the front desk - it checks the guest list and issues the one-hour badge.

Two sides must agree, and this is where most setups stall: **your** trust policy must name Atlan's role, and **Atlan's** side must be configured to request *your* role - a manual step Atlan support performs per tenant. Either half missing produces the same error: *authentication failed*.

## Four traffic paths

![Diagram of the four traffic paths between your Atlan tenant and your AWS account: AssumeRole via STS to get the one-hour badge from IAM security and roles, Glue API calls to read the Glue Data Catalog, Athena JDBC metadata queries to the Athena query engine on port 443, and S3 downloads of temporary query results from the results bucket - with Lake Formation / KMS as the governance layer if enabled. The authentication test exercises path 1 only](https://docs.atlan.com/img/apps/connectors/database/amazon-athena/how-tos/athena-iam-role-delegation-traffic-paths.png)

The authentication test exercises path 1 only. A crawl needs all four - which is why "test passed but crawl failed" is the single most common Athena support issue.

1. **AssumeRole (Atlan → STS).** Atlan's node instance role asks STS for temporary credentials for your role. Fails if either half of the two-sided setup is missing, or the external ID doesn't match - error `HEKA-401-00-001`.
2. **Glue Data Catalog (Atlan → Glue).** Athena stores its database/table/column definitions in Glue. Missing `glue:Get*` permissions fail here with `AccessDeniedException`.
3. **Athena queries (Atlan → Athena, port 443).** The crawler runs metadata queries through the Athena JDBC driver. Network blocks (usually PrivateLink misconfiguration) surface here as *Connection timed out* - after authentication already succeeded.
4. **Results download (Atlan → S3).** Athena writes every query result to your **S3 output location** first; Atlan then downloads it. Missing S3 or KMS permissions on that bucket fail here - queries "succeed" but results can't be read.

## Glossary

For definitions of every term used in these guides - IAM, IAM role, trust policy, node instance role, external ID, ARN, STS, Glue Data Catalog, workgroup, S3 output location, VPC interface endpoint, Lake Formation, KMS - see the [Network connectivity glossary](https://docs.atlan.com/llms/governance/administration/network-connectivity-glossary/llms.txt).

## See also

- [Choose how Atlan connects to Amazon Athena](https://docs.atlan.com/llms/connectors/amazon-athena/choose-how-atlan-connects-to-amazon-athena/llms.txt): Pick the right method before configuring anything
- [Connect with IAM role (recommended)](https://docs.atlan.com/llms/connectors/amazon-athena/connect-with-an-iam-role/llms.txt): Apply this knowledge in the recommended setup

---