How Superset AWS IAM authentication replaces stored database passwords
If your Superset team holds database passwords for Aurora or Redshift and wants to remove them, Superset can generate short-lived tokens from temporary AWS credentials for Aurora PostgreSQL, Aurora MySQL and Redshift instead of storing a static password in the connection. The feature is switched on with the AWS_DATABASE_IAM_AUTH feature flag, uses boto3 to request the token, and is configured per database connection in the connection's encrypted extra field, so you can move one database at a time rather than changing every connection in the same step.
Three requirements shape the plan. The feature needs boto3 installed in the Superset image or virtual environment, so the image build and its dependency pinning become part of the change. The database endpoint must accept SSL, so you need to confirm that the Aurora cluster or Redshift workgroup enforces or supports encrypted connections and that the client trusts the certificate chain. The credentials Superset uses come from the AWS environment it runs in, which means the IAM role attached to the Superset host or pod, or a role it assumes, must hold permission to generate database connect tokens for the specific database user. Confirm the exact IAM actions and the mapping between the IAM identity and the database user with your own AWS and database administrators, against current AWS documentation, before you write policies.
Treat the switch as a change to access control, not only to configuration. Each connection that moves to IAM authentication still needs a database user with the minimum privileges the dashboards require, and the token lifetime, the role chain and the audit trail in CloudTrail and the database logs should be checked in a staging environment first. Read the Apache Superset AWS IAM authentication documentation alongside your own tests, because the feature flag name and the encrypted extra keys are version-dependent and should be confirmed against the Superset release you run.
What you need before enabling IAM authentication
IAM authentication replaces a stored database password with a short-lived token, so it touches the Superset image, the AWS account and the database engine at once. The cards below cover the pieces that must line up before you change any connection, and each one names the check that prevents a failed rollout.
A Superset version with the feature
Confirm that the Superset release you deploy includes the AWS IAM authentication option and read the release notes for the version line you run. The supported release range moves quickly: Superset 6.0.0 was published on December 18, 2025, 6.1.0 on May 13, 2026, and a 7.0.0 release candidate appeared on October 16, 2026. Test the feature on the exact version that will reach production, not on the newest pre-release.
Feature flag enabled
IAM authentication is gated behind the AWS_DATABASE_IAM_AUTH feature flag. Set it in the Superset configuration file that your web and worker containers both load, then confirm it is active in the running application, not only in a local file. Record who owns the flag change, because enabling it changes how every AWS connection in the instance authenticates.
boto3 in the Superset image
Superset uses boto3 to request tokens from AWS, so the library must be present in the image that runs the web server, the Celery workers and any scheduled jobs. Add it to the image build rather than installing it at container start, and pin the version through your normal dependency review. Verify it inside each running container, since a worker missing the library fails only when a query or report runs.
Temporary AWS credentials source
Tokens are generated from temporary credentials, so decide how the Superset containers obtain them: an IAM role attached to the compute platform, such as an instance profile or pod identity, is generally preferable to long-lived access keys. Confirm that the role can call the database connect permission for each target cluster or workgroup. Ask your AWS administrator who approves changes to that role's trust and permission policies.
IAM authentication enabled on the database
Aurora and Redshift each need their own IAM database authentication setting and a database user mapped to the IAM identity. The exact steps differ between Aurora PostgreSQL, Aurora MySQL and Redshift, so confirm the mapping and the grant model in the vendor documentation for your engine version. Plan who creates these database users and how they are reviewed, because a mapping error here is the most common reason a connection fails.
SSL-capable endpoints
The connection must use SSL on the endpoint, so confirm that each cluster or workgroup accepts encrypted connections and that your network path does not terminate TLS in between. Decide how the CA certificate bundle reaches the Superset containers and who renews it. A connection that negotiates no SSL will be rejected once IAM authentication is required, so test this in staging before changing production connections.
Configuring the feature flag, connection and credentials in order
This sequence moves a Superset instance from stored database passwords to short-lived IAM tokens for Aurora and Redshift. Each step ends with a check so the team knows the previous change works before the next one starts.
Enable the AWS IAM feature flag
The platform team adds AWS_DATABASE_IAM_AUTH to the feature flags in superset_config.py and restarts the web and worker processes so the setting loads everywhere. Confirm the flag is active by checking the Superset feature flag list or the configuration loaded in each container. Do this in staging first, because the flag changes how connections authenticate and should be tested like any other configuration change. The step is done when every Superset process reports the same flag state.
Install and pin boto3 in the image
The image build adds boto3 as a dependency, pinned to a specific version that your team has tested, and the image is rebuilt so the web, worker and beat containers share it. Pinning matters because the token generation path depends on the library, and an unpinned install can change between builds. Confirm inside a running container that the module imports and reports the pinned version. The step is done when the same image tag passes that import check on every process type.
Grant the runtime role token generation permissions
The AWS team attaches an IAM policy to the role that Superset runs under, such as an EC2 instance profile, a container task role or an IRSA role, that allows it to generate database auth tokens for the specific database user and cluster or Redshift resource. Scope the resource ARNs narrowly, and confirm the exact action names and resource formats in the AWS IAM documentation for each engine before you write the policy. Verify the permission from the Superset host using the AWS CLI with that role's credentials. The step is done when the role can obtain a token for the target endpoint and cannot obtain one for other resources.
Create the database user for IAM login
The database administrator creates or configures a database user that authenticates with IAM instead of a password, following the engine's documented IAM setup for Aurora PostgreSQL, Aurora MySQL or Redshift. The user should hold only the privileges the Superset analytics role needs, because the token grants the same access as a password would. Confirm the user exists and that a login attempt with a generated token succeeds from the Superset host. The step is done when the token-based login works and a password login for that user is no longer possible.
Create the connection with SSL required
An administrator creates the database connection in Superset with the Aurora or Redshift endpoint, and enables SSL on the connection because the IAM method requires an SSL endpoint. Leave the password field empty so no static credential is stored in the metadata database. Confirm the SSL settings match what the database server expects, since a mismatch fails at connection time. The step is done when the connection record saves without a stored password and the connection editor shows SSL as enabled.
Place the IAM settings in the encrypted extra field
The administrator adds the IAM configuration to the connection's encrypted extra field, which is where Superset reads the auth method and related settings, and the field is stored encrypted in the metadata database. Confirm the exact keys and their names against the Superset AWS IAM documentation for your Superset version, because a misspelled key falls back to a failed or password-based login. Check that the stored value is encrypted and that the key is not exposed in the connection's displayed configuration. The step is done when the extra field contains the IAM settings and the connection form no longer shows any password value.
Test the connection and run a known query
Use the Test Connection action, then run a query against a table with a known row count, such as a small reference table your team has already counted, and compare the result with the source. Repeat the query from a second Superset process to confirm tokens are generated outside the first container. Review the database logs or CloudTrail activity to confirm logins are arriving under the expected IAM user. The step is done when the connection test passes, the query returns the expected rows and the login is traceable to the Superset runtime role.
Choosing how Superset obtains AWS credentials
When Superset runs on EC2 or on EKS, the cleanest pattern is to attach an IAM role to the compute resource so the process receives temporary credentials without any stored key. On EKS, the same idea is usually implemented through a pod-level role mapping rather than node-wide permissions, so the Superset pods are the only workload that can request database tokens. The platform team usually owns the instance profile or pod role, while the database team owns the database user mapping and the permission to connect with IAM authentication.
- Role scope: The role should allow only the database connect action for the specific Aurora or Redshift resources Superset needs, not broad database administration.
- Database user mapping: Confirm that a database user exists for IAM authentication and that its privileges match the analytics access you intend.
- Node sharing: On shared EC2 hosts or EKS nodes, confirm no other workload inherits the same role.
- Rotation: Temporary credentials refresh automatically, so there is no key to rotate by hand, but you should verify refresh works after a restart.
- Audit trail: Check that database connection events can be traced back to the role in CloudTrail and database logs.
Before relying on this path, check that the role, the database user and the network path to the endpoint all match what the Superset Helm chart or container configuration actually runs as.
When Superset runs outside AWS, for example in a data center or another cloud, it cannot receive an instance role, so it needs some way to obtain temporary AWS credentials. The usual options are federation from the external identity system into AWS, or a dedicated IAM user with an access key. The access key path is the one that creates long-lived secrets, and it moves the risk from the database password to an AWS credential that can request tokens for the database. Who owns the trust relationship depends on the path: the cloud security team usually owns the federation trust, while an access key is often created by whoever set up the service account.
- Key lifetime: A long-lived access key is a standing credential, so it needs an owner, a rotation schedule and a revocation procedure.
- Storage: Confirm where the key is stored, who can read it and whether it lands in the encrypted extra field, logs or container images.
- Permissions: Limit the IAM user to connect actions for the required database resources only.
- Federation option: Ask whether your identity provider can federate into AWS so Superset receives short-lived credentials instead.
- Exit plan: Document how the key is revoked during an incident and how Superset behaves afterward.
Check with your security team whether an access key is acceptable under your own policies before accepting this path, because it reintroduces a secret that the IAM method is designed to avoid.
When the database lives in a different AWS account from the one running Superset, the usual pattern is for Superset to assume a role in the database account. The database account owner writes the trust policy that names the Superset principal allowed to assume the role, and the role's permissions define what it may do. The Superset side needs permission to call the assume-role action on that target role. Both sides must agree on the role ARN, the external identifier if one is used and the session duration, so responsibility for the trust policy is shared but must be documented on both sides.
- Trust policy owner: The database account team writes and reviews the trust policy, and should restrict the principal to the Superset role only.
- Source permission: The Superset account must grant its role permission to assume exactly the target role, nothing wider.
- Confused deputy: Ask whether an external ID condition is required for your setup and who holds it.
- Session settings: Confirm the session duration suits your refresh behavior and that sessions can be revoked.
- Logging: Confirm that assume-role events appear in CloudTrail in both accounts.
Before go-live, test the assume-role call from the exact runtime environment Superset uses, because a trust policy that works from an admin workstation can still fail from the pod or instance.
Cross-account role assumption and when it applies
Superset may run in a different AWS account from the Aurora or Redshift cluster it queries. In that case, the IAM token request has to cross an account boundary, and the trust and role design decides whether it works. The cards below cover when this pattern applies and what to confirm in each account before configuring Superset.
Deciding whether you need it
Cross-account assumption applies when the Superset host and the database cluster sit in different AWS accounts, for example a shared analytics account that serves databases owned by production or data platform accounts. If Superset and the cluster share an account and the Superset runtime already holds a role that can call the database IAM authentication API, you may not need a second hop. Confirm the account map before you design anything, including where Superset runs and where each Aurora or Redshift endpoint lives.
Trust policy on the target role
The role in the database owner's account must trust the principal that Superset's runtime uses, and its permissions must allow the database connect action for the specific cluster or user. Keep the trust narrow: name the source role and avoid broad principals that let any account identity assume the role. Ask your cloud team to show the trust policy and the resource scope in writing before testing, because a permissive trust is one of the most common reasons this design passes testing and then fails audit.
Role chain from the Superset runtime
Document each hop explicitly. A typical chain starts with the identity attached to the Superset host or container, assumes a role in the database account, and then requests a short-lived token for the database user. Each hop produces temporary credentials that expire, so the chain must still be valid when Superset refreshes its connection. Test the chain with the same runtime Superset uses in production, because a developer laptop session can succeed where the service identity fails.
Session duration and token refresh
Temporary credentials from an assumed role have their own lifetime, and the short-lived database token depends on them. Confirm the maximum session duration allowed on the target role, and check how Superset handles a connection whose underlying credentials have expired. A chain with a short session limit can produce intermittent query failures that look like database faults. Ask your cloud team to confirm the duration limits in each account and to record who owns changes to them.
Account governance and audit trail
A cross-account chain changes who appears in the database logs and in AWS CloudTrail. Confirm that assumed-role sessions are attributable to the Superset service, that the database account can see which role connected, and that your logging retention covers both accounts. Auditors testing database access usually ask who can change the trust policy, so record the approvers for changes in the target account as part of the design.
Checks to run in your accounts
Before configuring the feature flag or the connection, confirm five things with your AWS and database owners: the account and region of each cluster, the principal Superset runs as, the trust and permission policies on the target role, the maximum session duration, and whether the database endpoint enforces SSL. Record the answers in the design document. The Superset AWS IAM documentation covers the connection settings once the account design is agreed.
Mapping Superset connection fields to IAM and database settings
This table maps each part of an IAM-based Superset connection to where it is configured, who owns it and what to verify before go-live. Read it top to bottom as a checklist: the feature flag and boto3 are deployment settings, while the database user, endpoint and SSL settings must agree with what the AWS side and the database actually expect.
| Setting | Where it lives | Owner | What to confirm |
|---|---|---|---|
| Feature flag AWS_DATABASE_IAM_AUTH | Superset configuration file (superset_config.py) on every web and worker container | Platform team | The flag is enabled on all nodes that open database connections, including workers that run async queries and scheduled reports |
| boto3 dependency | Superset image or virtual environment | Platform team | boto3 is installed in the same runtime as Superset and is the version your image build pins |
| Temporary AWS credentials | Instance profile, container role or workload identity used by Superset | Cloud team | The runtime obtains short-lived credentials from the environment and not from a stored access key in Superset |
| IAM-enabled database user | Aurora PostgreSQL, Aurora MySQL or Redshift user and grant configuration | Database administrator | The database user is set up to authenticate with IAM and holds only the privileges the dashboards need |
| Encrypted extra settings | Superset database connection, encrypted extra field | Analytics owner | The IAM-related keys in the encrypted extra field match the engine type and region, and no static password is left in the form |
| Endpoint and port | SQLAlchemy URI in the database connection | Platform team | The host is the cluster or workgroup endpoint for the correct account and the port matches the engine |
| SSL on the endpoint | Connection parameters and the database server configuration | Database administrator | SSL is required on the endpoint and the client trusts the certificate chain the database presents |
| Cross-account role assumption | IAM role trust policy in the target account and role settings in encrypted extra | Cloud team | The role assumed by Superset trusts the source role and grants only the database connect permission it needs |
Security controls for IAM-based database access
Removing stored passwords moves the security boundary from a database secret to the IAM role, the network path and the logs that record each login. The cards below cover the controls that connect those pieces, and what to verify in your environment before Superset connects to Aurora or Redshift with tokens.
Least-privilege token generation policy
Superset's IAM flow generates database tokens from the temporary credentials of the role it runs under, so that role's policy decides which database users and clusters it can authenticate as. Scope the policy to the specific database user ARNs and cluster or endpoint resources Superset needs, and avoid wildcard resources. Confirm the exact IAM actions for your engine in the AWS documentation, since they differ between Aurora and Redshift.
Short token lifetime planning
Generated tokens are short-lived, which limits the value of a stolen token but means every new connection or pool checkout must obtain a fresh one. Check how Superset's connection pooling interacts with token expiry, and test long-running queries, scheduled reports and async jobs that hold connections past the token window. Ask your database team which token lifetime applies to your engine.
SSL enforcement on the endpoint
IAM authentication requires SSL on the database endpoint, so the connection should reject plaintext sessions rather than fall back to them. Configure the SSL mode in the connection's encrypted extra settings, verify the server certificate chain that Superset's host trusts, and confirm the database parameter group forces encrypted connections. Test a deliberately unencrypted attempt to confirm it fails.
Protecting the encrypted extra field
The IAM configuration lives in the connection's encrypted extra field, and that field is only as protected as Superset's secret key and metadata database. Keep the SECRET_KEY out of source control, restrict who can edit database connections, and make sure metadata database backups are encrypted and access-controlled, since they contain the same field. Document how the key is rotated and what happens to stored connections when it changes.
CloudTrail and database login auditing
Token generation calls appear in AWS CloudTrail under the role Superset assumes, but they do not show which Superset user ran which query. Combine CloudTrail events with the database's own connection and audit logs, and decide where Superset's query history is retained. Confirm with your AWS and database teams which log types are enabled, where they are stored and how long they are kept.
Separating metadata and warehouse access
Superset's metadata database holds users, dashboards and connection definitions, and it should not share an identity or grant path with the warehouse. Give the metadata database its own credentials and IAM boundary, and give the warehouse role only the read permissions its datasets need. Review cross-account role assumption paths so that a compromised Superset host cannot reach warehouse accounts it does not need.
Common failures when Superset connects with IAM tokens
This table lists the failure points we see most often when Superset requests IAM tokens for Aurora or Redshift, with the symptom, the likely cause, the fix and the first thing to check. Work down the rows in order, because the feature flag, the boto3 install and the credential source must be right before trust policies and database users are worth examining.
| Failure point | Likely symptom | Likely cause and fix | What to check first |
|---|---|---|---|
| Feature flag not enabled | Connection form shows no IAM option, or the connection falls back to a password prompt | AWS_DATABASE_IAM_AUTH is not set in the Superset configuration. Enable the flag in the config file used by the web server and the workers, then restart both. | Confirm the flag value in the running configuration, not only in the file on your workstation |
| boto3 missing or mismatched in the image | ImportError for boto3 in logs, or token generation fails only in some containers | The image was built without boto3, or the web and worker images were built at different times. Add boto3 to the image build and rebuild all Superset images from the same definition. | Run an import of boto3 inside the web container and inside the worker container and compare versions |
| Credentials not visible to the worker | Dashboards and alerts that run as async queries fail while direct queries succeed | Workers run under a different identity or environment than the web process, so temporary credentials are not present. Provide the same role or environment variables, or the instance profile, to every component that opens database connections. | Compare the identity each component reports, for example with an STS identity call run from each container |
| Role lacks token permission | Access denied during connection, with no problem found in the database user | The Superset execution role cannot call the RDS or Redshift action that generates a database token. Attach a policy that allows the token action on the specific database user and resource ARN. | Simulate the policy for the execution role against the database user ARN |
| SSL not configured on the endpoint | Connection is refused or rejected before authentication completes | IAM token login requires SSL on the endpoint. Enable SSL in the connection's encrypted extra settings and confirm the server certificate is trusted by the Superset container. | Check that SSL is enabled on the cluster or instance and that the certificate bundle is present in the image |
| Database user not mapped for IAM login | Token is accepted by AWS but the database returns a login or permission error | The database user was not created or granted for IAM authentication. Create the user to match the IAM policy and grant only the schemas and tables the dashboards need. | Confirm the database user name in the connection matches the user configured for IAM login |
| Cross-account trust misconfigured | Assume-role call fails with access denied, or the wrong account's resources respond | The trust policy on the target account role does not name the Superset account or role, or the external ID does not match. Correct the trust relationship and the role ARN in the connection settings. | Review the trust policy on the target role and the role ARN and account ID stored in the connection |
Questions teams ask before enabling IAM authentication
How long does enabling AWS IAM authentication in Superset take?
The duration depends on how many connections you are moving off stored passwords, how many AWS accounts and roles are involved, and how much of the surrounding setup already exists. The configuration itself is small: enabling the AWS_DATABASE_IAM_AUTH feature flag, installing boto3 on the web and worker nodes, and adding the connection settings. The time goes into confirming the IAM policies, testing SSL against each endpoint, and running the change through staging. Ask any partner to break the estimate into these phases in the written scope before work starts.
What does it cost, and which parts are one-time or recurring?
The Superset software is licensed under the Apache License 2.0 and has no paid edition, so the cost is labor, infrastructure and ongoing operations. One-time costs include the design of IAM roles, the feature flag rollout, testing and documentation. Recurring costs include running the database and AWS role maintenance, reviewing permissions, and applying Superset upgrades that touch the connection layer. Whoever quotes the work should itemize these components and state which are fixed and which depend on the number of connections and accounts.
Can our own team enable IAM authentication without a partner?
Yes, if your team already operates Superset, understands AWS IAM roles and can test database connections over SSL. The work is mostly configuration and verification rather than new code. The main risks are misconfigured trust policies, tokens that expire mid-query, and missing SSL settings that leave connections unverified. A partner adds the most value when several AWS accounts, cross-account role assumption or audit evidence are part of the requirement. Either way, confirm the steps with your database and cloud owners before changing production.
What do we need from our AWS and database owners?
You need the AWS account owner to create or approve the IAM roles that Superset assumes, and the database owner to create matching database users that authenticate with IAM. Both must agree on which temporary credentials are allowed, which Aurora PostgreSQL, Aurora MySQL or Redshift endpoints are in scope, and how SSL is enforced on each endpoint. Ask them to confirm the role names, account IDs and endpoint hostnames in writing, and to provide a test account for verification before any production connection changes.
Do we keep a password fallback for these connections?
Keep a fallback only if your risk owners accept it in writing and it is limited to a documented break-glass path. Removing stored passwords is the point of IAM authentication, so a retained password should be rotated, stored in a managed secrets store and restricted to a small set of administrators. Record who can use it, when it was last rotated and how its use is logged. Confirm with your security team whether the policy allows exceptions before the migration starts.
How do we test the change before users depend on it?
Test in a staging Superset that points at non-production endpoints with the same feature flag, boto3 version and connection settings as production. Verify that tokens are generated from temporary credentials, that the connection fails without SSL, that cross-account role assumption works, and that queries return expected results under each role. Superset's upgrade guidance also recommends testing in staging first and backing up the metadata database before any change. Keep the test results as evidence for your change record.
Which Superset version should we use when enabling this feature?
Confirm the feature and its configuration against the documentation for the exact Superset version you run, because settings and supported behavior can change between releases. Check the Superset releases page for the version you plan to deploy, and read the upgrade notes for any version change planned alongside this work. Ask your implementation partner to document the tested version in the scope so that future upgrades know which configuration to revalidate.
How DeployOpen scopes and delivers this integration
DeployOpen plans and implements self-hosted Apache Superset inside your own infrastructure, including the AWS IAM authentication path to Aurora and Redshift. The work starts with a written scope that defines which accounts, roles, endpoints and databases are covered before any configuration changes are made.
How we scope
- Inventory each Aurora PostgreSQL, Aurora MySQL and Redshift connection Superset uses today and record its owner and purpose.
- Define the AWS accounts, IAM roles and cross-account trust paths Superset will assume in the written scope.
- Confirm the Superset version, the boto3 version in your image and whether the AWS_DATABASE_IAM_AUTH flag is available to you.
How we build
- Enable the feature flag in a staging Superset and configure one connection's encrypted extra settings with a test IAM role.
- Verify that SSL is required on each endpoint and that connections fail when TLS is not negotiated.
- Remove stored database passwords from staging connections only after token-based logins pass the agreed test cases.
How we hand over
- Deliver a written configuration record covering the feature flag, role trust policies, encrypted extra keys and SSL settings.
- Document the rollback steps, including how to restore password-based connections if token generation fails in production.
- Walk your platform and database teams through the runbook for rotating roles and reviewing connection changes.
How we support
- Available as a retainer that covers Superset upgrades, boto3 updates and periodic review of IAM role permissions.
- Re-test token-based connections after each Superset upgrade, since configuration behavior should be checked against UPDATING.md notes.
- Ongoing support is available as a retainer, with scope and response expectations agreed in writing before work begins.
