Fork me on GitHub
Teleport

Database Access with Self-Hosted MySQL

Self-Hosted MySQL

Create Certificate/Key Pair

Teleport uses mutual TLS authentication with self-hosted databases. As such, they must be configured with Teleport's certificate authority to be able to verify client certificates and a certificate/key pair that Teleport can verify.

With self-hosted version of Teleport use tctl auth sign command locally on the Teleport Auth server to produce the secrets

Create the secrets:

Export Teleport's certificate authority and generate certificate/key pair

for host db.example.com with a 3-month validity period.

tctl auth sign --format=db --host=db.example.com --out=server --ttl=2190h
TTL
We recommend using shorter TTL but keep mind that you'll need to update the database server certificate before it expires to not lose the ability to connect, so pick the TTL value that best fits your use-case.

The command will create 3 files: server.cas, server.crt and server.key which you'll need to enable mutual TLS on your MySQL server.

Configure MySQL Server

To configure MySQL server to accept TLS connections, add the following to MySQL configuration file mysql.cnf:

[mysqld]
require_secure_transport=ON
ssl-ca=/path/to/server.cas
ssl-cert=/path/to/server.crt
ssl-key=/path/to/server.key

Additionally, MySQL database user accounts must be configured to require a valid client certificate:

CREATE USER 'alice'@'%' REQUIRE X509;
ALTER USER 'alice'@'%' REQUIRE X509;

By default the created user may not have access to anything and won't be able to connect so let's grant it some permissions:

GRANT ALL ON `%`.* TO 'alice'@'%';

See Configuring MySQL to Use Encrypted Connections in MySQL documentation for more details.

Setup Teleport Auth and Proxy Services

Teleport Database Access for MySQL is available starting from 6.0 release.

Download the latest version of Teleport for your platform from our downloads page and follow the installation instructions.

Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt ACME protocol. We will assume that you have configured DNS records for teleport.example.com and *.teleport.example.com to point to the Teleport node.

Generate Teleport config with ACME enabled:

$ teleport configure --cluster-name=teleport.example.com --acme [email protected] -o file
Web Proxy Port
Teleport uses TLS-ALPN-01 ACME challenge to validate certificate requests which only works on port 443. As such, in order to use ACME for certificate management, web proxy needs to be accessible on port 443.

Start Teleport Auth and Proxy services:

$ sudo teleport start

Database service requires a valid auth token to connect to the cluster. Generate one and save it in /tmp/token:

$ tctl tokens add --type=db

Create Role and User

Create the role that will allow a user to connect to any database using any database account:

tctl --config=/path/to/teleport-db-role.yaml create <<EOF
kind: role
version: v4
metadata:
  name: db
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
    - '*'
    db_users:
    - '*'
EOF

Create the user assigned the db role we've just created:

tctl --config=/path/to/teleport-db-role.yaml users add --roles=admin,db testuser

Start Database Service with CLI Flags

For a quick try-out, Teleport database service doesn't require a configuration file and can be launched using a single CLI command:

teleport db start \ --token=/tmp/token \ --auth-server=teleport.example.com:3080 \ --name=test \ --protocol=mysql \ --uri=mysql.example.com:3306 \ --labels=env=dev

Note that the --auth-server flag must point to the Teleport cluster's proxy endpoint because database service always connects back to the cluster over a reverse tunnel.

Start Database Service with Config File

Below is an example of a database service configuration file that proxies a single self-hosted MySQL database:

teleport:
  # The data_dir should be a different location if running on the same
  # machine as Teleport auth and proxy.
  data_dir: /var/lib/teleport-db
  nodename: teleport-db-instance
  # Teleport invitation token used to join a cluster.
  # can also be passed on start using --token flag
  auth_token: /tmp/token
  # Proxy address to connect to. Note that it has to be the proxy address
  # because database service always connects to the cluster over reverse
  # tunnel.
  auth_servers:
  - teleport.example.com:3080
db_service:
  enabled: "yes"
  # This section contains definitions of all databases proxied by this
  # service, can contain multiple items.
  databases:
    # Name of the database proxy instance, used to reference in CLI.
  - name: "example"
    # Free-form description of the database proxy instance.
    description: "Example MySQL"
    # Database protocol.
    protocol: "mysql"
    # Database address, MySQL server endpoint in this case.
    #
    # Note: this URI's hostname must match the host name specified via --host
    # flag to tctl auth sign command.
    uri: "mysql.example.com:3306"
    # Labels to assign to the database, used in RBAC.
    static_labels:
      env: dev
auth_service:
  enabled: "no"
ssh_service:
  enabled: "no"
proxy_service:
  enabled: "no"
Tip
A single Teleport process can run multiple different services, for example multiple database access proxies as well as running other services such an SSH service or an application access proxy.

Start the database service:

teleport start --config=/path/to/teleport-db.yaml --token=/tmp/token

Connect

Once the database service has joined the cluster, login to see the available databases:

tsh login --proxy=teleport.example.com --user=testuser
tsh db ls

Name Description Labels

------- ------------- --------

example Example MySQL env=dev

Note that you will only be able to see databases your role has access to. See RBAC section for more details.

To connect to a particular database server, first retrieve credentials from Teleport using tsh db login command:

tsh db login example
Tip
You can be logged into multiple databases simultaneously.

You can optionally specify the database name and the user to use by default when connecting to the database instance:

tsh db login --db-user=root --db-name=mysql example

Once logged in, connect to the database:

tsh db connect example
Note
The mysql command-line client should be available in PATH in order to be able to connect.

If you would like to see the native mysql shell connect command, run:

tsh db config --format=cmd example

To log out of the database and remove credentials:

Remove credentials for a particular database instance.

tsh db logout example

Remove credentials for all database instances.

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