🛡️ Intro

In this example, we'll secure access to a MySQL Database server using Border0.
For more info about Border0 and Databases, also see this video demo and blog.

We'll walk through the following steps together.

Launch a MySQL server (Docker)
Create a database socket and link it to our connector
Authenticate and Connect
Kill the session and watch the recording
Using the Border0 Desktop app to access your database
Troubleshooting

1 Run a local MySQL server with docker

You can make any MySQL database server available with Border0; for testing purposes, we'll use a MySQL Docker container as the server.

👍
It works through NAT and Firewalls
Don't worry if your laptop is behind NAT. Border0 works perfectly fine with resources that are behind NAT.

docker run --name some-mysql --rm -e MYSQL_ROOT_PASSWORD=my-secret-pw -d -p 3306:3306  mysql

This will start a local MySQL server listening on port 3306, with my-secret-pw as root password.
Before we continue, let's just make sure if it came up ok and test connecting to the database locally as user root and password my-secret-pw
mysql -u root -pmy-secret-pw -h localhost --protocol TCP

Once connected, you can do a query like the one below. If this works, you're all good to continue. Your local MySQL instance is working.

$ mysql -u root -pmy-secret-pw -h localhost  --protocol TCP
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 11
Server version: 8.0.30 MySQL Community Server - GPL

Copyright (c) 2000, 2021, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> SHOW VARIABLES LIKE 'version';
+---------------+--------+
| Variable_name | Value  |
+---------------+--------+
| version       | 8.0.30 |
+---------------+--------+
1 row in set (0.00 sec)

mysql>

2 - Create a database socket and link it to your connector.

Now that we have a working database for our example it's time to create a database socket and link it to our connector.

In the Sockets page, click on new Database socket
set a name and optionally a description

Upstream Configuration
here we can configure how your connector can connect and authenticate to the upstream database server.

Select standard for Service type
For authentication select username and password.
Protocol: MySQL since we're working with a MySQL server
For hostname and port we'll use localhost and port 3306. Adjust as needed for your environment.
Credentials, in our example we used root and my-secret-pw Adjust as needed for your environment.
Connector: Select your connector from the list

That's it, now click create new socket button. And you should have access to your MySQL database.

Now connect your newly created socket to the Border0 Platform. For example by clicking on the blue connect button, which will redirect you to our web based database client.

📘
Securing your credentials
In the preceding example, we configured Border0 with credentials to access an upstream database. These credentials are essential for the connector running in your environment to establish a secure connection. While Border0 stores these credentials in encrypted form, we strongly recommend that you keep them local to the connector.
You can have the Border0 connector integrated with your secret management solution for enhanced security and keep your secrets local. Learn more about this in our guide:
https://docs.border0.com/docs/using-secret-managers-to-store-credentials

By default, our proxy will try to establish a secure database connection using TLS. If the database server does not support TLS, it will fall back to a non-TLS connection.

For an even more secure connection, it's possible to specify the root CA to verify the server certificate (flag: upstream_ca_filename). And for certificate authentication, it is possible to use the flags upstream_certificate_filename and upstream_key_filename. To disable TLS, you can specify the --upstream_tls=false flag.

Troubleshooting

Should you see any issues with your new socket, it's typically because it can't connect to the upstream database. To troubleshoot that take a look at the connector logs as described here

3 - Using the Border0 client to connect to your database

The easiest way to connect to your database is the client portal. If you prefer the cli, then use the border0 CLI. From there, it's easy to discover all your databases and launch your preferred database client.

First, make sure you're logged in to your organization.

border0 client login

📘
Organization name
If this is your first time issuing a client login, it will ask you for an Organization name. The Organization name is the part between the socket name and -border0.io. ie. .-border0.io
After you have the organization name, then login with
border0 client login --org <orgname>
The next time you log in, we'll remember your organization name, and you can just log in with border0 client login

Then request the list of all databases you have access to and pick your preferred client. We currently support integration with these MySql clients:

mysql
mysqlworkbench
mycli
dbeaver
datagrip

If your favorite client is not listed, you can always follow this process and use a Local Listener. Which allows you to use any client.

border0 client db

Alternatively, you can connect directly, like: border0 client db:mysql --host mysqltest-<org>.border0.io
Or use any of the other supported built-in tools.

If you want to, you can connect directly using the MySQL client like this. The hostname and port number were printed when you created the socket. The key and cert file are created after executing the border0 client login command.

$ mysql -h mysqltest-andree-toonk.border0.io -P 24558 --protocol TCP \
         -u root \
        --ssl-cert=~/.border0/<org_id>.crt  \
        --ssl-key=~/.border0/<org_id>.key

4 - Kill the session and watch the recording

Go to the portal, and click on your database socket. Go to the sessions tab and kill your session.
Refresh the session's webpage, and now click watch recording.

5. Using the Border0 Desktop app to access your database

Using the Border0 Desktop App, you'll be able to quickly discover all services (sockets) you have access to as an end-user.
In the demo below, you can see how the app lists all Database resources. After we click on "connect", it asks the user which database client the user prefers and launches the client for the user.

Troubleshooting

Should you see any issues with your new socket, it's typically because it can't connect to the upstream database. To troubleshoot that take a look at the connector logs as described here

If that doesn't help resolve the issue, feel free to contact us, and we'd be happy to help you troubleshoot.