diff --git a/docs/config.json b/docs/config.json
index 8379539886df3..d60b757dbf99a 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -988,6 +988,10 @@
"title": "SQL Server (Preview)",
"slug": "/database-access/guides/sql-server-ad/"
},
+ {
+ "title": "SQL Server with PKINIT (Preview)",
+ "slug": "/database-access/guides/sql-server-ad-pkinit/"
+ },
{
"title": "Self-Hosted Cassandra & ScyllaDB",
"slug": "/database-access/guides/cassandra-self-hosted/"
diff --git a/docs/cspell.json b/docs/cspell.json
index 3e93bdc6d35f7..0ede027551757 100644
--- a/docs/cspell.json
+++ b/docs/cspell.json
@@ -544,6 +544,7 @@
"pgaadauth",
"pidof",
"pkill",
+ "pkinit",
"plugindata",
"postgresqlselfhosted",
"pprof",
@@ -568,6 +569,7 @@
"quicktime",
"rdbms",
"rdns",
+ "rdsca",
"rdsproxy",
"readyz",
"realmd",
diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx
new file mode 100644
index 0000000000000..1125a358d6ea6
--- /dev/null
+++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx
@@ -0,0 +1,433 @@
+---
+title: Microsoft SQL Server access with PKINIT authentication (Preview)
+description: How to configure Microsoft SQL Server access with Active Directory PKINIT authentication.
+---
+
+
+ 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.
+
+
+
+{/*```mermaid
+%%{ init: { 'flowchart': { 'curve': 'stepBefore' } } }%%
+graph LR
+a(Users)
+b[Teleport Proxy]
+style b fill: #844cff,color: #ffffff
+a-->b
+b-->c
+subgraph local [Private Network]
+style local fill:#C0C0C0,stroke: #000000
+ c[Teleport DB Service]
+ style c fill: #a379ff,color: #ffffff
+ subgraph ad [ ]
+ direction TB
+ style ad fill:none,stroke:none
+ e[(SQL Servers)]
+ d{Active Directory Users}
+ end
+ c-->d
+ c-->e
+ e-->d
+end
+```*/}
+
+
+
+{/*```mermaid
+%%{ init: { 'flowchart': { 'curve': 'stepBefore' } } }%%
+graph LR
+a(Users)
+b[Teleport Cloud Tenant]
+style b fill: #844cff,color: #ffffff
+a-->b
+b-->c
+subgraph local [Private Network]
+style local fill:#C0C0C0,stroke: #000000
+ c[Teleport DB Service]
+ style c fill: #a379ff,color: #ffffff
+ subgraph ad [ ]
+ direction TB
+ style ad fill:none,stroke:none
+ e[(SQL Servers)]
+ d{Active Directory Users}
+ end
+ c-->d
+ c-->e
+ e-->d
+end
+```*/}
+
+
+This guide will focus on SQL Servers using self-hosted Active Directory
+authentication.
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- 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:
+
+
+
+ ```code
+ $ sudo apt-get update
+ $ sudo apt-get -y install krb5-user krb5-pkinit
+ ```
+
+
+ ```code
+ $ sudo yum -y update
+ $ sudo yum -y install krb5-workstation krb5-pkinit
+ ```
+
+
+
+- (!docs/pages/includes/tctl.mdx!)
+
+## Step 1/7. Create a Teleport user
+
+(!docs/pages/includes/database-access/create-user.mdx!)
+
+## 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.
+
+
+1. Get the Teleport database CA certificate by running:
+
+ ```code
+ $ tctl auth export --type=db-der > db-ca.cer
+ ```
+
+2. Get the Teleport database CRL by running:
+
+ ```code
+ $ 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
+
+
+ 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.
+
+
+1. Create a GPO named `Teleport DB Access`.
+
+ ```powershell
+ $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:
+
+ ```text
+ 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:
+
+ ```text
+ 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`.
+
+
+ 
+
+
+
+ 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):
+
+```powershell
+certutil –dspublish –f RootCA
+certutil -dspublish -f 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).
+
+```powershell
+certutil -dspublish -f 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:
+
+ ```powershell
+ 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:
+
+```powershell
+$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
+
+(!docs/pages/includes/database-access/token.mdx!)
+
+Install Teleport on the host where you will run the Teleport Database Service:
+
+(!docs/pages/includes/install-linux.mdx!)
+
+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.
+
+```yaml
+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:
+
+```code
+$ 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:
+
+```sql
+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:
+
+
+
+```code
+$ tsh login --proxy=teleport.example.com --user=alice
+$ tsh db ls
+# Name Description Labels
+# --------- ------------------- -------
+# sqlserver env=dev
+```
+
+
+
+
+```code
+$ tsh login --proxy=mytenant.teleport.sh --user=alice
+$ tsh db ls
+# Name Description Labels
+# --------- ------------------- -------
+# sqlserver env=dev
+```
+
+
+
+To retrieve credentials for a database and connect to it:
+
+```code
+$ tsh db connect --db-user=teleport sqlserver
+```
+
+
+ The `mssql-cli` command-line client should be available in `PATH` of the machine
+ you're running `tsh db connect` from.
+
+ `mssql-cli` is not required for SQL Server connections. Use `tsh proxy db --db-user=teleport --tunnel sqlserver`
+ to connect from other DB Clients such as Microsoft SQL Server Management Studio.
+
+
+To log out of the database and remove credentials:
+
+```code
+$ 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 user@AD.TELEPORT.DEV:
+\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:
+
+```diff
+...
+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
+
+(!docs/pages/includes/database-access/guides-next-steps.mdx!)
+
+## Further reading
+
+- [Kerberos PKINIT authentication](https://web.mit.edu/kerberos/krb5-1.13/doc/admin/pkinit.html).
diff --git a/docs/pages/database-access/guides/sql-server-ad.mdx b/docs/pages/database-access/guides/sql-server-ad.mdx
index d149c4fbd8fc0..7f84c6af2d5b2 100644
--- a/docs/pages/database-access/guides/sql-server-ad.mdx
+++ b/docs/pages/database-access/guides/sql-server-ad.mdx
@@ -381,8 +381,10 @@ If your `tsh db connect` error includes the following text, the certificate used
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.
-```yaml
+To solve this, you can add the CA configuration to the database like the
+following:
+
+```diff
databases:
- name: sqlserver
protocol: sqlserver
@@ -393,10 +395,18 @@ Add the Certificate Authority (CA) `ca_cert_file` into the `tls` section so Tele
spn: MSSQLSvc/sqlserver.example.com:1433
static_labels:
"env": "dev"
- tls:
- ca_cert_file: /var/lib/teleport/cert.pem
++ 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
```
+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
(!docs/pages/includes/database-access/guides-next-steps.mdx!)
diff --git a/docs/pages/includes/database-access/guides.mdx b/docs/pages/includes/database-access/guides.mdx
index 89f4ce60ecd1c..bb16a53595354 100644
--- a/docs/pages/includes/database-access/guides.mdx
+++ b/docs/pages/includes/database-access/guides.mdx
@@ -1,6 +1,7 @@
## How to connect your database to Teleport
- [Active Directory SQL Server (Preview)](../../database-access/guides/sql-server-ad.mdx): Connect Microsoft SQL Server with Active Directory authentication.
+- [Active Directory SQL Server with PKINIT (Preview)](../../database-access/guides/sql-server-ad-pkinit.mdx): Connect Microsoft SQL Server with Active Directory PKINIT authentication.
- [AWS DynamoDB](../../database-access/guides/aws-dynamodb.mdx): Connect AWS DynamoDB.
- [AWS ElastiCache & MemoryDB](../../database-access/guides/redis-aws.mdx): Connect AWS ElastiCache or AWS MemoryDB for Redis database.
- [AWS RDS & Aurora](../../database-access/guides/rds.mdx): Connect AWS RDS or Aurora PostgreSQL, MariaDB or MySQL database.