You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by be...@apache.org on 2026/01/29 16:26:56 UTC
(superset) 03/03: Update docs
This is an automated email from the ASF dual-hosted git repository.
beto pushed a commit to branch aws-iam
in repository https://gitbox.apache.org/repos/asf/superset.git
commit d6afe5b627733b17e1300f7669b38e41e990c27b
Author: Beto Dealmeida <ro...@dealmeida.net>
AuthorDate: Mon Jan 26 14:32:45 2026 -0500
Update docs
---
docs/docs/configuration/databases.mdx | 220 ++++++++++++++++++++++++++++++++++
1 file changed, 220 insertions(+)
diff --git a/docs/docs/configuration/databases.mdx b/docs/docs/configuration/databases.mdx
index 98cd9c58a22..932065934e0 100644
--- a/docs/docs/configuration/databases.mdx
+++ b/docs/docs/configuration/databases.mdx
@@ -40,6 +40,8 @@ are compatible with Superset.
| [AWS Athena](/docs/configuration/databases#aws-athena) | `pip install pyathena[pandas]` , `pip install PyAthenaJDBC` | `awsathena+rest://{access_key_id}:{access_key}@athena.{region}.amazonaws.com/{schema}?s3_staging_dir={s3_staging_dir}&...` |
| [AWS DynamoDB](/docs/configuration/databases#aws-dynamodb) | `pip install pydynamodb` | `dynamodb://{access_key_id}:{secret_access_key}@dynamodb.{region_name}.amazonaws.com?connector=superset` |
| [AWS Redshift](/docs/configuration/databases#aws-redshift) | `pip install sqlalchemy-redshift` | `redshift+psycopg2://<userName>:<DBPassword>@<AWS End Point>:5439/<Database Name>` |
+| [AWS Aurora PostgreSQL](/docs/configuration/databases#aws-aurora-postgresql-and-mysql) | `pip install psycopg2` | `postgresql://<userName>:<DBPassword>@<cluster-endpoint>:5432/<Database Name>` |
+| [AWS Aurora MySQL](/docs/configuration/databases#aws-aurora-postgresql-and-mysql) | `pip install mysqlclient` | `mysql://<userName>:<DBPassword>@<cluster-endpoint>:3306/<Database Name>` |
| [Apache Doris](/docs/configuration/databases#apache-doris) | `pip install pydoris` | `doris://<User>:<Password>@<Host>:<Port>/<Catalog>.<Database>` |
| [Apache Drill](/docs/configuration/databases#apache-drill) | `pip install sqlalchemy-drill` | `drill+sadrill://<username>:<password>@<host>:<port>/<storage_plugin>`, often useful: `?use_ssl=True/False` |
| [Apache Druid](/docs/configuration/databases#apache-druid) | `pip install pydruid` | `druid://<User>:<password>@<Host>:<Port-default-9088>/druid/v2/sql` |
@@ -333,6 +335,224 @@ You have to define the following arguments in Superset's redshift database conne
{"connect_args":{"iam":true,"is_serverless":true,"serverless_acct_id":"<aws account number>","serverless_work_group":"<redshift work group>","database":"<database>","user":"IAMR:<superset iam role name>"}}
```
+##### Cross-Account IAM Authentication
+
+Superset also supports cross-account IAM authentication for both Redshift Serverless and provisioned clusters. This approach uses STS AssumeRole to obtain temporary credentials and is ideal for multi-account AWS architectures.
+
+**Prerequisites:**
+- Redshift cluster or Serverless workgroup with IAM authentication enabled
+- IAM role in the data account with permissions to get Redshift credentials
+- Superset running on AWS infrastructure with an IAM role that can assume the data account role
+
+**Configuration for Redshift Serverless:**
+
+1. Set the SQLAlchemy URI:
+ ```
+ redshift+psycopg2://{username}@{workgroup}.{account_id}.{region}.redshift-serverless.amazonaws.com:5439/{database}
+ ```
+
+2. Add IAM configuration in **Secure Extra** (ADVANCED → Security → Secure Extra):
+ ```json
+ {
+ "aws_iam": {
+ "enabled": true,
+ "role_arn": "arn:aws:iam::DATA_ACCOUNT_ID:role/SupersetRedshiftAccess",
+ "external_id": "your-unique-external-id",
+ "region": "us-east-1",
+ "workgroup_name": "my-workgroup",
+ "db_name": "dev"
+ }
+ }
+ ```
+
+**Configuration for Provisioned Redshift Clusters:**
+
+1. Set the SQLAlchemy URI:
+ ```
+ redshift+psycopg2://{username}@{cluster-identifier}.{unique-id}.{region}.redshift.amazonaws.com:5439/{database}
+ ```
+
+2. Add IAM configuration in **Secure Extra** (ADVANCED → Security → Secure Extra):
+ ```json
+ {
+ "aws_iam": {
+ "enabled": true,
+ "role_arn": "arn:aws:iam::DATA_ACCOUNT_ID:role/SupersetRedshiftAccess",
+ "external_id": "your-unique-external-id",
+ "region": "us-east-1",
+ "cluster_identifier": "my-redshift-cluster",
+ "db_username": "superset_user",
+ "db_name": "analytics"
+ }
+ }
+ ```
+
+**Configuration Fields:**
+
+| Field | Serverless | Provisioned | Description |
+|-------|------------|-------------|-------------|
+| `enabled` | Required | Required | Set to `true` to enable IAM authentication |
+| `role_arn` | Required | Required | ARN of the IAM role to assume |
+| `region` | Required | Required | AWS region |
+| `db_name` | Required | Required | Database name |
+| `workgroup_name` | Required | - | Redshift Serverless workgroup name |
+| `cluster_identifier` | - | Required | Provisioned cluster identifier |
+| `db_username` | - | Required | Database username for provisioned clusters |
+| `external_id` | Optional | Optional | External ID for cross-account security |
+| `session_duration` | Optional | Optional | STS session duration in seconds (default: 3600) |
+
+**Required IAM Permissions:**
+
+For Redshift Serverless:
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "redshift-serverless:GetCredentials",
+ "redshift-serverless:GetWorkgroup"
+ ],
+ "Resource": "arn:aws:redshift-serverless:REGION:ACCOUNT_ID:workgroup/WORKGROUP_ID"
+ }
+ ]
+}
+```
+
+For provisioned Redshift clusters:
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": "redshift:GetClusterCredentials",
+ "Resource": [
+ "arn:aws:redshift:REGION:ACCOUNT_ID:dbuser:CLUSTER_NAME/superset_user",
+ "arn:aws:redshift:REGION:ACCOUNT_ID:dbname:CLUSTER_NAME/analytics"
+ ]
+ }
+ ]
+}
+```
+
+:::resources
+- [AWS Docs: IAM Authentication for Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-user-credentials.html)
+- [AWS Docs: Redshift Serverless IAM](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-iam.html)
+:::
+
+#### AWS Aurora (PostgreSQL and MySQL)
+
+Amazon Aurora is a MySQL and PostgreSQL-compatible relational database built for the cloud. Superset supports connecting to Aurora using standard PostgreSQL or MySQL drivers, with optional IAM authentication for enhanced security.
+
+##### Standard Connection (Username/Password)
+
+For Aurora PostgreSQL, use the PostgreSQL driver:
+
+```
+postgresql://{username}:{password}@{cluster-endpoint}:{port}/{database}
+```
+
+For Aurora MySQL, use the MySQL driver:
+
+```
+mysql://{username}:{password}@{cluster-endpoint}:{port}/{database}
+```
+
+##### Cross-Account IAM Authentication
+
+Superset supports AWS cross-account IAM authentication for Aurora databases. This eliminates the need to store database passwords and provides automatic credential rotation.
+
+**Prerequisites:**
+- Aurora cluster with [IAM database authentication enabled](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.Enabling.html)
+- Database user configured for IAM authentication
+- IAM role with `rds-db:connect` permission
+- Superset running on AWS infrastructure (EC2, ECS, or EKS) with an IAM role that can assume the database access role
+
+**Configuration:**
+
+1. Set the SQLAlchemy URI with the cluster endpoint (password will be replaced by IAM token):
+
+ For Aurora PostgreSQL:
+ ```
+ postgresql://{db_username}@{cluster-endpoint}:{port}/{database}
+ ```
+
+ For Aurora MySQL:
+ ```
+ mysql://{db_username}@{cluster-endpoint}:{port}/{database}
+ ```
+
+2. Add the IAM configuration in the **Secure Extra** field (ADVANCED → Security → Secure Extra):
+
+ ```json
+ {
+ "aws_iam": {
+ "enabled": true,
+ "role_arn": "arn:aws:iam::DATA_ACCOUNT_ID:role/SupersetDatabaseAccess",
+ "external_id": "your-unique-external-id",
+ "region": "us-east-1",
+ "db_username": "superset_iam_user"
+ }
+ }
+ ```
+
+**Configuration Fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `enabled` | Yes | Set to `true` to enable IAM authentication |
+| `role_arn` | Yes | ARN of the IAM role to assume for database access |
+| `region` | Yes | AWS region where the Aurora cluster is located |
+| `db_username` | Yes | Database username configured for IAM authentication |
+| `external_id` | No | External ID for cross-account role assumption (recommended for security) |
+| `session_duration` | No | STS session duration in seconds (default: 3600) |
+
+**Required IAM Permissions:**
+
+The IAM role specified in `role_arn` needs the following permission:
+
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": "rds-db:connect",
+ "Resource": "arn:aws:rds-db:REGION:ACCOUNT_ID:dbuser:CLUSTER_RESOURCE_ID/superset_iam_user"
+ }
+ ]
+}
+```
+
+For cross-account access, the role also needs a trust policy allowing Superset's IAM role to assume it:
+
+```json
+{
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Principal": {
+ "AWS": "arn:aws:iam::SUPERSET_ACCOUNT_ID:role/SupersetApplicationRole"
+ },
+ "Action": "sts:AssumeRole",
+ "Condition": {
+ "StringEquals": {
+ "sts:ExternalId": "your-unique-external-id"
+ }
+ }
+ }
+ ]
+}
+```
+
+:::resources
+- [AWS Docs: IAM Database Authentication for Aurora](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.IAMDBAuth.html)
+- [AWS Docs: Cross-Account IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)
+:::
+
#### ClickHouse
To use ClickHouse with Superset, you will need to install the `clickhouse-connect` Python library: