## Connect with IAM role (recommended)

URL: https://docs.atlan.com/apps/connectors/database/amazon-athena/how-tos/connect-with-an-iam-role

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

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.

:::note New to IAM roles?

Read [How IAM role delegation works](https://docs.atlan.com/llms/connectors/amazon-athena/how-iam-role-delegation-works/llms.txt) 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](https://docs.atlan.com/llms/connectors/amazon-athena/permissions-and-the-s3-results-bucket/llms.txt).

## 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](https://docs.atlan.com/support/submit-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.

:::tip 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](https://docs.atlan.com/llms/connectors/amazon-athena/permissions-and-the-s3-results-bucket/llms.txt) and in [Set up Amazon Athena](https://docs.atlan.com/llms/connectors/amazon-athena/set-up-amazon-athena/llms.txt)).

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

```json
{
 "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>" }
 }
 }]
}
```

:::danger 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

:::caution 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](https://docs.atlan.com/llms/connectors/amazon-athena/set-up-a-private-network-link-to-amazon-athena/llms.txt))
 - **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](https://docs.atlan.com/llms/connectors/amazon-athena/troubleshooting-athena-connectivity/llms.txt). Remember: the auth test only proves the STS handshake - crawl failures after a passing test are usually [permissions](https://docs.atlan.com/llms/connectors/amazon-athena/permissions-and-the-s3-results-bucket/llms.txt), not authentication.

## Next steps

[Crawl Amazon Athena](https://docs.atlan.com/llms/connectors/amazon-athena/crawl-amazon-athena/llms.txt): Configure and run the crawler to extract metadata from Athena

---