Why the Apache Superset SECRET_KEY needs a rotation plan
A production Superset will not start until you set a user-specified SECRET_KEY, a requirement that took effect in version 2.1.0. Because the key is mandatory, teams often set it once during installation, copy the same value into staging and production, or paste it into a new container image and never revisit it. The key is a long-lived secret that Superset depends on, so each of those habits creates a question you will need to answer during an incident: which environments share this key, and who has seen it? Before you touch configuration, list every environment, image and deployment template that carries the current value.
At a high level, the SECRET_KEY is the secret Superset uses to protect data it hands to clients and to keep its own stored values intact. The configuration documentation ties it to rotation: Superset supports changing the key by setting PREVIOUS_SECRET_KEY alongside the new value and re-encrypting stored data, so you do not have to lose existing encrypted content. That mechanism only helps if someone owns the procedure. Confirm in the configuration documentation which settings your installed version reads, and confirm which stored values must be re-encrypted in your own metadata database before you plan the change.
Plan a rotation for four situations: a scheduled interval set by your security policy, a change in the staff who had access to the key, a suspected leak, and any time an environment is cloned from another. Cloning is the one teams overlook. A copy of production that keeps the production key gives everyone with access to that copy the ability to affect production sessions and encrypted data, and it is often the way a key ends up in a developer's laptop or a test pipeline. Treat each clone as a reason to generate a new key for that environment. The rotation itself is a change to a live system that holds your metadata, so it needs an owner, a backup of the metadata database taken before the change, and a rollback path. Ask whoever runs your Superset to state where the key is stored today, which secrets manager or environment variable holds it, and who can read it. Those answers decide how much work the first rotation will be and how fast you can respond to a leak later.
How to generate and store a unique SECRET_KEY
This sequence produces a high-entropy SECRET_KEY that is unique to each environment, held in a secrets store instead of the repository or image, and confirmed to be loaded before Superset first starts. Teams should run it once per environment before any deployment reaches users.
Confirm the key is required before first start
The platform engineer who owns the Superset deployment reviews the configuration and confirms that SECRET_KEY is set explicitly in the environment that will run Superset. Superset requires a user-specified key to start, a requirement added in version 2.1.0, so a deployment that boots without one is not configured as intended. Record which environments need a key (development, staging, production, and any disaster recovery copy) so none is skipped. The check is complete when every target environment has a named owner and an entry in the list.
Generate a high-entropy key with a standard tool
Generate the key on a trusted administrator workstation or inside your secrets platform using a cryptographically secure random source, such as the operating system's random generator through openssl rand. Do not type a value by hand, reuse a phrase from documentation, or copy a key from another environment. Generate one value per environment and never print it to a shared terminal history or a ticket. The output is a long random string that exists only in the secrets store once the next step is done.
Assign a separate value to each environment
Create a distinct key for development, staging, production and every other deployment that runs Superset, and keep a record of which key belongs to which environment without storing the values in the record. Sharing one key across environments lets a session signed in one place be accepted in another, which is the forgery risk this page covers. Confirm that no two environments return the same value by comparing a non-reversible fingerprint, such as a hash of each key, rather than the keys themselves. The check passes when every fingerprint is different.
Store the key in a secrets manager or orchestrator secret
Write each key to your organization's secrets manager or to a Kubernetes Secret, or the equivalent secret object in your orchestrator, with access limited to the service accounts and administrators who deploy Superset. Inject it into the Superset container as an environment variable at runtime. Keep it out of the Git repository, configuration files committed to version control, Dockerfiles, and any image layer, because anyone who can read an image or repository can read the key. The step is complete when the secret exists in the store, its access policy is recorded, and the deployment manifests reference it by name only.
Check that the key is not the documented placeholder
Before the first start, compare the loaded value with the placeholder string shipped in the example configuration and with any default you find in sample files or tutorials. Reject any match, including values that differ only by case or a trailing character. Also confirm the value has the length and randomness produced in the generation step, so a short or hand-typed value cannot pass. Run this check in the pipeline or as a documented manual review, and keep the result with the change record. It passes when the value is neither the placeholder nor any known example.
Verify the key is set before the first start
Start the Superset container or process in the target environment and confirm from the startup output that it reads the configured key rather than failing or falling back to a default. Confirm that the secret is present in the running process environment by checking the environment inside the container through your orchestrator's normal tooling, without printing the value. A deployment that starts only because a fallback was used should be treated as failed and corrected before any user logs in. The check passes when the service starts cleanly with the secret injected.
Confirm the key is absent from logs and inspection output
Review container logs, orchestrator event output, and container inspection data for the deployment, and search them for the key value or its fingerprint. Container inspect output and deployment manifests often expose environment variables in plain text, so check whether your platform masks secret values and whether anyone without a need can run inspect commands on the host. Adjust log settings, restrict inspect access, or move the value to a file mount if it appears in plain text. The step is complete when a search of logs and inspection output returns no match.
Record the key owner and rotation procedure
Document who can read and replace each environment's key, where the secret lives, and which rotation procedure applies, including the PREVIOUS_SECRET_KEY steps and the re-encryption command described elsewhere on this page. Confirm that the backup and disaster recovery process stores the key with the same restrictions as production, because a restored database cannot be decrypted without the key that encrypted it. The record is complete when a named owner can explain where each key is stored and how it would be replaced.
Configuration options for rotating the key
This table compares the ways to change the key and the failure to avoid. Read each row across to see what happens to signed sessions and to encrypted database connection credentials, then find the option that matches your transition window. The main takeaway is that the old key must stay available until every stored credential has been re-encrypted, and a leaked old key keeps validating sessions for as long as it remains configured.
| Option | Existing sessions | Stored database credentials | When it fits |
|---|---|---|---|
| Change SECRET_KEY alone | Sessions signed with the old key are expected to stop validating, so users sign in again. | Stored encrypted credentials cannot be decrypted, so database connections are expected to fail. | Only in a new environment with no stored connections, or where you will re-enter every credential. |
| Set PREVIOUS_SECRET_KEY with the new key | Sessions signed with the old key should keep validating during the window. Confirm this for your version. | Superset can read values encrypted with the old key, so connections keep working during the window. | Live rotation where users and connections must continue while you prepare the re-encrypt step. |
| Run the re-encrypt command, then retire the old key | Same as the transition window until the old key is removed, then old-key sessions stop validating. | Stored values are rewritten under the new key, so the old key is no longer needed to read them. | The standard path for a planned rotation. Confirm the exact command name in the docs for your release. |
| Remove the old key before re-encrypting | Old-key sessions stop validating immediately, which can end active user sessions abruptly. | Any credential not yet re-encrypted becomes unreadable, and connections that use it fail. | Not a valid option. This is the failure to avoid after any rotation. |
| Rotate after a suspected leak | Keeping the old key configured lets anyone holding it still forge valid sessions. | Rotate credentials stored under the old key as well, since the leaked key can decrypt them. | Shorten the transition window, re-encrypt promptly, and retire the old key as soon as it is safe. |
Running the rotation with PREVIOUS_SECRET_KEY and re-encrypt
This sequence moves a running Superset from its current key to a new one without losing access to data that was encrypted under the old key. Each step ends with a check, so the team knows when it can safely move on.
Back up the metadata database first
The database administrator takes a full, restorable backup of the Superset metadata database before any configuration changes. Encrypted values such as stored database connection credentials live in that database, so the backup is the rollback point if the re-encrypt step fails. Confirm the backup completes and that a test restore into a separate instance succeeds. Do not treat the step as done until the restore has been checked.
Stage the new key with the old key as previous
The platform engineer generates a new, high-entropy value and stores it in the team's secrets manager, not in the repository. In the staging configuration, set SECRET_KEY to the new value and PREVIOUS_SECRET_KEY to the current production key, so Superset can still decrypt existing data. Confirm the exact setting names and syntax against the configuration documentation for the installed version. The check is that the staging web and worker pods start and report the expected configuration without errors.
Deploy the change to staging
The platform team rolls the configuration to the staging environment, using the same image and deployment method as production so the test is representative. Engineers sign in, open existing dashboards, and check that scheduled jobs and async queries still run if the environment uses them. The check is a clean application log and a successful login by a test user who was created before the change. Any errors about decryption point to a wrong or missing previous key and stop the rollout.
Run the documented re-encrypt command
With the new key active and the previous key still set, the administrator runs the re-encrypt command from the Superset CLI documentation for the installed version. This rewrites stored encrypted values under the new key. Record the start time, the command output and any rows reported as failed. The check is that the command reports completion with no failures, and that a second run finds nothing left to convert.
Verify logins and database connections
The QA owner tests the paths that depend on encrypted data: user login, opening a dashboard backed by each database connection, running a SQL Lab query, and testing a saved database connection from the settings page. Sessions created before the change should behave as the team expects for its session model. Record each result against a checklist. The step is complete when every connection type used in production has been tested successfully in staging.
Repeat the sequence in production
The operations lead applies the same steps to production in a planned window, starting with a fresh metadata database backup taken at that time. The new key and previous key go into the production secrets store, followed by the re-encrypt command and the same verification checklist. The check is that the production logs show no decryption errors and the test accounts can sign in and query data. Keep the old key available until the next step is complete.
Remove the previous key after verification
Once production checks pass and the team is confident no data is still encrypted under the old key, the platform engineer removes PREVIOUS_SECRET_KEY from the configuration and redeploys. Confirm the exact removal procedure against the documentation for the installed version. The old key is then archived under the organization's key retention policy, not deleted from the record. The step is done when the running configuration shows only the new key and the change is logged in the change record.
Why reused keys enable session forgery across environments
Anyone who holds a Superset SECRET_KEY can forge session data for every environment that accepts that key. The key is what Superset relies on to trust values it signs, so its value matters more than the machine it sits on. When a production key is copied into staging, development or a sandbox built from a production image, the exposure of the whole estate becomes the exposure of its least protected environment. Development hosts are often reachable by more people, run older packages, and have weaker logging and change control. A key that was carefully guarded in production can be quietly weakened by a configuration file that was cloned for convenience.
The practical consequence is on access control. Superset's roles, dataset permissions and row level security only protect data if the session identifying the user is trustworthy. If a forged session can present itself as an Admin or as a user with broad dataset access, the role model you designed on paper is bypassed in the environment where the key is reused. Before rotating anything, list every environment that shares the key, confirm which of them hold copies of production data, and confirm who can read each environment's configuration. Ask your platform team to show where SECRET_KEY is set in each deployment, including container images, Helm values and CI variables.
In a regulated setting, a cross-environment leak is more than an engineering inconvenience. It can mean that a control you describe to auditors, such as restricted production access, no longer holds because a non-production system can impersonate production users. Your incident record would need to show which environments held the key, when it was exposed and what was done about it. Plan for this now by keeping a separate key per environment, recording where each key is stored, and deciding who approves a rotation. Confirm the exact session and signing behavior of your Superset version with your own security team and with the Superset configuration documentation before you write the control into your compliance evidence.
Storage, access and logging controls around the key
The SECRET_KEY is only as safe as the places it lives. These controls cover where the key is read, how it reaches running containers, how changes are recorded, and which copies of the data can decrypt what the key protects.
Restrict who can read the secret
Limit read access to the Superset secret in your Kubernetes namespace, secrets manager or vault to the workloads and operators that need it during deployment. Confirm that web, worker and beat pods, plus any migration job, are the only identities that can read it, and that developers and CI runners cannot read the production value. Review these bindings whenever the team changes, because a leaked key lets anyone with it forge session cookies for every environment that reuses it.
Keep the key out of images and code
Do not bake SECRET_KEY into a container image, a superset_config.py committed to version control, or a Helm values file stored in plain text. Load it at runtime from an environment variable or mounted secret, and scan your build pipeline and repositories for the key value. An image pushed to a shared registry exposes the key to everyone who can pull it, and old image layers keep the value even after you change the config.
Audit every change to the secret
Record who created, read, updated or deleted the secret, and when, in the audit log of your secrets manager or cluster. Tie each rotation to a change ticket that names the old and new key references, the PREVIOUS_SECRET_KEY window and the re-encryption run. Without this trail, you cannot tell whether an unexpected session or encrypted-value problem came from a rotation, a misconfigured environment or an intrusion.
Protect metadata database backups
Backups of the metadata database can contain values encrypted with SECRET_KEY, such as stored database connection credentials. Restrict who can restore or download these backups, encrypt them at rest, and keep the backup key or retention rules separate from the Superset key where your storage allows it. Confirm that a restored backup from before a rotation still has the old key available, because the restore procedure depends on it.
Keep the key out of support tickets
Support requests, chat threads, log exports and screenshots of configuration pages are common places where a key is copied by accident. Set a team rule that engineers share the key name and the environment, never the value, and mask the value in any log or diagnostic bundle you send to a vendor or partner. If a value has already been pasted into a ticket or chat, treat it as exposed and start the response plan.
Response plan if the SECRET_KEY leaks
A leaked SECRET_KEY lets an attacker forge session cookies and read data protected by that key, so the response runs several tracks at once. The cards below can be worked in parallel by security, platform and data teams, with the compliance decision marked where it belongs.
Contain and scope the exposure
Start by establishing where the key lived and who could read it: config files, container images, CI variables, shared runbooks, and any environment that copied the same value. Record every deployment that used the key and whether it was reachable from outside your network. Treat the key as compromised for any environment you cannot rule out. Scoping decides how far the later steps must reach, so write down what you checked and what you could not confirm.
Generate and deploy a new key
Generate a new, high-entropy value and store it in your secrets manager rather than a checked-in config file. Move the old value into PREVIOUS_SECRET_KEY only if you need to re-encrypt stored credentials, and confirm that the compromised value is no longer the active SECRET_KEY in any environment. Deploy to every web and worker process at the same time, because mixed keys across nodes will cause sessions and encrypted values to fail unpredictably.
Invalidate sessions and review logs
Cookie-based sessions signed with the leaked key can be forged, so changing the key is the first invalidation step, but confirm that your session backend actually ends existing sessions. Review web server and Superset access logs for logins, unusual user agents, and requests from unfamiliar addresses during the exposure window. Look for role changes, new users, and dashboard or SQL Lab activity by accounts that were not active. Preserve these logs before retention limits remove them.
Rotate stored database credentials
Superset encrypts the database connection passwords it stores in its metadata database using the secret key, so an attacker holding the key may be able to decrypt them. Rotate the passwords for every warehouse and database connection Superset uses, and update the connections in Superset with the new values. Also rotate OAuth client secrets, LDAP bind credentials, SMTP and alert-channel tokens, and any other secret kept in the metadata database. Run this as a checklist tied to your inventory, not from memory.
Review backups and shared environments
Backups of the metadata database contain values encrypted with the old key, so anyone who obtains a backup and the leaked key can recover stored secrets. Decide how long old backups are kept, whether they should be re-encrypted or destroyed, and who can restore them. Check staging, test and development environments that were built from production data or configuration, since they may share the same key and the same database credentials. Each copy needs its own decision and an owner.
Document and decide on notification
Write an incident record covering the timeline, scope, actions taken, evidence preserved and open questions, and hand it to the security team for review. Whether the exposure triggers a notification duty to customers, regulators or data subjects depends on what data was reachable and on the laws and contracts that apply to you. Mark this decision as a legal and compliance call and confirm the obligations with your own counsel before any notice goes out.
Questions teams ask before rotating the Superset secret key
How much effort does a SECRET_KEY rotation take?
The effort depends on how many environments share the key, how much encrypted data sits in the metadata database, and how well the current configuration is documented. A single instance with one owner and a tested staging copy is a short, contained change. Effort rises when several Superset instances, a Kubernetes deployment or a Helm values file must all be updated together, or when nobody can confirm where the current key is stored. The main work is planning the cutover, setting PREVIOUS_SECRET_KEY correctly, running the re-encrypt step on a copy first, and verifying logins and connected database credentials afterward. Ask any provider to break the quote into those steps and to state which environments are included.
Can our own team rotate the key without outside help?
Yes, if your team already runs Superset and can follow the upgrade and configuration documentation. The rotation itself is a configuration change plus a documented re-encrypt command, so an engineer comfortable with the deployment tooling can do it. Outside help is most useful when the key is shared across environments, when the key was exposed and you need a response plan with evidence, or when the team lacks staging capacity to rehearse the change. Whichever route you choose, assign one owner, write down the current configuration, and confirm that someone can roll back if logins or data access break.
What does the rotation need from our team?
It needs a staging environment that mirrors production closely enough to test the re-encrypt step, a verified backup of the metadata database taken before any change, and a named owner for the secret store where the key lives. It also needs a change window that covers the restart of web and worker processes, plus time for someone to test logins, dashboards, scheduled reports and saved database connections. Confirm who can approve the window, who receives alerts if authentication fails, and how the team will communicate with users if sessions are invalidated.
How often should we rotate the Superset secret key?
There is no fixed interval supplied in the project documentation, so the schedule should come from your own policy, your identity and key management standards, and your risk assessment. Common triggers include a staff change in people who could read the configuration, a planned major upgrade, a suspected exposure in logs or backups, or a change in hosting. Record the rotation date, the environments covered and the evidence of the re-encrypt run each time, because auditors usually ask for that history rather than the frequency alone.
If the secret key leaks, do we always need a full rebuild?
No. A leaked key is serious because it allows session forgery and tampering with signed data, but a full rebuild is not required in every case. The usual response is to generate a new key, set the old value as PREVIOUS_SECRET_KEY, run the re-encrypt step, restart services, and then remove the old value once data is converted. You still need to review access logs, invalidate sessions, rotate the database and connection credentials that Superset stores, and check whether the key appeared in backups or images. Rebuild only if you cannot establish what the key protected or if the host itself is compromised.
How does rotating the key relate to a Superset upgrade?
Both change the state of the metadata database, so they should be planned together but not blended into one change. The upgrade documentation calls for a metadata database backup, superset db upgrade, superset init, staging tests and a review of UPDATING.md for breaking changes. Run the key rotation as a separate, documented step so that a failure can be traced to one cause. Confirm the order with your plan, and do not rotate the key during an upgrade that is already failing its staging tests.
Does Superset have a paid edition that includes key management support?
Apache Superset is released under the Apache License 2.0 and the project has no paid edition, so the software itself carries no license fee. Costs come from the people, infrastructure and secret management tools you use to run it. Ask any provider to list those components separately in the quote, including who maintains the secret store and who handles the on-call response if a rotation fails in production.
Limits to confirm in your environment
The SECRET_KEY rotation steps depend on details that change between Superset releases and deployment methods. The cards below list what to verify in your own environment before you run a rotation in production, so the plan you write matches the version and platform you actually operate.
PREVIOUS_SECRET_KEY behavior by version
Superset supports rotating the key with PREVIOUS_SECRET_KEY, but the exact behavior of that setting should be confirmed against the release you run. Read the configuration documentation for your version, then test on a staging copy of your metadata database. Confirm which key Superset uses to decrypt existing values and which it uses to sign new ones, and whether the old key must stay in place until re-encryption finishes.
Re-encrypt command and its scope
Confirm the exact re-encrypt command for your version and what it touches. Ask whether it covers only stored database connection credentials or also other encrypted fields, and whether it can run against a live metadata database. Check its runtime on a copy of production data, and confirm that a backup taken before the run can restore the previous state if the job fails partway.
Sessions and existing logins
Confirm how the new key affects signed session cookies. If sessions are cookie based, a key change may invalidate active logins, which is useful after a leak but disruptive during planned rotation. If you use a server-side session backend, confirm whether session records survive the change. Plan the window and tell users to expect a fresh sign-in.
Helm and Kubernetes Operator behavior
The Helm chart is marked deprecated for new deployments, and the Kubernetes Operator is in alpha with a v1alpha1 API whose schemas may change between releases. Confirm how each method sets SECRET_KEY and PREVIOUS_SECRET_KEY, whether the value comes from a Secret or a plain values file, and whether a change triggers a rolling restart. Do not assume an alpha operator will keep the same field names after an upgrade.
Proxy, cache and worker propagation
Web pods, Celery workers and beat processes must all read the same new value, or background jobs will fail to decrypt credentials that the web tier wrote. Confirm how each component receives the setting, whether workers restart with the web tier, and whether the reverse proxy or caching layer holds any cached session data. Verify the order of the rollout in staging before production.
Alerts, reports and scheduled jobs
Alerts, reports and async queries depend on the caching layer and worker components. Confirm that scheduled reports still send and that async queries still return results immediately after rotation. Check the Superset version's notes for any changes to how stored credentials are read by these jobs, and test one scheduled report end to end before you close the change window.
How DeployOpen scopes and delivers Superset key rotation
DeployOpen plans and carries out SECRET_KEY rotation as a written, fixed-scope piece of work inside your own infrastructure. We confirm which environments share keys, build the rotation with PREVIOUS_SECRET_KEY and the re-encrypt step, test it in staging, and hand over a runbook your team can repeat.
How we scope
- We inventory every Superset environment and confirm which ones currently share a SECRET_KEY value.
- We confirm the metadata database engine and version against the supported range before planning the re-encrypt step.
- The written scope lists the environments, secret storage location, rotation window and who approves the change.
How we build
- We set up a unique SECRET_KEY per environment in your secrets store and wire it into the deployment configuration.
- We run the rotation in staging with PREVIOUS_SECRET_KEY, then run the re-encrypt command and check that stored credentials still decrypt.
- We test login, existing sessions, database connections and scheduled reports after each rotation step.
How we hand over
- You receive the configuration changes, the rotation runbook and the verification checklist used during testing.
- The runbook includes a documented response plan for a suspected key leak, with steps to rotate, invalidate sessions and review logs.
- We walk your platform and security teams through the runbook so they can repeat the rotation without us.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the fixed-scope work ends.
- Rotation steps are rechecked when you upgrade Superset, since upgrade notes can change how configuration and keys are handled.
- Ask your DeployOpen contact to confirm retainer coverage for key rotation drills and leak response exercises.
