Database Access Architecture

This section provides an overview of Teleport Database Access inner workings.

How it works

Let's take a look at a sample Database Access deployment:

In it, we have the following Teleport components:

• Teleport Proxy. A stateless service that performs a function of an authentication gateway, serves web UI and accepts database (and other) client connections.
• Teleport Auth. Serves as cluster's certificate authority, handles user authentication/authorization and issues short-lived client certificates.
• Teleport Database Service. The Database Access' "brain" that connects to the databases, performs database authentication and protocol parsing.

Database Service establishes an SSH reverse tunnel to the Proxy. As such, users do not need to have direct connectivity to the Database Service, or the databases it's connected to. As long as it can dial back to the cluster's Proxy server, it can be located behind a firewall.

Let's take a look at the typical flow Database Access users go through to connect to a database.

1. A user logs into the cluster with tsh login command and retrieves a client certificate. See Issuing User Certificates for more details on how it works.
2. The user picks the database they want to connect to from the list of available databases shown in tsh db ls command and retrieves a short-lived X.509 certificate for it with tsh db login.
3. The user uses a standard database client (e.g. psql, mysql or one of the graphical clients) to connect to the Proxy, authenticating with the client certificate from step 2.
4. The Proxy authenticates the connection and dispatches it to the appropriate Database Service based on the routing information encoded in the client certificate, over the reverse tunnel.
5. The Database Service authenticates the connection, performs an authorization check, and then establishes the connection to the database.
6. The Database Service begins proxying traffic between the user's database client and the database. Additionally, it interprets the database wire protocol messages and submits events to the Teleport audit log.

Authentication

Teleport relies on short-lived X.509 certificates for user authentication, as well as authentication between internal components.

Authentication happens in 3 places:

• Database client connecting to Proxy
• Proxy connecting to Database Service
• Database Service connecting database.

Let's take a detailed look at each authentication point.

Database client to Proxy

Database clients authenticate with the Proxy using X.509 client certificates obtained from the tsh db login command.

The login command updates database-specific local configuration files (e.g. PostgreSQL connection service file or MySQL option file to group connection information for a particular database, which CLI clients can refer to.

For configuring graphical clients, there is a tsh db config command that prints detailed information about the connection such as host/port and location of the secrets. See GUI Clients for details.

Proxy to Database service

The connection between the Proxy and the Database Service is also authenticated with mutual TLS.

The Proxy generates a short-lived X.509 certificate signed by the cluster's host authority, with the client's identity and database routing information encoded in it, and uses it to authenticate with the Database Service.

Database service to database

Database authentication is handled differently for self-hosted databases and databases hosted by AWS.

Self-hosted

Teleport Database Service uses client certificate authentication with self-hosted database servers.

See respective configuration guides for PostgreSQL and MySQL for details on configuring client certificate authentication.

AWS RDS / Aurora

With RDS and Aurora database instances, the Database Service authenticates using IAM Authentication.

The Database Service automatically generates an IAM token for each connection and uses the token as a password.

See respective configuration guides for PostgreSQL and MySQL for details on configuring IAM authentication.

Next steps

Please refer to the RFD #11 for a more in-depth description of the feature scope and design.

See Architecture Overview for general Teleport architecture principles.