Skip to main content

aws-iam

title: AWS IAM Authentication sidebar_label: AWS IAM Authentication 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." 
    FEATURE_FLAGS = {
        "AWS_DATABASE_IAM_AUTH": True,
    }
  • boto3 must be installed in your Superset environment: 
    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​

{
  "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
  }
}
FieldRequiredDescription
enabledYesSet to true to activate IAM auth
role_arnNoARN of the cross-account IAM role to assume via STS. Omit for same-account auth
external_idNoExternal ID for the STS AssumeRole call, if required by the target role's trust policy
regionYesAWS region of the database cluster
db_usernameYesThe database username associated with the IAM identity
session_durationNoSTS session duration in seconds (default: 3600)

Redshift (Serverless)​

{
  "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)​

{
  "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:

{
  "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):

{
  "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:

{
  "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.