Teleport

Database Access with Azure PostgreSQL and MySQL

Database access for Azure PostgreSQL/MySQL is available starting from Teleport 8.1.

This guide will help you to:

Install and configure Teleport.
Set up access to Azure Database for PostgreSQL or Azure Database for MySQL.
Connect to the database server through Teleport.

Note

Teleport uses Azure Active Directory authentication with Azure PostgreSQL and MySQL databases which at the moment of this writing is only supported by Single Server. Flexible Server does not support Azure AD authentication.

Prerequisites

Deployed Azure Database for PostgreSQL or MySQL server.
Azure Active Directory administrative privileges.
A host, e.g., an Azure VM instance, where you will run the Teleport Database Service.

The tsh client tool version >= 9.2.4.
```
tsh version
Teleport v9.2.4 go1.17
```
See Installation for details.
A host where you will install the Teleport Auth Service and Proxy Service.
A registered domain name.

The tsh client tool version >= 9.2.4, which you can download by visiting the customer portal.
```
tsh version
Teleport v9.2.4 go1.17
```
A host where you will install the Teleport Auth Service and Proxy Service.
A registered domain name.

The tctl and tsh client tools version >= 9.2.4.

You can download these from Teleport Cloud Downloads.
```
tctl version
Teleport v9.2.4 go1.17
tsh version
Teleport v9.2.4 go1.17
```

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.2.4
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.2.4
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Step 1/4. Install and configure Teleport

Set up the Teleport Auth and Proxy Services

On the host where you will run the Auth Service and Proxy Service, 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's ACME protocol. Before Let's Encrypt can issue a TLS certificate for the Teleport Proxy host's domain, the ACME protocol must verify that an HTTPS server is reachable on port 443 of the host.

You can configure the Teleport Proxy service to complete the Let's Encrypt verification process when it starts up.

Run the following teleport configure command, where tele.example.com is the domain name of your Teleport cluster and [email protected] is an email address used for notifications (you can use any domain):

teleport configure --acme [email protected] --cluster-name=tele.example.com > /etc/teleport.yaml

The --acme, --acme-email, and --cluster-name flags will add the following settings to your Teleport configuration file:

proxy_service:
  enabled: "yes"
  web_listen_addr: :443
  public_addr: tele.example.com:443
  acme:
    enabled: "yes"
    email: [email protected]

Port 443 on your Teleport Proxy Service host must allow traffic from all sources.

Next, start the Teleport Auth and Proxy Services:

sudo teleport start

You will run subsequent tctl commands on the host where you started the Auth and Proxy Services.

If you do not have a Teleport Cloud account, use our signup form to get started. Teleport Cloud manages instances of the Proxy Service and Auth Service, and automatically issues and renews the required TLS certificate.

You must log in to your cluster before you can run tctl commands.

tsh login --proxy=mytenant.teleport.sh
tctl status

Set up the Teleport Database Service

The Database Service requires a valid auth token to connect to the cluster. Generate one by running the following command against your Teleport Auth Service and save it in /tmp/token on the node that will run the Database Service:

tctl tokens add --type=db

Install Teleport on the host where you will run the Teleport Database Service:

Download Teleport's PGP public key
sudo curl https://deb.releases.teleport.dev/teleport-pubkey.asc \  -o /usr/share/keyrings/teleport-archive-keyring.asc
Add the Teleport APT repository
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] https://deb.releases.teleport.dev/ stable main" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

sudo yum-config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
sudo yum install teleport
Optional:  Using DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

curl https://get.gravitational.com/teleport-v9.2.4-linux-amd64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.2.4-linux-amd64-bin.tar.gz
shasum -a 256 teleport-v9.2.4-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.2.4-linux-amd64-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-v9.2.4-linux-arm-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.2.4-linux-arm-bin.tar.gz
shasum -a 256 teleport-v9.2.4-linux-arm-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.2.4-linux-arm-bin.tar.gz
cd teleport
sudo ./install

curl https://get.gravitational.com/teleport-v9.2.4-linux-arm64-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://get.gravitational.com/teleport-v9.2.4-linux-arm64-bin.tar.gz
shasum -a 256 teleport-v9.2.4-linux-arm64-bin.tar.gz
Verify that the checksums match
tar -xzf teleport-v9.2.4-linux-arm64-bin.tar.gz
cd teleport
sudo ./install

Start the Teleport Database Service. Make sure to update --auth-server to point to your Teleport Proxy Service address and --uri to the Azure database server endpoint.

teleport db start \  --token=/tmp/token \  --auth-server=teleport.example.com:3080 \  --name=azure-db \  --protocol=postgres \  --uri=example.postgres.database.azure.com:5321 \  --labels=env=dev

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

Tip

You can start the Teleport Database Service using a configuration file instead of CLI flags. See the YAML reference.

Create a Teleport user

