---
title: AWS IAM Authentication
sidebar_label: AWS IAM Authentication
version: 1
sidebar_position: 15
---

# AWS IAM Authentication for AWS Databases

Superset supports IAM-based authentication for **Amazon Aurora** (PostgreSQL and MySQL) and **Amazon Redshift**. IAM auth eliminates the need for database passwords — Superset generates a short-lived auth token using temporary AWS credentials instead.

Cross-account IAM role assumption via STS `AssumeRole` is supported, allowing a Superset deployment in one AWS account to connect to databases in a different account.

## Prerequisites

- Enable the `AWS_DATABASE_IAM_AUTH` feature flag in `superset_config.py`. IAM authentication is gated behind this flag; if it is disabled, connections using `aws_iam` fail with *"AWS IAM database authentication is not enabled."*
  ```python
  FEATURE_FLAGS = {
      "AWS_DATABASE_IAM_AUTH": True,
  }
  ```
- `boto3` must be installed in your Superset environment:
  ```bash
  pip install boto3
  ```
- The Superset server's IAM role (or static credentials) must have permission to call `sts:AssumeRole` (for cross-account) or the same-account permissions for the target service:
  - **Aurora (RDS)**: `rds-db:connect`
  - **Redshift provisioned**: `redshift:GetClusterCredentials`
  - **Redshift Serverless**: `redshift-serverless:GetCredentials` and `redshift-serverless:GetWorkgroup`
- SSL must be enabled on the Aurora / Redshift endpoint (required for IAM token auth).

## Configuration

IAM authentication is configured via the **encrypted_extra** field of the database connection. Access this field in the **Advanced** → **Security** section of the database connection form, under **Secure Extra**.

### Aurora PostgreSQL or Aurora MySQL

```json
{
  "aws_iam": {
    "enabled": true,
    "role_arn": "arn:aws:iam::222222222222:role/SupersetDatabaseAccess",
    "external_id": "superset-prod-12345",
    "region": "us-east-1",
    "db_username": "superset_iam_user",
    "session_duration": 3600
  }
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `enabled` | Yes | Set to `true` to activate IAM auth |
| `role_arn` | No | ARN of the cross-account IAM role to assume via STS. Omit for same-account auth |
| `external_id` | No | External ID for the STS `AssumeRole` call, if required by the target role's trust policy |
| `region` | Yes | AWS region of the database cluster |
| `db_username` | Yes | The database username associated with the IAM identity |
| `session_duration` | No | STS session duration in seconds (default: `3600`) |

### Redshift (Serverless)

```json
{
  "aws_iam": {
    "enabled": true,
    "role_arn": "arn:aws:iam::222222222222:role/SupersetRedshiftAccess",
    "region": "us-east-1",
    "workgroup_name": "my-workgroup",
    "db_name": "dev"
  }
}
```

### Redshift (Provisioned Cluster)

```json
{
  "aws_iam": {
    "enabled": true,
    "role_arn": "arn:aws:iam::222222222222:role/SupersetRedshiftAccess",
    "region": "us-east-1",
    "cluster_identifier": "my-cluster",
    "db_username": "superset_iam_user",
    "db_name": "dev"
  }
}
```

## Cross-Account IAM Setup

To connect to a database in Account B from a Superset deployment in Account A:

**1. In Account B — create a database-access role:**

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["rds-db:connect"],
      "Resource": "arn:aws:rds-db:us-east-1:222222222222:dbuser/db-XXXXXXXXXXXX/superset_iam_user"
    }
  ]
}
```

**Trust policy** (allows Account A's Superset role to assume it):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111111111111:role/SupersetInstanceRole"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "superset-prod-12345"
        }
      }
    }
  ]
}
```

**2. In Account A — grant Superset's role permission to assume the Account B role:**

```json
{
  "Effect": "Allow",
  "Action": "sts:AssumeRole",
  "Resource": "arn:aws:iam::222222222222:role/SupersetDatabaseAccess"
}
```

**3. Configure the database connection in Superset** using the `role_arn` and `external_id` from the trust policy (as shown in the configuration example above).

## Credential Caching

STS credentials are cached in memory keyed by `(role_arn, region, external_id)` with a 10-minute TTL. This reduces the number of STS API calls when multiple queries are executed with the same connection. Tokens are refreshed automatically before expiry.