Database Access with Microsoft SQL Server with Active Directory authentication (Preview)

This guide will help you to:

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

This guide will focus on Amazon RDS for SQL Server using AWS-managed Active Directory authentication.

Prerequisites

• A SQL Server database with Active Directory authentication enabled.
• A SQL Server network listener configured with a Certificate using Subject Alternative Names
• A Windows machine joined to the same Active Directory domain as the database.
• A Linux node joined to the same Active Directory domain as the database. This guide will walk you through the joining steps if you don't have one.

Step 1/7. Set up the Teleport Auth and Proxy

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

Step 2/7. 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 3/7. Join the Linux node to Active Directory

The Linux node where the Database Service will run must be joined to the same Active Directory domain as the SQL Server database.

Note that in order to be able to join, the Linux node must be able to resolve your Active Directory fully-qualified domain name. For example, for AWS-managed AD, use nameservers provided under "Networking details" on the directory's overview page.

Install necessary packages:

sudo apt-get update
sudo apt-get -y install sssd realmd krb5-user samba-common packagekit adcli

sudo yum -y update
sudo yum -y install sssd realmd krb5-workstation samba-common-tools

Edit /etc/krb5.conf to disable reverse DNS resolution and set the default realm. Make sure that the [realms] section contains your domain definition and has admin_server and kdc fields set pointing to the domain controllers:

[libdefaults]
default_realm = EXAMPLE.COM
rdns = false

[realms]
  EXAMPLE.COM = {
    kdc = example.com
    admin_server = example.com
  }

Join the realm:

sudo realm join -v -U [email protected] example.com
...
 * Successfully enrolled machine in realm

To confirm the node has joined the realm, use the realm list command:

sudo realm list
example.com
  type: kerberos
  realm-name: EXAMPLE.COM
  domain-name: example.com
  configured: kerberos-member
  server-software: active-directory
  client-software: sssd
  ...

Step 4/7. Create keytab file

Teleport requires a keytab file to obtain Kerberos service tickets from your Active Directory for authentication with SQL Server. The easiest way to generate it is to use the adutil Linux CLI utility.

Install adutil on the Linux node you have joined to your Active Directory domain:

curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
sudo curl https://packages.microsoft.com/config/ubuntu/18.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y adutil

sudo wget -qO /etc/apt/trusted.gpg.d/microsoft.asc https://packages.microsoft.com/keys/microsoft.asc
sudo curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y adutil

sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/8/prod.repo
sudo ACCEPT_EULA=Y yum install -y adutil

Log in to Active Directory using the kinit command:

kinit [email protected]

Use the adutil keytab create command to generate keytab entries for each Active Directory user that will be connecting to the SQL Server database:

adutil keytab create teleport.keytab alice
adutil keytab create teleport.keytab bob

You will be prompted to enter each user's password. All keytab entries will be merged into the same teleport.keytab file.

setspn -L alice

setspn -s user/alice alice

You can verify entries in the keytab file using klist command:

klist -ke teleport.keytab
Keytab name: FILE:teleport.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   5 [email protected] (aes256-cts-hmac-sha1-96)
   2 [email protected] (aes256-cts-hmac-sha1-96)

Step 5/7. 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

Configure the Teleport Database Service. Make sure to update --proxy to point to your Teleport Proxy Service address and --uri to the SQL Server endpoint.

sudo teleport db configure create \  -o file \  --token=/tmp/token \  --proxy=teleport.example.com:443 \  --name=sqlserver \  --protocol=sqlserver \  --uri=sqlserver.example.com:1433 \  --ad-keytab-file=/path/to/teleport.keytab \  --ad-domain=EXAMPLE.COM \  --ad-spn=MSSQLSvc/sqlserver.example.com:1433 \  --labels=env=dev

Provide Active Directory parameters:

Service Principal Name

You can use ldapsearch command to see the SPNs registered for your SQL Server. Typically, they take a form of MSSQLSvc/<name>.<ad-domain>:<port>.

For example, an AWS RDS SQL Server named sqlserver and joined to an AWS managed Active Directory domain EXAMPLE.COM will have the following SPNs registered:

ldapsearch -x -h example.com -D admin -W -b DC=example,DC=com servicePrincipalName
...
EC2AMAZ-4KN05DU, RDS, AWS Reserved, example.com
dn: CN=EC2AMAZ-4KN05DU,OU=RDS,OU=AWS Reserved,DC=example,DC=com
servicePrincipalName: MSSQLSvc/sqlserver-rds.example.com:1433
servicePrincipalName: MSSQLSvc/EC2AMAZ-4KN05DU.example.com:1433
servicePrincipalName: MSSQLSvc/EC2AMAZ-4KN05DU.example.com
...

Alternatively, you can look SPNs up in the Attribute Editor of the Active Directory Users and Computers dialog on your AD-joined Windows machine. The RDS SQL Server object typically resides under the AWS Reserved / RDS path:

Step 6/8. Start the Database Service

Start the Database Service:

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

Step 7/8. Create SQL Server AD users

Connect to your SQL Server as an administrative account (e.g. sa) and create logins that will use Active Directory authentication:

master> CREATE LOGIN [EXAMPLE\alice] FROM WINDOWS WITH DEFAULT_DATABASE = [master], DEFAULT_LANGUAGE = [us_english];

Step 8/8. Connect

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

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

To retrieve credentials for a database and connect to it:

tsh db connect --db-user=teleport sqlserver

To log out of the database and remove credentials:

tsh db logout sqlserver

Troubleshooting

Certificate error

If your tsh db connect error includes the following text, the certificate used by SQL Server is not a known Certificate Authority.

Error message: TLS Handshake failed: x509: certificate signed by unknown authority

Add the Certificate Authority (CA) ca_cert_file into the tls section so Teleport can validate the certificate.

  databases:
  - name: sqlserver
    protocol: sqlserver
    uri: sqlserver.example.com:1433
    ad:
      keytab_file: /path/to/teleport.keytab
      domain: EXAMPLE.COM
      spn: MSSQLSvc/sqlserver.example.com:1433
    static_labels:
      "env": "dev"
    tls:
      ca_cert_file: /var/lib/teleport/cert.pem

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.

Further reading

• Manually join a Linux instance in the AWS documentation.
• Introduction to adutil in the Microsoft documentation.