When Apache Superset needs an SSH tunnel to reach your database
A self-hosted Superset often has to query a database that sits in a private subnet with no direct route from the Superset host. In that case the question is not whether Superset can connect, but how the traffic reaches the database. Superset's SSH tunneling support is one answer: the Superset host opens an SSH session to a bastion or jump host that can reach the database, and the database connection is routed through that session. The capability is off until you enable the SSH_TUNNELING feature flag in your configuration, so a tunnel is a deliberate configuration choice that depends on your network design, not a default you inherit.
Once the flag is on, Superset supports basic (username and password) and private key authentication for the SSH hop. Private key authentication is usually the stronger choice for a service account, because the credential is not typed into a database connection form and can be scoped to the single jump host. Before rollout, confirm with your network and security teams which bastion hosts are approved, which account Superset will use on each one, how the private key is stored and rotated, and whether the jump host logs the sessions. Those answers determine whether a tunnel fits your access model at all.
The tunnel also changes the blast radius. The SSH hop becomes one more path into a database network, so the jump host should accept connections only from the Superset host and only to the database ports it must reach. Superset's network settings allow the local bind address to be set with SSH_TUNNEL_LOCAL_BIND_ADDRESS and the tunnel manager class to be overridden, and both should be reviewed against your host firewall and logging design. If your organization can place Superset and the database on a shared private network, or use a site-to-site link, that is often the safer option, because it removes an interactive-style access path that someone must monitor and maintain. Confirm the options in the Superset network and security settings before you choose.
Password versus private key authentication for the tunnel
Basic authentication sends a username and password for the SSH account on the bastion host. It is the simpler option to set up because the credential is a single string, and most teams already know how to rotate account passwords. The trade-off is that the password becomes a reusable secret that someone must enter, store and protect wherever Superset needs it.
- Setup effort: A password can be issued and tested quickly, which suits short proofs of concept on a restricted network.
- Rotation: Changing a password means updating every database connection that uses the tunnel and coordinating with the team that owns the bastion account.
- Auditability: If the bastion account is shared, its logins cannot be tied to one person, so confirm that your bastion logs identify the individual or service behind each session.
- Exposure: A password typed into a form can be copied, pasted into tickets or reused on other hosts.
Check whether your bastion host allows password login at all, and whether the account is a named account or a shared service account.
Private key authentication uses a key pair: the bastion holds the public key, and Superset presents the private key to prove its identity. The Network and security settings documentation lists private key authentication as a supported option alongside basic authentication. A key can be protected with a passphrase, can be granted access to one account on the bastion, and can be revoked by removing its public half.
- Revocation: Removing one public key from the bastion cuts off that Superset instance without changing access for other users or services.
- Passphrase protection: Ask whether the private key is protected by a passphrase and who holds it, since an unprotected key file works as a bearer credential.
- Approved algorithms: Confirm with your security team which key types and sizes are approved, and check that the bastion accepts them before you generate the key.
- Operational steps: Someone must generate the pair, install the public half, and record the key's fingerprint and owner, which adds steps to every deployment.
Confirm that the bastion's SSH service accepts the key type you generate before you place the key in a production connection.
The team that owns the bastion host should approve each key's access, and the team that owns Superset should own how the key is used inside the application. Splitting these responsibilities means a Superset administrator cannot open new network paths on their own, and a network administrator does not need to know which dashboards depend on the tunnel. Record the owner, purpose and rotation schedule for every key in your inventory.
- Named owner: Assign one accountable team to each key, with a named backup, and record both in your change system.
- Separate keys per environment: Use different keys for each Superset environment (illustratively, production and staging) so that a leaked key does not expose every instance.
- Rotation procedure: Agree the steps before the first rotation: generate the new key, add its public half to the bastion, update the Superset connection, test it, then remove the old public key.
- Rotation interval: Set the interval according to your security policy. The documentation supplied for this topic does not give a recommended period, so ask your policy owner.
Ask who can remove a key from the bastion, and whether that person is notified when a Superset connection changes.
Credentials usually leak through places that are easy to forget: superset_config.py, environment variables in container manifests, Helm values, shell history, and connection details edited by hand. Superset requires a user-specified SECRET_KEY to start, so treat that value as a secret in its own right. Confirm in the documentation for your version how tunnel credentials are stored in the metadata database, and whether they are encrypted with that key.
- Config files: Keep SSH material out of
superset_config.pyand out of version control, and reference a mounted file path or a secret store instead. - Manifests and values: Pass key material through your orchestrator's secret mechanism, and keep it out of plain environment entries in manifests and chart values.
- Dashboards and exports: Test whether database exports or API responses reveal connection details, and restrict who can export database definitions.
- Backups: Metadata database backups carry whatever Superset stores, so apply the same access controls and retention rules to them.
- Terminals and logs: Avoid pasting keys into terminals, tickets or chat, and confirm that log settings do not print connection parameters.
Before go-live, search your repositories, container images and backups for private key headers, and confirm the results with the people who own each location.
Which SSH tunnel settings fit which network design
This table compares the four SSH tunnel settings Superset exposes, what each one controls, the network designs it suits and what to confirm with the network team before enabling it. Read each row as a separate decision, since the flag, the authentication method, the bind address and the tunnel manager override are set independently.
| Setting | What it controls and when it fits | What to confirm with the network team |
|---|---|---|
| SSH_TUNNELING feature flag | Turns on SSH tunnel support in the Superset database connection dialog. Enable it only where a database is reachable through a bastion or jump host and not directly from the Superset network. | Which bastion hosts are approved, whether they are allowed to reach the database port, and who owns the bastion's access logs. |
| Basic (password) authentication | Lets Superset log in to the bastion with a username and password. It fits short-lived pilots or hosts where key distribution is not yet possible, but the password must be stored with the connection. | Whether password logins are permitted on the bastion at all, how the password is rotated, and whether a policy requires key-based access instead. |
| Private key authentication | Lets Superset authenticate to the bastion with a private key. It fits production networks that prohibit shared passwords, and it lets the network team restrict the key to one account and one destination. | Which key type is approved, where the key is stored and who can read it, how keys are rotated and whether the bastion can restrict the key to port forwarding only. |
| SSH_TUNNEL_LOCAL_BIND_ADDRESS | Sets the local address the tunnel listens on inside the Superset host. Keep it on the loopback address unless another process or container must reach the tunnel, since a wider bind exposes the forwarded port to other hosts. | Whether other services on the Superset host or in its container network need to reach the tunnel, and whether host firewall rules block the forwarded port from the wider network. |
| Overriding SSHTunnelManager | Replaces the default tunnel handling class with your own implementation, for example to add custom logging, host key checks or connection rules. It adds code you must maintain through every Superset upgrade. | Whether the security team has approved custom tunnel code, who reviews it and whether it is tested against each new Superset release before upgrading. |
| Private network link instead of a tunnel | A VPN, private link or peering connection can be safer when many users or services need the database, because the tunnel is then a per-user path through a bastion that must be managed. It also avoids placing a bastion in the data path. | Whether a private link to the database network already exists, what the change process and lead time are, and whether the database owner accepts the connection path. |
Configuring SSH tunneling in a self-hosted Superset
This sequence takes a self-hosted Superset from an unconfigured host to a verified database connection that reaches a private database through a bastion host, with each step checked before the next begins.
Confirm the bastion path and firewall rules
The network or platform team confirms which bastion host or jump server will carry the tunnel, which database host and port it must reach, and which firewall rules allow the Superset web and worker hosts to open outbound SSH sessions to that bastion. Record the bastion address, the SSH port, the database host and port, and the host key fingerprint, and confirm the bastion can reach the database. The step is done when a manual SSH session from the Superset host to the bastion succeeds and the bastion can open a connection to the database port. Ask the security team to confirm the bastion's logging and access policy before any tunnel is opened.
Enable the SSH_TUNNELING feature flag
A Superset administrator sets the SSH_TUNNELING feature flag to true in the FEATURE_FLAGS section of superset_config.py, then restarts the web and worker processes so the setting loads everywhere. Confirm the flag name against the networking and security settings documentation for your Superset version, because flags can change between releases. The step is done when the Database connection dialog in Superset shows the SSH tunnel option for a database connection and the web application starts without configuration errors in its logs.
Choose and provision the authentication method
The team decides between password and private key authentication for the tunnel account. Superset supports basic and private key authentication for SSH tunnels. Key authentication usually suits unattended workers better, because the key can be stored in a secrets manager and rotated, while passwords need a rotation process of their own. Create a dedicated bastion account with the least rights needed to open forwarding sessions, install the public key or set the password on the bastion, and store the private key or password in your secrets store rather than in notebooks or chat. The step is done when a test login with that account and method succeeds from the Superset host using the same user the web and worker processes run as.
Set the local bind address
Set SSH_TUNNEL_LOCAL_BIND_ADDRESS in superset_config.py to the local address on which the forwarded port should listen on the Superset host. Keep this on the loopback interface unless you have a specific reason to expose the forwarded port, because a tunnel listening on a wider interface can be reached by other hosts on the network. Confirm the setting name and default behavior in the networking settings documentation for your version. The step is done when, after a restart, a test tunnel opened from the Superset host binds to the intended address and no other address, which you can confirm with a socket listing command such as ss on Linux.
Override the tunnel manager only when required
Most deployments keep the default SSHTunnelManager class. Override it only when a documented requirement, such as a custom authentication step or an audit hook, cannot be met by the default. Any override becomes code your team owns and must be reviewed on every Superset upgrade, so record the reason and test it against the target version in staging. The step is done when either the default is confirmed as sufficient in a written decision or the custom class loads without errors and passes the connection test in the next steps.
Create the database connection through the tunnel
A user with permission to manage database connections creates the connection in Superset, enters the database host and port as seen from the bastion, selects the SSH tunnel option, and enters the bastion host, port, username and chosen credential. Use a database account with read-only privileges for analytics, and keep the credential out of shared screens and exports. Save the connection. The step is done when the connection record exists, the stored secret does not appear in plain text in the UI or logs, and the database appears in the list of connections available to the Superset admin account.
Test from the Superset host and from a worker
Run the connection test in the Superset UI, then repeat it from a Celery worker because scheduled reports, alerts and async queries run there and may have different network paths or service accounts. Check the web and worker logs for tunnel open and close messages and for authentication errors. Run a simple query such as selecting the current timestamp from SQL Lab on each path. The step is done when the test passes from both the web tier and a worker, the query returns a result, and the tunnel closes cleanly after the session, which confirms the setup is ready for users and scheduled jobs.
Security risks of tunneling into private databases
An SSH tunnel gives Superset a path into a database that is not reachable from the internet, so the tunnel becomes part of your attack surface. Each risk below maps to a control your operations team can check on the bastion, the Superset host and the database itself.
Bastion exposure to the internet
The bastion host is the one machine that accepts inbound SSH from outside the private network, so it is the first target for anyone trying to reach your databases. Confirm that the bastion accepts SSH only from the Superset host's address range or a管理 network you approve, that password logins are disabled, and that the host receives the same patching and vulnerability scanning as other internet-facing systems. Ask who owns the bastion, since Superset teams often assume the platform team does.
Over-privileged SSH accounts
The account Superset uses to open the tunnel should be able to forward traffic to one database host and port and nothing else. A general shell account on the bastion can read other hosts' configuration, pivot to other networks and reach services Superset never needs. Verify that the account has no interactive shell, that forwarding is limited to the database endpoint, and that a separate account exists for each Superset environment so revoking one does not affect the others.
Private key handling
Private key authentication avoids storing a password in the Superset metadata database, but the key then becomes the credential that matters. Check where the key file lives on the Superset host, who can read it, whether it is passphrase protected, and whether it is rotated when staff change roles. Confirm that the Superset database connection record stores only what the tunnel configuration requires and that the key is never written to logs, screenshots or exported dashboards.
Local bind address exposure
The local bind address decides which network interfaces can use the forwarded port on the Superset host. A bind to all interfaces lets other hosts on that network reach the database through Superset's tunnel, bypassing the database's own access rules. Verify that SSH_TUNNEL_LOCAL_BIND_ADDRESS is set to a loopback or otherwise restricted address, and confirm with a port scan from another host that the forwarded port does not answer.
Connection activity logging
A tunnel can carry many database sessions, and the bastion may record only that a connection opened, not which Superset user or query caused it. Confirm that bastion logs capture session start and end times, source address and the target host, and that Superset audit records link a query to a user. Ask who reviews these logs, how long they are kept, and how a suspicious session would be traced back to a named account.
Database privileges for the tunnel path
A working tunnel does not limit what Superset can do once a query reaches the database. The database user that Superset connects with should hold read privileges on the schemas its dashboards need, and nothing that changes data or creates objects. Verify the grants on that user, check that write and DDL rights are absent, and review them whenever a new dataset is added through the tunnel.
When a private network link is safer than a tunnel
A private network path is usually the safer way to reach a database when your cloud or data center can provide one. Options such as network peering between VPCs or virtual networks, a site-to-site VPN, or a private service endpoint let Superset connect to the database address directly over routes that never cross the public internet. An SSH tunnel adds a bastion host, an SSH daemon that must be patched and monitored, and a key or password that Superset must store and present on every connection. Each added hop is another component that can fail, be misconfigured or be exposed, and each long-lived SSH credential is another secret to rotate, scope and revoke when someone leaves the team.
The choice depends on your network, not on Superset. Before you enable the SSH_TUNNELING flag, confirm which options your cloud account or data center actually offers: whether the Superset workers and the database sit in networks that can be peered, whether your provider offers private endpoints for the database service, and whether a VPN gateway already exists between the Superset host and the database segment. Check the routing and DNS as well, because a private address that resolves differently from inside and outside your network can send traffic to the wrong place. Ask your network team to document each path and its owner so that the connection does not depend on one person's workstation.
A tunnel still makes sense when the database is reachable only through a jump host that your security policy already requires, or when a private link cannot be built within the project's timeline. In that case, plan for the tunnel's ongoing costs: key rotation, bastion patching, logging of tunnel sessions and a test that proves the connection fails closed when the bastion is down. Whichever path you choose, record the decision, the network ownership and the review date in your architecture documentation, so that the next change to network or database access is made with the trade-off in view.
Questions teams ask before setting up Superset SSH tunnels
What does it cost to set up SSH tunnels for Superset, and who pays for it?
The cost comes from the people hours needed to design, configure and verify tunnel access, paid either to your internal team or to a partner under a fixed-scope written agreement. Setup is mostly one-time work: confirming network paths, enabling the SSH_TUNNELING feature flag, configuring authentication and testing each database connection. Recurring costs appear later, when bastion hosts, keys or database accounts must be rotated, or when an upgrade changes configuration. The main cost drivers are the number of databases behind separate bastions, how many network zones are involved, and whether your security team must review each tunnel. Ask any quote to itemize discovery, configuration, testing, documentation and handover, and to state what is excluded.
How long does SSH tunnel setup take when network access is limited?
Duration depends mostly on how quickly you can grant access to the bastion host and the target databases, not on the Superset configuration itself. When a bastion already exists and the Superset host can reach it, the configuration work is usually short. Delays come from change approvals, firewall rule requests, network diagrams that do not match reality, and waiting for database accounts to be created. Ask any proposal to name which of these prerequisites it assumes are already in place, and to list what would extend the timeline if they are not.
What must our team provide before a tunnel engagement starts?
Expect to provide three groups of inputs before configuration begins:
- Bastion access: a jump host the Superset server can reach, its address, the login method and who approves changes to it.
- Network diagrams: the paths between the Superset host, the bastion and each database, with firewall zones marked.
- Database accounts: read-only accounts per database, created for Superset, with credentials stored in your secrets system.
Also confirm the Superset version and where the metadata database runs, because these affect where the feature flag and settings are applied. Missing inputs are the most common reason setup slows down.
Can our in-house team set up SSH tunnels for Superset without a partner?
Yes, if your team has Superset administration experience and someone who can manage the bastion and firewall rules. The work requires enabling the SSH_TUNNELING feature flag, choosing between password and private key authentication, setting SSH_TUNNEL_LOCAL_BIND_ADDRESS where needed and, if required, overriding the SSHTunnelManager class. Teams without these skills should ask a partner to deliver a written configuration, a verification checklist and a handover session. Whichever path you choose, confirm the authentication method against the Superset network and security settings documentation for your version.
Does an SSH tunnel setup change after a Superset upgrade?
Tunnel settings are configuration, so they usually survive an upgrade, but each upgrade is a point where they should be retested. Follow the Superset upgrade process: back up the metadata database, run the upgrade in staging, check the release's breaking change notes and then confirm every database connection through its tunnel. Changes to feature flags, default settings or the tunnel manager class can affect behavior without any error at startup. Ask whether your plan includes a post-upgrade connection test for each database and who owns it.
Is an SSH tunnel safer than a private network link to the database?
A private network link is usually the safer option when your network design allows it, because it removes a hop and an extra component that must be patched and monitored. An SSH tunnel is a reasonable choice when the database sits in a segment that Superset cannot reach directly, but it adds a bastion host, key management and audit scope. Weigh the security review of the bastion, key rotation, logging of tunnel sessions and the blast radius if the bastion is compromised. Document the decision so your auditors can see why the tunnel was chosen.
Which security checks should we ask for before going live with tunnels?
Ask for a review that covers the authentication method, where private keys or passwords are stored, the least-privilege database accounts used through the tunnel, the bastion's access logs and which network paths are allowed. Confirm that the local bind address is limited to the intended interface, so other hosts cannot reuse the tunnel. Check that the review results are written down and linked to the change record, since assessors will ask for this evidence. DeployOpen can prepare these controls and evidence for your review, but independent auditors and certification bodies decide compliance.
How DeployOpen scopes and delivers Superset database connectivity
DeployOpen plans, builds, tests and documents SSH tunnel connections from your self-hosted Superset to databases inside your own network. Each engagement starts with a written scope that names the databases, bastion hosts, authentication method and access paths, so the work and its deliverables are agreed before any configuration begins.
How we scope
- We inventory which private databases Superset must reach and which bastion or jump hosts sit between them.
- The written scope names the authentication method for each tunnel, either password or private key, and who owns the keys.
- We agree how the SSH_TUNNELING feature flag, local bind address and tunnel manager override will be set and reviewed.
How we build
- We enable the SSH_TUNNELING feature flag in your Superset configuration and verify tunnel behavior in a staging environment first.
- We configure SSH_TUNNEL_LOCAL_BIND_ADDRESS and document which interfaces the tunnel listens on in your hosts.
- We test each database connection through the tunnel and record failure modes such as unreachable hosts or rejected keys.
How we hand over
- You receive configuration records, a connection inventory and a runbook for rotating SSH credentials and keys.
- The handover covers the network paths used, the firewall rules involved and the reasoning behind each tunnel design choice.
- Your team walks through the tunnel tests with us so operators can repeat them after changes.
How we support
- Ongoing support, upgrades and continuous testing of tunnel connections are available as a retainer.
- Upgrades of Superset are checked against tunnel configuration before rollout, using your staging environment.
- Changes to bastion hosts, database endpoints or key rotation follow the documented procedure and are recorded in the scope.
