
Microsoft SQL Server access is currently in Preview mode.
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 running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 13.0.3.tctl versionTeleport v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.0.3, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
Please use the latest version of Teleport Enterprise documentation.
-
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:sudo apt-get updatesudo apt-get -y install krb5-user krb5-pkinitsudo yum -y updatesudo yum -y install krb5-workstation krb5-pkinit -
Make sure you can connect to Teleport. Log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster 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
To modify an existing user to provide access to the Database Service, see Database Access Access Controls
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. |
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/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
You will need to repeat these steps if you rotate Teleport's database certificate authority.
-
Get the Teleport database CA certificate by running:
tctl auth export --type=db-der > db-ca.cer -
Get the Teleport database CRL by running:
tctl auth crl --type=db > db-ca.crl -
Transfer the
db-ca.cer
anddb-ca.crl
files to a Windows machine where you can manage your group policy.
Create a GPO and import the Teleport CA
For the purposes of this guide, we apply the GPO we are about to create to our entire AD domain. In the case where you wish for only a subset of computers within your AD domain to be accessible via Teleport, you should apply the GPO to an OU that includes only these computers.
-
Create a GPO named
Teleport DB Access
.$GPOName="Teleport DB Access" New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
-
Open the
Group Policy Management
program, and on the left pane, navigate to$FOREST > Domains > $DOMAIN > Group Policy Objects
. -
Right click on the GPO you just made (
Teleport DB Access
), and selectEdit...
. -
In the group policy editor, select:
Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
-
Right click on
Trusted Root Certification Authorities
and selectImport
. -
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.
-
Still editing your
Teleport DB Access
, select:Computer Configuration > Policies > Windows Settings > Security Settings > System Services
-
Double click on
Smart Card
, selectDefine this policy setting
and switch toAutomatic
then clickOK
.

You will be modifying GPOs, and sometimes GPO modifications can take some time
to propagate to all hosts. You can force your changes to take effect
immediately on your current host at any time by opening a PowerShell prompt
and running gpupdate.exe /force
(though the effects of your changes may still take time to
propagate to other machines on the domain).
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
To avoid waiting until the certificate propagates, you can force the CA retrieval from LDAP after importing the CA and CRL with the command:
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.
Teleport Edition
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd 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 teleportTip: 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-releaseAdd 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 teleportTip: 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
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
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.gzshasum -a 256 teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzcd teleportsudo ./install
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport-ent
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo apt-get install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd 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-entTip: 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
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo yum install teleport-ent-fips
Source variables about OS version
source /etc/os-releaseAdd 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-entTip: 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
For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips
package instead:
sudo dnf install teleport-ent-fips
In the example commands below, update $SYSTEM_ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
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.gzshasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
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.gzshasum -a 256 teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v13.0.3-linux-$SYSTEM_ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
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-----
You can look SPNs up in the Attribute Editor of the Active Directory Users and Computers dialog on your AD-joined Windows machine.
If you don't see the Attribute Editor tab, make sure that the "View > Advanced Features" toggle is enabled.
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
You can skip this step if you already have Active Directory logins in your SQL Server.
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=alicetsh db lsName Description Labels
--------- ------------------- -------
sqlserver env=dev
To retrieve credentials for a database and connect to it:
tsh db connect --db-user=teleport sqlserver
When you run the tsh db connect
command above, tsh
attempts to execute
the mssql-cli
command-line client, which must be available in the user's
PATH
. If you do not have mssql-cli
available on your system, you can run the
following command to start a local proxy server that you can connect
to with your SQL Server client:
tsh proxy db --db-user=teleport --tunnel sqlserver
Read the Database Access GUI Clients guide for how to connect your DB GUI client to the local proxy.
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.