Fork me on GitHub
Teleport

Database Access GUI Clients

Graphical Database Clients

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

Obtain local certificate/key-pair

Issue the following command after you login with tsh:

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 PEM files:

Name:      example
Host:      teleport.example.com
Port:      3036
User:      alice
Database:
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, enter the default database name (the maintenance database) and the connection service name (the same one that you specify when connecting through psql). Leave all the other fields blank:

pgAdmin Connection

In the "SSL" tab, set "SSL Mode" to Verify-Full:

pgAdmin SSL

Click "Save", and pgAdmin should immediately connect.

Note

On a Windows client, use terminal to export a PG Service File env variable:

$ setx PGSERVICEFILE <path_to_.pg_service.conf_file>

Restart the pgAdmin client.

MySQL Workbench

MySQL Workbench is a visual tool that provides comprehensive MySQL administration and SQL development tools.

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

MySQL Workbench\nParameters

In the "SSL" tab, set "Use SSL" to Require and Verify Identity and enter paths to your CA, certificate, and private key files from tsh db config command:

MySQL Workbench SSL

Optionally, click "Test Connection" to verify connectivity:

MySQL Workbench Test

Save the connection, and connect to the database.

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 your Teleport proxy's hostname and port shown by tsh db config. Leave "Authentication" as None.

MongoDB Compass hostname

On the "More Options" tab set SSL to "Client and Server Validation" and set CA as well as client key and certificate. Note the CA path must be provided and be able to validate certificate presented by your Teleport proxy's web endpoint. Client key and certificate locations are shown by tsh db config.

MongoDB Compass more options

Click on the "Connect" button.

DBeaver

DBeaver is a SQL client software application and database administration tool.

MySQL

Note
Teleport's DBeaver MySQL integration only supports MySQL server 8.0.3 or older.

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" Main tab copy the Server Host and Port from the tsh db config output into the DBeaver config fields:

DBeaver Select Configure Server

In that same tab set the username to match the one that you are connecting to using the Teleport db certs 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 navigate to the "Driver Properties" tab, scroll down to find the enabledTLSProtocols field and enter "TLSv1.2" into the Value field:

DBeaver TLS Settings

Navigate to the "SSL" tab, check the "Use SSL" box, uncheck the "Verify Server Certificates" box, and copy the CA Certificate, Client Certificate, and Client Private Key paths from the tsh db config output:

DBeaver SSL

Click "Ok" to finish and DBeaver should connect to the remote MySQL server automatically.

Have a suggestion or can’t find something?
IMPROVE THE DOCS