Create a local Teleport user with the built-in access role:

tctl users add \  --roles=access \  --db-users=\* \  --db-names=\* \  alice

Flag	Description
`--roles`	List of roles to assign to the user. The builtin `access` role allows them to connect to any database server registered with Teleport.
`--db-users`	List of database usernames the user will be allowed to use when connecting to the databases. A wildcard allows any user.
`--db-names`	List of logical databases (aka schemas) the user will be allowed to connect to within a database server. A wildcard allows any database.

Warning

Database names are only enforced for PostgreSQL and MongoDB databases.

For more detailed information about database access controls and how to restrict access see RBAC documentation.

Step 2/4. Configure Azure service principal

To authenticate with PostgreSQL or MySQL databases, Teleport Database Service needs to obtain access tokens from Azure AD. There are a couple of ways to achieve that:

The Database Service can be registered as an Azure AD application (via AD's "App registrations") and configured with its credentials. This is only recommended for development and testing purposes since it requires Azure credentials to be present in the Database Service's environment.
The Database Service can run on an Azure VM with attached managed identity. This is the recommended way of deploying the Database Service in production since it eliminates the need to manage Azure credentials.

Go to the Managed Identities page in your Azure portal and click Create to create a new user-assigned managed identity:

Pick a name and resource group for the new identity and create it:

Take note of the created identity's Client ID:

Next, navigate to the Azure VM that will run your Database Service agent and add the identity you've just created to it:

Attach this identity to all Azure VMs that will be running the Database Service.

Note

Registering the Database Service as Azure AD application is suitable for test and development scenarios, or if your Database Service does not run on an Azure VM. For production scenarios prefer to use the managed identity approach.

Go the the App registrations page of your Azure Active Directory and click on New registration:

Pick a name (e.g. DatabaseService) and register a new application. Once the app has been created, take note of its Application (client) ID and click on Add a certificate or secret:

Create a new client secret that the Database Service agent will use to authenticate with the Azure API:

The Teleport Database Service uses Azure SDK's default credential provider chain to look for credentials. Refer to Authentication methods to pick a method suitable for your use-case. For example, to use environment-based authentication with a client secret, the Database Service should have the following environment variables set:

export AZURE_TENANT_ID=
export AZURE_CLIENT_ID=
export AZURE_CLIENT_SECRET=

Step 3/4. Create Azure database users

To let Teleport connect to your Azure database authenticating as a service principal, you need to create Azure AD users for that principal in the database.

Assign Azure AD administrator

Only the Azure AD administrator for the database can connect to it and create Azure AD users. Go to your database's Active Directory admin page and set the AD admin using the Set admin button:

Note that only one AD user can be set as an admin for the database.

Connect to the database as an AD admin

Next, you need to connect to your database as the AD admin user.

Use the Azure az CLI utility to log in as the user that you set as the AD admin, fetch the access token and use it as a password when connecting to the database:

az login -u [email protected]
export PGPASSWORD=`az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken`
psql "host=example.postgres.database.azure.com [email protected]@instance-name sslmode=require dbname=postgres"

az login -u [email protected]
export TOKEN=`az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken`
mysql -h example.mysql.database.azure.com -P 3306 -u [email protected]@instance-name --enable-cleartext-plugin --password=$TOKEN

Note that the database username must include @instance-name suffix with the name of the Azure database instance you're connecting to.

Create AD users

Once connected to the database as AD admin, create database users for the service principal that Teleport Database Service will be using. Use Client ID when using managed identities and Application (client) ID when using app registrations:

postgres=> SET aad_validate_oids_in_tenant = off;
SET
postgres=> CREATE ROLE teleport WITH LOGIN PASSWORD '11111111-2222-3333-4444-555555555555' IN ROLE azure_ad_user;
CREATE ROLE

mysql> SET aad_auth_validate_oids_in_tenant = OFF;
mysql> CREATE AADUSER 'teleport' IDENTIFIED BY '11111111-2222-3333-4444-555555555555';
Query OK, 0 rows affected (0.92 sec)

You can create multiple database users for the same service principal.

Step 4/4. Connect

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name     Description         Labels
-------- ------------------- -------
azure-db                     env=dev

Fetch a short-lived client certificate for your Azure database using the tsh db login command:

tsh db login --db-user=teleport azure-db

Tip

You can be logged in to multiple databases simultaneously.

Now connect to the database:

tsh db connect azure-db

Note

The appropriate database command-line client (psql, mysql) should be available in the PATH of the machine you're running tsh db connect from.

To log out of the database and remove credentials:

tsh db logout azure-db

Next steps

Learn how to restrict access to certain users and databases.
View the High Availability (HA) guide.
Take a look at the YAML configuration reference.
See the full CLI reference.

Have a suggestion or can’t find something?

IMPROVE THE DOCS