Database Access with SQL Server on Azure (Preview)

This guide will help you to:

• Install and configure Teleport.
• Set up access to Azure SQL Server using Azure Active Directory authentication.
• Connect to Azure SQL Server through Teleport.

Prerequisites

• SQL Server running on Azure.
• The Teleport Database Service running on an Azure virtual instance.

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

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

Step 1/8. 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/8. Enable the SQL Server Azure Active Directory integration

If you have it enabled, you can go to the next step.

Go to the Azure Portal, select Database servers, and select the database you wish to enable the Azure Active Directory integration.

Select Azure Active Directory in the left-hand column.

Select Set Admin, and choose an account that will be added as an admin login to SQL Server.

Step 3/8. Configure IAM permissions for Teleport

The Teleport Database Service needs Azure IAM permissions to:

• Discover and register SQL Server instances.
• Fetch virtual machine managed identities used for login.

Configure an Azure service principal

Teleport requires the following permissions:

• <resource-type>/read permissions for discovery, but only for the resource types you have. For example, Microsoft.Sql/managedInstances/read.
• Microsoft.Compute/virtualMachines/read.

Here is a sample role definition allowing Teleport to read Azure SQL Servers and Azure SQL Managed Instances:

{
    "properties": {
        "roleName": "SQLServerAutoDiscovery",
        "description": "Allows Teleport to discover SQL Servers and SQL Managed Instances.",
        "assignableScopes": [
            "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Sql/managedInstances/read",
                    "Microsoft.Sql/servers/read",
                    "Microsoft.Compute/virtualMachines/read"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

The assignableScopes field above includes a subscription (/subscriptions/<subscription>), allowing the role to be assigned at any resource scope within that subscription or the subscription scope itself. If you want to further limit the assignableScopes, you can use a resource group (/subscriptions/<subscription>/resourceGroups/<group>) or a management group (/providers/Microsoft.Management/managementGroups/<group>) instead.

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:

Step 4/8. Configure virtual machine identities

In the Teleport Database Service virtual machine's Identity section, enable the system assigned identity. This is used by Teleport to access Azure APIs.

To grant Teleport permissions, the custom role you created must be assigned to the virtual machine system assigned identity. On the same page, click on the Azure role assignments, then on Add role assignment. Select the custom role and save.

Login identities

The Teleport Database Service needs access tokens from Azure AD to authenticate with SQL Server databases.

It uses the managed identities attached to its Virtual Machine to fetch the authentication token.

To create a new user-assigned managed identity, go to the Managed Identities page in your Azure Portal and click on Create. Choose a name and resource group for it and create:

Next, go to the Teleport Database Service virtual machine instance, Identity section, select User assigned, and add the identity we just created:

Step 5/8. Enable managed identities login on SQL Server

Azure AD SQL Server integration uses database-level authentication (contained users), meaning we must create a user for our identities on each database we want to access.

To create contained users for the identities, connect to your SQL server using its Activity Directory Admin and execute the query:

USE MyDatabase;
CREATE USER [sqlserver-identity] FROM EXTERNAL PROVIDER;

The newly created user will be attached to the public role, which might not have enough permissions to perform queries. Consider granting individual permissions to the user or assigning it to an existing role. For example, add the user as a member of the db_datareader role:

ALTER ROLE db_datareader ADD MEMBER [sqlserver-identity];

Step 6/8. Create a Database Service configuration

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

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 v12. 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/v12" \| 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 v12. 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/v12/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-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

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

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

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

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

Generate a configuration file at /etc/teleport.yaml for the Database Service:

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

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

Step 7/8. Start Teleport Database Service

Start the Database Service:

teleport start --config=/etc/teleport.yaml

Step 8/8. Connect

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

tsh login --proxy=teleport.example.com --user=alice
tsh db ls
Name                Description                       Allowed Users Labels Connect
------------------ ---------------------------------- ------------- ------ -------
sqlserver          Azure SQL Server in westeurope     [*]           ...
sqlserver-managed  Azure Managed SQL Server in eastus [*]           ...

To retrieve credentials for a database and connect to it:

tsh db connect --db-user=sqlserver-identity --db-name=master sqlserver

Where --db-user is the managed identity name.

Troubleshooting

Could not find identity

If you see the error could not find identity "my-identity" attached to the instance when connecting to your database, then the identity you’re trying to connect with is not attached to the Teleport Database Service virtual machine. You can navigate to the Virtual Machines page within Azure Portal, open the Teleport instance, Identity section, and choose User assigned to see all identities you can connect with. If you don’t see your identity check Step 4 to see how to add it.

Login failed for the user

When connecting to your database, and you see the error mssql: login error: Login failed for user '<token-identified principal>', it means your managed identity login is not present on the SQL database. You’ll need to create their users as described in Step 6. Remember: you must create the users on all databases you want to connect.

Timeout connecting to the database

If you receive the error i/o timeout issue when connecting to your database, please check if the Teleport Database service can reach the database on Azure.

In case your database is public, you can enable it to receive connections from Azure services without creating firewall rules: Go to your database page, Network tab, and at the bottom of the page in the Exceptions section check the option "Allow Azure services and resources to access this server" and save.

If your database is not public and it is using private endpoints, ensure that they're on the same VPC, or if the Teleport VM VPC is peering with the database one.

To check if the VM has access, you can do the following on the VM:

• Using netcat: nc -v yourdatabase.database.windows.net 1433
• Using telnet: telnet yourdatabase.database.windows.net 1433

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.