Database Access with Azure PostgreSQL and MySQL

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.

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.

Step 1/5. Install and configure Teleport

Set up the Teleport Auth and Proxy Services

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

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

sudo teleport start

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

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

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:

Next, use the appropriate commands for your environment to install your package.

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v11. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v11" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v11. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v11/teleport.repo")
sudo yum install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Optional:  Use 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-v11.3.2-linux-
-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v11.3.2-linux-
-bin.tar.gz
shasum -a 256 teleport-v11.3.2-linux-
-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v11.3.2-linux-
-bin.tar.gz
cd teleport
sudo ./install

dpkg -i ~/Downloads/teleport-ent_11.3.2_
.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_11.3.2_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 11.3.2 ...
Setting up teleport-ent 11.3.2 ...

rpm -i ~/Downloads/teleport-ent-11.3.2.
.rpm
warning: teleport-ent-11.3.2.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.3.2-linux-
-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v11.3.2-linux-
-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.2-linux-
-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v11.3.2-linux-
-bin.tar.gz
cd teleport-ent
sudo ./install

curl https://get.gravitational.com/teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
shasum -a 256 teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v11.3.2-linux-
-fips-bin.tar.gz
cd teleport-ent
sudo ./install

dpkg -i ~/Downloads/teleport-ent_11.2.1_
.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_11.2.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 11.2.1 ...
Setting up teleport-ent 11.2.1 ...

rpm -i ~/Downloads/teleport-ent-11.2.1.
.rpm
warning: teleport-ent-11.2.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v11.2.1-linux-
-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
shasum -a 256 teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v11.2.1-linux-amd64-bin.tar.gz
cd teleport-ent
sudo ./install

Create the Database Service configuration, specifying a region like this:

teleport db configure create \  -o file \  --proxy=tele.example.com:443 \  --token=/tmp/token \  --azure-postgres-discovery=eastus

teleport db configure create \  -o file \  --proxy=teleport.example.com:3080 \  --token=/tmp/token \  --azure-mysql-discovery=eastus

The command will generate a Database Service configuration with Azure MySQL/Postgres database auto-discovery enabled in the eastus region and place it at the /etc/teleport.yaml location.

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

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

Step 2/5. 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 for the Teleport Database Service to access Azure resources:

• 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.
• 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.

export AZURE_TENANT_ID=
export AZURE_CLIENT_ID=
export AZURE_CLIENT_SECRET=

Step 3/5. Configure IAM permissions for Teleport

Create a custom role

Teleport needs Azure IAM permissions to discover and register MySQL and PostgreSQL databases. Create a role with assignable scope(s) that include all databases that Teleport should discover. For example:

{
    "properties": {
        "roleName": "TeleportDiscovery",
        "description": "Allows Teleport to discover MySQL and PostgreSQL databases",
        "assignableScopes": [
            "/subscriptions/11111111-2222-3333-4444-555555555555"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.DBforMySQL/servers/read",
                    "Microsoft.DBforPostgreSQL/servers/read"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

This role definition allows Teleport to discover MySQL and PostgreSQL databases, but Teleport only needs permissions for the database types you have. The assignable scopes include a subscription, so the role can be assigned at any resource scope within that subscription, or assigned using the subscription scope itself.

Go to the Subscriptions page and select a subscription.

Click on Access control (IAM) in the subscription and select Add > Add custom role:

In the custom role creation page, click the JSON tab and click Edit, then paste the JSON example and replace the subscription in "assignableScopes" with your own subscription id:

Create a role assignment for the Teleport Database Service principal.

To grant Teleport permissions, the custom role you created must be assigned to the Teleport service principal - either the managed identity or the app registration you created earlier.

Navigate to the resource scope where you want to make the role assignment. Click Access control (IAM) and select Add > Add role assignment. Choose the custom role you created as the role and the Teleport service principal as a member.

Step 4/5. Create Azure database users

To let Teleport connect to your Azure database authenticating as a service principal, you need to create Azure AD users authenticated by 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:

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)

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

You can create multiple database users identified by the same service principal.

Step 5/5. Connect

Log in to your Teleport cluster. Your Azure database should appear in the list of available databases:

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

To retrieve credentials for a database and connect to it:

tsh db connect --db-user=teleport azure-db

To log out of the database and remove credentials:

tsh db logout azure-db

Troubleshooting

No credential providers error

If you see the error DefaultAzureCredential: failed to acquire a token. in Database Service logs then Teleport is not detecting the required credentials to connect to the Azure SDK. Check whether the credentials have been applied in the machine running the Teleport Database Service and restart the Teleport Database Service. Refer to Azure SDK Authorization for more information.

Timeout errors

The Teleport Database Service needs connectivity to your database endpoints. That may require enabling inbound traffic on the database from the Database Service on the same VPC or routing rules from another VPC. Using the nc program you can verify connections to databases:

nc -zv server-name.postgres.database.azure.com 5432
Connection to server-name.postgres.database.azure.com 5432 port [tcp/postgresql] succeeded!

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.