Microsoft SQL Server access with PKINIT authentication (Preview)

This guide will help you to:

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

This guide will focus on SQL Servers using self-hosted 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 with network access to an Active Directory installation and kinit command with PKINIT extensions installed:

  • Ubuntu
  • RHEL / CentOS 7

  sudo apt-get update
  sudo apt-get -y install krb5-user krb5-pkinit

  sudo yum -y update
  sudo yum -y install krb5-workstation krb5-pkinit

• Make sure you can 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  13.0.3
  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.

Step 1/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 2/7. Configure a GPO to allow Teleport connections

We need to configure a GPO to allow Teleport database sessions. This includes telling your computers to trust Teleport's CA and allowing certificate-based smart card authentication.

Export Teleport CA and CRL

1. Get the Teleport database CA certificate by running:

   tctl auth export --type=db-der > db-ca.cer

2. Get the Teleport database CRL by running:

   tctl auth crl --type=db > db-ca.crl

3. Transfer the db-ca.cer and db-ca.crl files to a Windows machine where you can manage your group policy.

Create a GPO and import the Teleport CA

1. Create a GPO named Teleport DB Access.

   $GPOName="Teleport DB Access"
   New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
   

2. Open the Group Policy Management program, and on the left pane, navigate to $FOREST > Domains > $DOMAIN > Group Policy Objects.

3. Right click on the GPO you just made (Teleport DB Access), and select Edit....

4. In the group policy editor, select:

   Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
   

5. Right click on Trusted Root Certification Authorities and select Import.

6. Click through the wizard, selecting your CA file (db-ca.cer).

Enable smart card service

Teleport performs certificate-based authentication by emulating a smart card.

1. Still editing your Teleport DB Access, select:

   Computer Configuration > Policies > Windows Settings > Security Settings > System Services
   

2. Double click on Smart Card, select Define this policy setting and switch to Automatic then click OK.

Publish the Teleport CA

This step enables the domain controllers to trust the Teleport CA, which will allow smart card logins via Teleport to succeed.

On a machine that is joined to your domain and logged in as an account in the Domain Administrators group, run the two commands below at a PowerShell prompt to publish the Teleport CA to your Active Directory domain (using the path to the exported Teleport db-ca.cer file that you copied above):

certutil –dspublish –f <PathToCertFile.cer> RootCA
certutil -dspublish -f <PathToCertFile.cert> NTAuthCA

Publish the Teleport CRL

On the same machine, run the command below at a PowerShell prompt to publish the Teleport CRL to your Active Directory domain (using the path to the exported db-ca.crl file that you copied above).

certutil -dspublish -f <PathToCRLFile.crl> TeleportDB

certutil -pulse

Step 3/7. Export the LDAP CA certificate

Teleport uses LDAPS to authenticate users, which requires specifying the LDAP CA certificate on the database configuration. To ensure that Teleport trusts the certificate sent by the server during the initial SSL connection, you must export the certificate from your AD. You can export the certificate by running the following PowerShell script on your Windows instance:

$WindowsDERFile = $env:TEMP + "\windows.der"
$WindowsPEMFile = $env:TEMP + "\windows.pem"
certutil "-ca.cert" $WindowsDERFile 
certutil -encode $WindowsDERFile $WindowsPEMFile

$CA_CERT_PEM = Get-Content -Path $WindowsPEMFile
Write-Output $CA_CERT_PEM

Remove-Item $WindowsDERFile -Recurse
Remove-Item $WindowsPEMFile -Recurse

The script will write the LDAP CA contents in PEM format to the terminal, and from there, you can copy and use it on your database configuration.

Step 4/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:

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 v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| 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 v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/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

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
Install teleport
sudo dnf 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

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

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 v13. You'll need to update this
file for each major release of Teleport.
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v13" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport-ent

sudo apt-get install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
sudo yum install teleport-ent
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

sudo yum install teleport-ent-fips

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v13. You'll need to update this
file for each major release of Teleport.
Use the dnf config manager plugin to add the teleport RPM repo
sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v13/teleport.repo")"
Install teleport
sudo dnf install teleport-ent
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

sudo dnf install teleport-ent-fips

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

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

Copy the join token to a file on the instance where you will run the Database Service, and then use the following configuration, replacing the fields on the database section below as appropriate:

• uri: The server address, including the port.
• domain: The Active Directory domain (Kerberos realm) DNS/Address to which SQL Server is joined.
• spn: Service Principal Name (SPN) for SQL Server to fetch Kerberos tickets.
• kdc_host_name: SPN of the domain controller responsible for providing the LDAP CA.
• ldap_cert: The contents of the LDAP CA previously exported.

version: v3
teleport:
  auth_token: abcd123-insecure-do-not-use-this
  proxy_server: teleport.example.com:443

auth_service:
  enabled: no
ssh_service:
  enabled: no
proxy_service:
  enabled: no

db_service:
  enabled: "yes"
  databases:
    - name: my-sqlserver
      protocol: sqlserver
      uri: SQL-SERVER-INSTANCE.ad.teleport.dev:1433
      ad:
        domain: ad.teleport.dev
        spn: MSSQLSvc/SQL-SERVER-INSTANCE.ad.teleport.dev:1433
        kdc_host_name: DOMAIN-CONTROLLER.ad.teleport.dev
        ldap_cert: |
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----

Step 5/7. Start the Database Service

Start the Database Service:

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

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

tsh proxy db --db-user=teleport --tunnel sqlserver

To log out of the database and remove credentials:

tsh db logout sqlserver

Troubleshooting

Teleport CA and CRL not imported correctly

When connecting to your database, you get an error Error message: authentication failed and Teleport Database Service logs have the error message Failed to authenticate with KDC: kinit: Client not trusted while getting initial credentials. This happens when the Teleport Database CA is not imported correctly or propagated yet. You can force the propagation by running certutil -pulse and trying to connect to your database.

Invalid KDC hostname

If you’re connecting to your database and receive the error Error message: authentication failed and on Teleport Database Service logs, there is the error entry Failed to authenticate with KDC: Password for [email protected]: \nkinit: Cannot read password while getting initial credentials, which means that the KDC hostname is wrong. You can verify your domain controller’s SPN to see if they’re set correctly and update the value on the field kdc_hostname on your database's configuration.

Teleport cannot verify database CA

If your database has a CA that Teleport doesn’t know about, it will return the following error when connecting to it: Error message: TLS Handshake failed: x509: certificate signed by unknown authority (possibly because of "x509: invalid signature: parent certificate cannot sign this kind of certificate" while trying to verify candidate authority certificate "SSL_Self_Signed_Fallback").

To solve this, you can add the following configuration to your Teleport Database Service instance:

...
db_service:
  databases:
    - name: sqlserver
      protocol: sqlserver
+     tls:
+       # Point it to your Database CA PEM certificate.
+       ca_cert_file: "rdsca.pem"
+       # If your database certificate has an empty CN filed, you must change
+       # the TLS mode to only verify the CA.
+       mode: verify-ca
      ad:
       ...

If you’re unable to acquire the database CA, you can skip TLS verification by providing the configuration tls.mode: "insecure". However, we do not recommend skipping TLS verification in production environments.

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

• Kerberos PKINIT authentication.