Why do Database Tunnels need authentication but in-Stack connections don't?

Hello! I have a question: how is a deployed App authenticated to use a Database’s connection URL?
I mean, that when an Aptible user tries to connect to a database directly - this is also protected by the authentication token received in Aptible cli. But what about Apps, where in the App config we define the Database URL? And if I deploy an application outside of Aptible and define the database url - it shouldn’t be able to connect, but why? How does the protection work there?

Great question! The Database connection URL used by Apps and Ephemeral SSH Sessions within the Stack does not require Aptible user authentication like you would have with a Database Tunnel. Both connections still use the Database’s user authentication (the user and password from the connection URL), and both connections are encrypted in transit.

The default behavior of Aptible Databases is that they are only exposed to traffic originating from within the Aptible Stack they reside in. The hostname from the default credentials (in the format "db-${STACK_NAME}-${DATABASE_ID}.aptible.in") is set to resolve to the internal IP address of the host within that Stack (generally 10.x.y.z, a Class A private network address). This won’t be routable from anywhere except the Stack network.

However, engineers commonly need to access databases directly in the course of their work. One option would be to create an External Endpoint to allow access from outside the Stack, but best practices require using IP Filtering to allow only known IPs (your engineers, reporting tools, etc.) access to the Database. This requires management of the IP allow-list, and still widens the attack surface of your Database by exposing it to the public internet.

So instead, we created Database Tunnels as an option to create a temporary connection directly to the Database. The Aptible CLI contacts your Stack’s bastion instance to link a port on your computer to the Database on your Stack. This is why the connection details printed by the db:tunnel command are different from the default credentials - the hostname localhost.aptible.in ( is your computer, and the port is whichever free port the Aptible CLI temporarily claimed for the tunnel. To run this command, the user must authenticate via the Aptible CLI to prove both that they are associated with your Organization, and that their Role(s) give them manage access to the Database’s Environment. Once the user exits via ctrl-c or the tunnel times out, the temporary connection is severed.

Hope that’s helpful, let me know if you have any questions!

1 Like