From 6f7a437eee1faa31d26bfa06616dd6ef853ec75d Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Thu, 16 Mar 2023 16:32:40 -0300 Subject: [PATCH 01/12] feat(docs): add sqlserver pkinit guide page --- docs/config.json | 4 + .../guides/sql-server-ad-pkinit.mdx | 377 ++++++++++++++++++ .../pages/includes/database-access/guides.mdx | 1 + 3 files changed, 382 insertions(+) create mode 100644 docs/pages/database-access/guides/sql-server-ad-pkinit.mdx diff --git a/docs/config.json b/docs/config.json index 37964ed5ec588..ca40fe7b53416 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/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..2287ba781198a --- /dev/null +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -0,0 +1,377 @@ +--- +title: Database Access with Microsoft SQL Server with Active Directory PKINIT authentication (Preview) +description: How to configure Teleport Database Access with Microsoft SQL Server with Active Directory PKINIT authentication. +--- + + + Database Access for Microsoft SQL Server 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. + + +![Teleport Database Access SQL Server Self-Hosted](../../../img/database-access/guides/sqlserver_selfhosted.png) + + +![Teleport Database Access SQL Server Cloud](../../../img/database-access/guides/sqlserver_cloud.png) + + +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 the Active Directory. + +(!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. + +The following step requires an existing cluster. If you don't already have a +Teleport cluster up and running, see our general [Getting +Started](../../try-out-teleport/introduction.mdx) guide. + + + These steps will need to be repeated if Teleport's database certificate + authority is rotated. + + +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 such computers. + + +1. Create a GPO with name like `Teleport DB Access`. + +```powershell +$GPOName="Teleport DB Access" +New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName) +``` + +2. Again 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. + +
+ ![Import Teleport CA](../../../img/desktop-access/ca.png) +
+ +### 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`. + +
+ ![Enable Smartcard](../../../img/desktop-access/smartcard.png) +
+ +### Publish Teleport CA + +This step enables the domain controllers to trust the Teleport CA, which will +allow smart card logons via Teleport to succeed. + +On a machine which 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 Teleport CRL + +On the same machine, run the command below at a PowerShell promt 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 Teleport +``` + + + To avoid waiting until the certificate propagation, you can force the CA + retrieval from LDAP after importing the CA and CRL with the command: + + ```powershell + certutil -pulse + ``` + + +## Step 3/7. Export LDAP CA certificate + +To authenticate users, Teleport uses LDAPS. This means that Teleport needs to +know that the certificate sent by the server during the initial SSL connection +is trusted. This is done by specifying the LDAP CA certificate on the database +configuration, but first, we need to export it from your AD. It can be done 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!) + + + Teleport Database Service must run on a Linux server with the `kinit` command + installed with PKINIT extensions. + + + + ```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 + ``` + + + + +Copy the join token to a file on the instance where you will run the Database +Service, and then use the following configuration: + +```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: + # Active Directory domain (Kerberos realm) that SQL Server is joined. + domain: ad.teleport.dev + # Service Principal Name for SQL Server to fetch Kerberos tickets for. + spn: MSSQLSvc/SQL-SERVER-INSTANCE.ad.teleport.dev:1433 + # The SPN of the domain controller responsible for providing the LDAP CA. + kdc_host_name: DOMAIN-CONTROLLER.ad.teleport.dev + # Place the LDAP CA contents generated above. + 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 Attribute Editor tab, make sure that "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 CA configuration to the database like the +following: + +```yaml +... +db_service: + databases: + - name: sqlserver + protocol: sqlserver + tls: + # Point it to your Database CA PEM certificate. + ca_cert_file: "rdsca.pem" + 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/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. From c01e2999adc85ccd8c828f74e8688dc995fe502b Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Mon, 3 Apr 2023 18:11:00 -0300 Subject: [PATCH 02/12] docs(database-access): update with codereview suggestions --- .../guides/sql-server-ad-pkinit.mdx | 14 ++++++++++++-- .../pages/database-access/guides/sql-server-ad.mdx | 14 ++++++++++++-- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 2287ba781198a..1f36220d7f6a9 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -95,7 +95,7 @@ Computer Configuration > Policies > Windows Settings > Security Settings > Publi ``` 5. Right click on `Trusted Root Certification Authorities` and select `Import`. -6. Click through the wizard, selecting your CA file. +6. Click through the wizard, selecting your CA file (`db-ca.cer`).
![Import Teleport CA](../../../img/desktop-access/ca.png) @@ -118,6 +118,14 @@ Computer Configuration > Policies > Windows Settings > Security Settings > Syste ![Enable Smartcard](../../../img/desktop-access/smartcard.png)
+ + 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 their effects may still take time to + propagate to other machines on the domain). + + ### Publish Teleport CA This step enables the domain controllers to trust the Teleport CA, which will @@ -359,6 +367,9 @@ db_service: 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: ... ``` @@ -367,7 +378,6 @@ 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/database-access/guides/sql-server-ad.mdx b/docs/pages/database-access/guides/sql-server-ad.mdx index d149c4fbd8fc0..62b83352d3e60 100644 --- a/docs/pages/database-access/guides/sql-server-ad.mdx +++ b/docs/pages/database-access/guides/sql-server-ad.mdx @@ -381,7 +381,9 @@ 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. +To solve this, you can add the CA configuration to the database like the +following: + ```yaml databases: - name: sqlserver @@ -394,9 +396,17 @@ Add the Certificate Authority (CA) `ca_cert_file` into the `tls` section so Tele static_labels: "env": "dev" tls: - ca_cert_file: /var/lib/teleport/cert.pem + # 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!) From 6b3aa1eff73cb5022dbdd01c709a854dca0e2467 Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Mon, 3 Apr 2023 18:13:22 -0300 Subject: [PATCH 03/12] docs(database-access): update CRL path --- docs/pages/database-access/guides/sql-server-ad-pkinit.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 1f36220d7f6a9..3d2c2e952f8ec 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -148,7 +148,7 @@ 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 Teleport +certutil -dspublish -f TeleportDB ``` From baab680c5fac0556627c3b87de9f2b3f0da0ced7 Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Wed, 5 Apr 2023 14:32:27 -0300 Subject: [PATCH 04/12] Apply suggestions from code review Co-authored-by: Paul Gottschling Co-authored-by: Alex Fornuto --- .../guides/sql-server-ad-pkinit.mdx | 48 ++++++++----------- 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 3d2c2e952f8ec..384325430c3c3 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -4,7 +4,7 @@ description: How to configure Teleport Database Access with Microsoft SQL Server --- - Database Access for Microsoft SQL Server is currently in Preview mode. + Database access for Microsoft SQL Server is currently in Preview mode. This guide will help you to: @@ -28,11 +28,10 @@ authentication. (!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 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 the Active Directory. - -(!docs/pages/includes/tctl.mdx!) +- (!docs/pages/includes/tctl.mdx!) ## Step 1/7. Create a Teleport user @@ -44,15 +43,11 @@ 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. +### Export Teleport CA and CRL -The following step requires an existing cluster. If you don't already have a -Teleport cluster up and running, see our general [Getting -Started](../../try-out-teleport/introduction.mdx) guide. - These steps will need to be repeated if Teleport's database certificate - authority is rotated. +You will need to repeat these steps if you rotate Teleport's database certificate authority. 1. Get the Teleport database CA certificate by running: @@ -69,13 +64,13 @@ $ 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. +### 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 such computers. + to an OU that includes only these computers. 1. Create a GPO with name like `Teleport DB Access`. @@ -85,7 +80,7 @@ $GPOName="Teleport DB Access" New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName) ``` -2. Again open the `Group Policy Management` program, and on the left pane, +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: @@ -101,9 +96,9 @@ Computer Configuration > Policies > Windows Settings > Security Settings > Publi ![Import Teleport CA](../../../img/desktop-access/ca.png) -### Enable smart card service. +### Enable smart card service -Teleport performs certificate based authentication by emulating a smart card. +Teleport performs certificate-based authentication by emulating a smart card. 1. Still editing your `Teleport DB Access`, select: @@ -114,7 +109,7 @@ Computer Configuration > Policies > Windows Settings > Security Settings > Syste 2. Double click on `Smart Card`, select `Define this policy setting` and switch to `Automatic` then click `OK`. -
+
![Enable Smartcard](../../../img/desktop-access/smartcard.png)
@@ -126,12 +121,12 @@ Computer Configuration > Policies > Windows Settings > Security Settings > Syste propagate to other machines on the domain). -### Publish Teleport CA +### Publish the Teleport CA This step enables the domain controllers to trust the Teleport CA, which will -allow smart card logons via Teleport to succeed. +allow smart card logins via Teleport to succeed. -On a machine which is joined to your domain and logged in as an account in the +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): @@ -141,7 +136,7 @@ certutil –dspublish –f RootCA certutil -dspublish -f NTAuthCA ``` -### Publish Teleport CRL +### Publish the Teleport CRL On the same machine, run the command below at a PowerShell promt to publish the Teleport CRL to your Active Directory domain (using the path to the exported @@ -152,7 +147,7 @@ certutil -dspublish -f TeleportDB ``` - To avoid waiting until the certificate propagation, you can force the CA + 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 @@ -160,7 +155,7 @@ certutil -dspublish -f TeleportDB ``` -## Step 3/7. Export LDAP CA certificate +## Step 3/7. Export the LDAP CA certificate To authenticate users, Teleport uses LDAPS. This means that Teleport needs to know that the certificate sent by the server during the initial SSL connection @@ -252,7 +247,7 @@ db_service: 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 Attribute Editor tab, make sure that "View > Advanced Features" + If you don't see the Attribute Editor tab, make sure that the "View > Advanced Features" toggle is enabled. @@ -330,7 +325,7 @@ $ tsh db logout sqlserver ### 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 +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 @@ -339,7 +334,7 @@ correctly or propagated yet. You can force the propagation by running ### 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 +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 @@ -355,8 +350,7 @@ 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 CA configuration to the database like the -following: +To solve this, you can add the following configuration to your Teleport Database Service instance: ```yaml ... From 29c0c24f5106c9d89ce479cb666ea1bc51e0f2c0 Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Wed, 5 Apr 2023 15:17:31 -0300 Subject: [PATCH 05/12] refactor(docs): apply code review requested changes --- .../guides/sql-server-ad-pkinit.mdx | 79 ++++++++++--------- .../database-access/guides/sql-server-ad.mdx | 14 ++-- 2 files changed, 48 insertions(+), 45 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 384325430c3c3..58b3f4d6762b2 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -1,5 +1,5 @@ --- -title: Database Access with Microsoft SQL Server with Active Directory PKINIT authentication (Preview) +title: Database Access for Microsoft SQL Server with PKINIT (Preview) description: How to configure Teleport Database Access with Microsoft SQL Server with Active Directory PKINIT authentication. --- @@ -52,15 +52,15 @@ You will need to repeat these steps if you rotate Teleport's database certificat 1. Get the Teleport database CA certificate by running: -```code -$ tctl auth export --type=db-der > db-ca.cer -``` + ```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 -``` + ```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. @@ -73,21 +73,21 @@ $ tctl auth crl --type=db > db-ca.crl to an OU that includes only these computers. -1. Create a GPO with name like `Teleport DB Access`. +1. Create a GPO named `Teleport DB Access`. -```powershell -$GPOName="Teleport DB Access" -New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName) -``` + ```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 -``` + ```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`). @@ -102,9 +102,9 @@ 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 -``` + ```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`. @@ -157,11 +157,11 @@ certutil -dspublish -f TeleportDB ## Step 3/7. Export the LDAP CA certificate -To authenticate users, Teleport uses LDAPS. This means that Teleport needs to -know that the certificate sent by the server during the initial SSL connection -is trusted. This is done by specifying the LDAP CA certificate on the database -configuration, but first, we need to export it from your AD. It can be done by -running the following PowerShell script on your Windows instance: +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" @@ -208,7 +208,14 @@ Install Teleport on the host where you will run the Teleport Database Service: Copy the join token to a file on the instance where you will run the Database -Service, and then use the following configuration: +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 @@ -230,13 +237,9 @@ db_service: protocol: sqlserver uri: SQL-SERVER-INSTANCE.ad.teleport.dev:1433 ad: - # Active Directory domain (Kerberos realm) that SQL Server is joined. domain: ad.teleport.dev - # Service Principal Name for SQL Server to fetch Kerberos tickets for. spn: MSSQLSvc/SQL-SERVER-INSTANCE.ad.teleport.dev:1433 - # The SPN of the domain controller responsible for providing the LDAP CA. kdc_host_name: DOMAIN-CONTROLLER.ad.teleport.dev - # Place the LDAP CA contents generated above. ldap_cert: | -----BEGIN CERTIFICATE----- ... @@ -322,7 +325,7 @@ $ tsh db logout sqlserver ## Troubleshooting -### Teleport CA and CRL not imported correctly. +### 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 @@ -331,7 +334,7 @@ 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. +### 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 @@ -341,7 +344,7 @@ 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. +### 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: @@ -352,18 +355,18 @@ while trying to verify candidate authority certificate To solve this, you can add the following configuration to your Teleport Database Service instance: -```yaml +```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 ++ 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: ... ``` diff --git a/docs/pages/database-access/guides/sql-server-ad.mdx b/docs/pages/database-access/guides/sql-server-ad.mdx index 62b83352d3e60..7f84c6af2d5b2 100644 --- a/docs/pages/database-access/guides/sql-server-ad.mdx +++ b/docs/pages/database-access/guides/sql-server-ad.mdx @@ -384,7 +384,7 @@ Error message: TLS Handshake failed: x509: certificate signed by unknown authori To solve this, you can add the CA configuration to the database like the following: -```yaml +```diff databases: - name: sqlserver protocol: sqlserver @@ -395,12 +395,12 @@ following: spn: MSSQLSvc/sqlserver.example.com:1433 static_labels: "env": "dev" - 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 ++ 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 From 86bb6598dad78736849e87965f8fa9887e1ef7bd Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Wed, 5 Apr 2023 15:25:32 -0300 Subject: [PATCH 06/12] refactor(docs): remove kinit install from admonition --- .../guides/sql-server-ad-pkinit.mdx | 36 +++++++++---------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 58b3f4d6762b2..98d80ca6ae0bc 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -187,25 +187,23 @@ Install Teleport on the host where you will run the Teleport Database Service: (!docs/pages/includes/install-linux.mdx!) - - Teleport Database Service must run on a Linux server with the `kinit` command - installed with PKINIT extensions. - - - - ```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 - ``` - - - +Teleport Database Service must run on a Linux server with the `kinit` command +installed with PKINIT extensions. + + + + ```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 + ``` + + 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 From 636ee9ba7d7e1d181a1c4e24f987b93e011adc9f Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Wed, 5 Apr 2023 15:31:18 -0300 Subject: [PATCH 07/12] feat(docs): comment mermaid diagrams --- .../guides/sql-server-ad-pkinit.mdx | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 98d80ca6ae0bc..b09300b3e0023 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -15,9 +15,55 @@ This guide will help you to: ![Teleport Database Access SQL Server Self-Hosted](../../../img/database-access/guides/sqlserver_selfhosted.png) +{/*```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 +```*/} ![Teleport Database Access SQL Server Cloud](../../../img/database-access/guides/sqlserver_cloud.png) +{/*```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 From 66be4175f6981bf465e3152836dfcd9e3c6f1d3d Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Thu, 6 Apr 2023 13:59:34 -0300 Subject: [PATCH 08/12] docs(database-access): fix lint --- .../database-access/guides/sql-server-ad-pkinit.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index b09300b3e0023..05d68172c8b4b 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -128,7 +128,9 @@ You will need to repeat these steps if you rotate Teleport's database certificat 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 @@ -136,6 +138,7 @@ You will need to repeat these steps if you rotate Teleport's database certificat ``` 5. Right click on `Trusted Root Certification Authorities` and select `Import`. + 6. Click through the wizard, selecting your CA file (`db-ca.cer`).
@@ -255,11 +258,11 @@ 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. +- `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 From 1a7926d835a217a2ed98dc0d454084b03eeb3dfa Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Mon, 10 Apr 2023 11:20:49 -0300 Subject: [PATCH 09/12] Apply suggestions from code review Co-authored-by: Paul Gottschling --- docs/pages/database-access/guides/sql-server-ad-pkinit.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index 05d68172c8b4b..c499e07600c3d 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -166,7 +166,7 @@ Teleport performs certificate-based authentication by emulating a smart card. 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 their effects may still take time to + and running `gpupdate.exe /force` (though the effects of your changes may still take time to propagate to other machines on the domain). @@ -236,7 +236,7 @@ Install Teleport on the host where you will run the Teleport Database Service: (!docs/pages/includes/install-linux.mdx!) -Teleport Database Service must run on a Linux server with the `kinit` command +The Teleport Database Service must run on a Linux server with the `kinit` command installed with PKINIT extensions. From 85d3e5eecb93af831f94d01b5d8ebc48b29023d2 Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Mon, 10 Apr 2023 14:06:52 -0300 Subject: [PATCH 10/12] docs(database-access): move kinit installation instructions --- .../guides/sql-server-ad-pkinit.mdx | 40 ++++++++++--------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index c499e07600c3d..d46dc76d6597a 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -74,9 +74,29 @@ authentication. (!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 the Active Directory. + +- A Linux node with network access to an Active Directory installation and + `kinit` command with PKINIT extensions intalled: + + + + ```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 @@ -236,24 +256,6 @@ Install Teleport on the host where you will run the Teleport Database Service: (!docs/pages/includes/install-linux.mdx!) -The Teleport Database Service must run on a Linux server with the `kinit` command -installed with PKINIT extensions. - - - - ```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 - ``` - - - 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: From 01c4ccbdb19c0646ef21042321d58971426c5b89 Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Wed, 19 Apr 2023 14:44:18 -0300 Subject: [PATCH 11/12] docs(database-access): fix spellchek errors --- docs/cspell.json | 2 ++ docs/pages/database-access/guides/sql-server-ad-pkinit.mdx | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/cspell.json b/docs/cspell.json index 14deacd333b6f..d0c9f2b8fc03c 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 index d46dc76d6597a..ac1dc79315952 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -80,7 +80,7 @@ authentication. - 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 intalled: + `kinit` command with PKINIT extensions installed: @@ -207,7 +207,7 @@ certutil -dspublish -f NTAuthCA ### Publish the Teleport CRL -On the same machine, run the command below at a PowerShell promt to publish the +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). From 1030cb5cf83e82d136990056cbd1a8d4f808e8ab Mon Sep 17 00:00:00 2001 From: Gabriel Corado Date: Wed, 19 Apr 2023 15:00:51 -0300 Subject: [PATCH 12/12] docs(database-access): change database access usage --- .../database-access/guides/sql-server-ad-pkinit.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx index ac1dc79315952..1125a358d6ea6 100644 --- a/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx +++ b/docs/pages/database-access/guides/sql-server-ad-pkinit.mdx @@ -1,10 +1,10 @@ --- -title: Database Access for Microsoft SQL Server with PKINIT (Preview) -description: How to configure Teleport Database Access with Microsoft SQL Server with Active Directory PKINIT authentication. +title: Microsoft SQL Server access with PKINIT authentication (Preview) +description: How to configure Microsoft SQL Server access with Active Directory PKINIT authentication. --- - Database access for Microsoft SQL Server is currently in Preview mode. + Microsoft SQL Server access is currently in Preview mode. This guide will help you to: @@ -14,7 +14,7 @@ This guide will help you to: - Connect to SQL Server through Teleport. -![Teleport Database Access SQL Server Self-Hosted](../../../img/database-access/guides/sqlserver_selfhosted.png) +![SQL Server with self-hosted Teleport](../../../img/database-access/guides/sqlserver_selfhosted.png) {/*```mermaid %%{ init: { 'flowchart': { 'curve': 'stepBefore' } } }%% graph LR @@ -40,7 +40,7 @@ end ```*/} -![Teleport Database Access SQL Server Cloud](../../../img/database-access/guides/sqlserver_cloud.png) +![Teleport SQL Server access with Teleport Cloud](../../../img/database-access/guides/sqlserver_cloud.png) {/*```mermaid %%{ init: { 'flowchart': { 'curve': 'stepBefore' } } }%% graph LR