Fork me on GitHub
Teleport

Database Access GUI Clients

Improve

This guide describes how to configure popular graphical database clients to work with Teleport Database Access.

Setting up your Teleport environment

Prerequisites

Ensure that your environment includes the following:

  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

  • The tctl admin tool and tsh client tool version >= 9.2.3.

    tctl version

    Teleport v9.2.3 go1.17

    tsh version

    Teleport v9.2.3 go1.17

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 9.2.3, which you can download by visiting the customer portal.

    tctl version

    Teleport v9.2.3 go1.17

    tsh version

    Teleport v9.2.3 go1.17

  • A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

  • The tctl admin tool and tsh client tool version >= 9.1.2. To download these tools, visit the Downloads page.

    tctl version

    Teleport v9.1.2 go1.17

    tsh version

    Teleport v9.1.2 go1.17

  • The Teleport Database Service configured to access a database. See one of our guides for how to set up Teleport Database Access for your database.

Get connection information

Starting the local database proxy with the --tunnel flag will create an authenticated tunnel that you can use to connect to your database instances. You won't need to configure any credentials when connecting to this tunnel.

Here is an example on how to start the proxy:

First, login into the database.

tsh db login <database-name>

Then, start the local proxy.

tsh proxy db --tunnel <database-name>

Started authenticated tunnel for the <engine> database "<database-name>" in cluster "<cluster-name>" on 127.0.0.1:62652.

You can then connect to the address the proxy command returns, in our example it is 127.0.0.1:62652.

If you're using Teleport in TLS routing mode where each database protocol is multiplexed on the same web proxy port, use the following command to start a local TLS proxy your GUI database client will be connecting to:

tsh proxy db <database-name>

Started DB proxy on 127.0.0.1:61740

Use following credentials to connect to the <database-name> proxy:

ca_file=/Users/r0mant/.tsh/keys/root.gravitational.io/certs.pem

cert_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice-db/root/<database-name>-x509.pem

key_file=/Users/r0mant/.tsh/keys/root.gravitational.io/alice

Use the displayed local proxy host/port and credentials paths when configuring your GUI client below. When entering the hostname, use localhost rather than 127.0.0.1.

If you're not using TLS routing, run the following command to see the database connection information:

View configuration for the database you're logged in to.

tsh db config

View configuration for the specific database when you're logged into multiple.

tsh db config example

It will display the path to your locally cached certificate and key files:

Name:      example
Host:      teleport.example.com
Port:      3080
User:      postgres
Database:  postgres
CA:        /Users/alice/.tsh/keys/teleport.example.com/certs.pem
Cert:      /Users/alice/.tsh/keys/teleport.example.com/alice-db/root/example-x509.pem
Key:       /Users/alice/.tsh/keys/teleport.example.com/alice

The displayed CA, Cert, and Key files are used to connect through pgAdmin 4, MySQL Workbench, and other graphical database clients that support mutual TLS authentication.

PostgreSQL pgAdmin 4

pgAdmin 4 is a popular graphical client for PostgreSQL servers.

To configure a new connection, right-click on "Servers" in the main browser view and create a new server:

pgAdmin Add Server

In the "General" tab of the new server dialog, enter the server connection name:

pgAdmin General

In the "Connection" tab, fill in the hostname, port, user and database name from the configuration above:

pgAdmin Connection

In the "SSL" tab, set "SSL Mode" to Verify-Full and fill in paths for client certificate, key and root certificate from the configuration above:

pgAdmin SSL

Click "Save", and pgAdmin should immediately connect. If pgAdmin prompts you for password, leave the password field empty and click OK.

PostgreSQL DBeaver

To connect to your PostgreSQL instance, use the authenticated proxy address. This is 127.0.0.1:62652 in the example above (see the “Authenticated Proxy” section on Get connection information for more information).

Use the "Database native" authentication with an empty password:

DBeaver Postgres Configure
Server

Clicking on "Test connection" should return a connection success message. Then, click on "Finish" to save the configuration.

MySQL Workbench

MySQL Workbench is a GUI application that provides comprehensive MySQL administration and SQL development tools.

In the MySQL Workbench "Setup New Connection" dialog, fill out "Connection Name", "Hostname", "Port", and "Username":

MySQL Workbench
Parameters

In the "SSL" tab, set "Use SSL" to Require and Verify Identity and enter the paths to your CA, certificate, and private key files (see Get connection information):

MySQL Workbench SSL

Optionally, click "Test Connection" to verify connectivity:

MySQL Workbench Test

Save the connection and connect to the database.

MySQL DBeaver

Note

Teleport's DBeaver MySQL integration only supports versions of MySQL server up to 8.0.3.

Right-click in the "Database Navigator" menu in the main view and select Create > Connection:

DBeaver Add Server

In the search bar of the "Connect to a database" window that opens up, type "mysql", select the MySQL driver, and click "Next":

DBeaver Select Driver

In the newly-opened "Connection Settings" tab, use the Host as localhost and Port as the one returned by the proxy command (62652 in the example above):

DBeaver Select Configure Server

In that same tab, set the username to match the one that you are connecting to using Teleport and uncheck the "Save password locally" box:

DBeaver Select Configure User

Click the "Edit Driver Settings" button on the "Main" tab, check the "No Authentication" box, and click "Ok" to save:

DBeaver Driver Settings

Once you are back in the "Connection Settings" window, click "Ok" to finish and DBeaver should connect to the remote MySQL server automatically.

MongoDB Compass

Compass is the official MongoDB graphical client.

On the "New Connection" panel, click on "Fill in connection fields individually".

MongoDB Compass new connection

On the "Hostname" tab, enter the hostname and port of the proxy you will use to access the database (see Get connection information). Leave "Authentication" as None.

MongoDB Compass hostname

On the "More Options" tab, set SSL to "Client and Server Validation" and set the CA as well as the client key and certificate. Note that a CA path must be provided and be able to validate the certificate presented by your Teleport Proxy Service's web endpoint.

MongoDB Compass more options

Click on the "Connect" button.

SQL Server DBeaver

In the DBeaver connection configuration menu, use your proxy's endpoint. This is localhost:62652 in the example above. (See Get connection information for more information.)

Use the SQL Server Authentication option and keep the Password field empty:

DBeaver connection options

Click OK to connect.

SQL Server DataGrip

In the DataGrip connection configuration menu, use your proxy's endpoint. This is localhost:4242 in the example below. (See Get connection information for more information.)

Select the "User & Password" authentication option and keep the "Password" field empty:

DataGrip connection options

Click "OK" to connect.

Redis Insight

Note

Teleport's Redis Insight integration only supports Redis standalone instances.

After opening Redis Insight click ADD REDIS DATABASE.

Redis Insight Startup Screen

Log in to your Redis instance with a Redis user first by using:

tsh db login --db-user=alice redis-db-name.

Click Add Database Manually. Use 127.0.0.1 as the Host. Use the port printed by the tsh command you ran in Get connection information.

Provide your Redis username as Username and password as Password.

Redis Insight Configuration

Next, check the Use TLS and Verify TLS Certificates boxes and copy the CA certificate returned by tsh proxy db. Copy the private key and certificate to corresponding fields.

Click Add Redis Database.

Redis Insight TLS Configuration

Congratulations! You have just connected to your Redis instance.

Redis Insight Connected