## Permissions & S3 results bucket

URL: https://docs.atlan.com/apps/connectors/database/amazon-athena/how-tos/permissions-and-the-s3-results-bucket

> The complete permission surface an Amazon Athena connection needs - including Lake Formation, KMS, and the S3 results bucket that cause most "test passed, crawl failed" issues.

The complete permission surface an Athena connection needs - including the three that the setup form never asks about (Lake Formation, KMS, and the results bucket) and that cause most "test passed, crawl failed" issues.

## Permission map

| Service | Why Atlan needs it | Key actions | If missing, you see |
|---|---|---|---|
| **Glue** | Read database/table/column definitions | `glue:GetDatabases`, `glue:GetTables`, `glue:GetTable` | `AccessDeniedException … not authorized to perform: glue:GetDatabases` |
| **Athena** | Run metadata queries; list catalogs and workgroups | `athena:StartQueryExecution`, `athena:GetQueryResults`, `athena:GetTableMetadata`, `athena:ListDataCatalogs` | Query-permission errors in the workflow logs |
| **S3 (results bucket)** | Athena writes query results there; Atlan reads them back | `s3:PutObject`, `s3:GetObject`, `s3:ListBucket` on the output location | *Access to the specified S3 resource is denied* |
| **Lake Formation** (if used) | LF adds a second permission layer over Glue - IAM alone isn't enough | LF grants: `DESCRIBE` on databases, `SELECT`/`DESCRIBE` on tables | *Insufficient permissions … Principal does not have any privilege on specified resource* |
| **KMS** (if catalog/buckets encrypted) | Decrypt Glue catalog metadata and S3 results | `kms:Decrypt`, `kms:DescribeKey` on the relevant key | `GlueEncryptionException … not authorized to perform: kms:Decrypt` |
| **Lambda** (external Hive metastore only) | Athena federates to non-Glue catalogs via Lambda | `lambda:InvokeFunction`, `lambda:GetFunction` | Catalog listing fails for the federated catalog |

The base policy JSON (Glue/Athena/S3/ListDataCatalogs/Lambda statements) is in [Set up Amazon Athena](https://docs.atlan.com/llms/connectors/amazon-athena/set-up-amazon-athena/llms.txt). The Lake Formation and KMS rows are additional requirements that apply only when your account uses those features.

:::danger Why "test passed" doesn't mean "done"

The authentication test only proves Atlan can *become* your IAM identity. It does not run a query, read Glue, or touch S3. Four services can still be misconfigured - which is why setups with missing `kms:Decrypt` or missing Lake Formation grants pass every test and then fail mid-crawl.

:::

## S3 results bucket, explained

Athena never returns query results directly. Every query - including Atlan's metadata queries - writes its result file to the **S3 output location** first; the client then downloads it. This has three practical consequences:

- The Atlan identity needs **read and write** on that bucket path - write for Athena to store results as you, read to fetch them.
- If the bucket is **KMS-encrypted**, add `kms:Decrypt` for the bucket's key, or downloads fail even though queries succeed.
- The value in the Atlan form must be a valid S3 URI you control, e.g. `s3://example-corp-athena-results/atlan/`. If your team uses per-workgroup output locations, the workgroup's setting can override the client's - keep the form's workgroup and output location consistent with what your admin configured.

## Pre-flight checks your AWS admin can run

Two one-liners that catch the silent extras before the first crawl:

```

# Is the Glue catalog KMS-encrypted? If "SSE-KMS" appears, Atlan's role needs kms:Decrypt on that key.

aws glue get-data-catalog-encryption-settings --region <region>

# Is Lake Formation in play? If this returns registered resources, LF grants are needed too.

aws lakeformation list-resources --region <region>
```

## Scoping down without breaking the crawler

- Scope Glue/Athena statements to the region and catalog you're cataloging - but grant them on **every database you expect in Atlan**. An explicit *deny* on one database makes the crawler skip it.
- Use Atlan's **include/exclude filters** in the crawler config to match your permission boundary, so the crawler doesn't attempt databases it can't read.

---