diff --git a/docs/config.json b/docs/config.json
index fbc710ddcb5..b1d34b04be6 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -71,7 +71,7 @@
"slug": "/setup/reference/",
"entries": [
{ "title": "Config File", "slug": "/setup/reference/config/" },
- { "title": "Config Resources", "slug": "/setup/reference/resources/" },
+ { "title": "Config Resources", "slug": "/setup/reference/resources/" },
{ "title": "Command Line", "slug": "/setup/reference/cli/" },
{ "title": "Metrics", "slug": "/setup/reference/metrics/" },
{ "title": "Terraform Resources", "slug": "/setup/reference/terraform-provider/" },
@@ -200,6 +200,16 @@
{ "title": "FAQ", "slug": "/database-access/faq/" }
]
},
+ {
+ "icon": "desktop",
+ "title": "Desktop Access",
+ "entries": [
+ { "title": "Introduction", "slug": "/desktop-access/introduction/" },
+ { "title": "Getting Started", "slug": "/desktop-access/getting-started/" },
+ { "title": "Reference", "slug": "/desktop-access/reference/" },
+ { "title": "Troubleshooting", "slug": "/desktop-access/troubleshooting/" }
+ ]
+ },
{
"icon": "lock",
"title": "Access Controls",
@@ -230,7 +240,7 @@
{"title": "Getting Started", "slug": "/api/getting-started/"},
{"title": "Architecture", "slug": "/api/architecture/"}
]
- },
+ },
{
"icon": "wand",
"title": "Preview",
@@ -286,7 +296,7 @@
"entries": [
{ "title": "U2f", "slug": "/cloud/guides/u2f/" }
]
- },
+ },
{ "title": "Architecture", "slug": "/cloud/architecture/" },
{ "title": "FAQ", "slug": "/cloud/faq/" }
]
@@ -402,7 +412,7 @@
"source": "/reference/api/introduction/",
"destination": "/api/introduction/",
"permanent": true
- },
+ },
{
"source": "/metrics-logs-reference/",
"destination": "/setup/reference/metrics/",
@@ -412,7 +422,7 @@
"source": "/config-reference/",
"destination": "/setup/reference/config/",
"permanent": true
- },
+ },
{
"source": "/cli-docs/",
"destination": "/setup/reference/cli/",
@@ -462,7 +472,7 @@
"source": "/gcp-guide/",
"destination": "/setup/deployments/gcp/",
"permanent": true
- },
+ },
{
"source": "/ibm-cloud-guide/",
"destination": "/setup/deployments/ibm/",
diff --git a/docs/img/desktop-access/ca.png b/docs/img/desktop-access/ca.png
new file mode 100644
index 00000000000..9b48cf35aef
Binary files /dev/null and b/docs/img/desktop-access/ca.png differ
diff --git a/docs/img/desktop-access/rdp.png b/docs/img/desktop-access/rdp.png
new file mode 100644
index 00000000000..fae0a67812b
Binary files /dev/null and b/docs/img/desktop-access/rdp.png differ
diff --git a/docs/img/desktop-access/smatcard.png b/docs/img/desktop-access/smatcard.png
new file mode 100644
index 00000000000..0aa7c668796
Binary files /dev/null and b/docs/img/desktop-access/smatcard.png differ
diff --git a/docs/pages/desktop-access/getting-started.mdx b/docs/pages/desktop-access/getting-started.mdx
new file mode 100644
index 00000000000..9c4fe6cbb40
--- /dev/null
+++ b/docs/pages/desktop-access/getting-started.mdx
@@ -0,0 +1,187 @@
+---
+title: Getting Started With Desktop Access
+description: Connect Teleport to Active Directory and log into a Windows Desktop
+---
+
+
+ Desktop Access is currently in Preview. Do not use this feature for any critical
+ infrastructure and keep a backup option for accessing your desktop hosts.
+
+
+# Getting Started
+
+In this guide we will connect an Active Directory domain to Teleport using
+Desktop Access and log into a Windows desktop from that domain.
+
+## Prerequisites
+
+This guide requires you to have:
+
+- An Active Directory domain
+- [Active Directory Certificate Services (AD
+ CS)](https://docs.microsoft.com/en-us/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority)
+ installed in the domain
+- Access to a Domain Controller
+- LDAP credentials for Active Directory (usually the same credentials you use
+ to log into the Domain Controller)
+- An existing Teleport cluster and user, version 8.0 or newer
+ - see [Teleport Getting Started](../getting-started.mdx) if you're new to Teleport
+- A Linux server to run the Teleport Desktop Access service on
+ - you can reuse an existing server running any other Teleport instance
+
+## Step 1/3. Configure Teleport
+
+
+ Prior to v8.0, the Teleport CA was not compatible with Windows logins. If
+ you're setting up Desktop Access in an existing cluster created before v8.0,
+ you must first perform a [CA rotation](../setup/operations/ca-rotation.mdx)
+ in order to resolve this.
+
+
+First, we need to enable Desktop Access in Teleport. To do this, add the
+following section in `teleport.yaml` on your Linux server:
+
+```yaml
+windows_desktop_service:
+ enabled: yes
+ # This is the address that windows_desktop_service will listen on.
+ listen_addr: "localhost:3028"
+ # (optional) This is the address that windows_desktop_service will advertise
+ # to the rest of Teleport for incoming connections. Only proxy_service should
+ # connect to windows_desktop_service, users connect to the proxy's web UI
+ # instead.
+ public_addr: "desktop-access.example.com:3028"
+ ldap:
+ # Address of the Domain Controller for LDAP connections. Usually, this
+ # address will use port 389, like: domain-controller.example.com:389.
+ addr: '$LDAP_SERVER_ADDRESS'
+ # Active Directory domain name you are connecting to.
+ domain: '$LDAP_DOMAIN_NAME'
+ # LDAP username for authentication. This username must include the domain
+ # NetBIOS name.
+ #
+ # For example, if your domain is "example.com", the NetBIOS name for it is
+ # likely "EXAMPLE". When connecting as the "Administrator" user, you should
+ # use the format: "EXAMPLE\Administrator".
+ username: '$LDAP_USERNAME'
+ # LDAP password for authentication. This is usually the same password you
+ # use to login to the Domain Controller.
+ password: '$LDAP_PASSWORD'
+```
+
+After updating `teleport.yaml`, start Teleport as usual using `teleport start`.
+
+## Step 2/3. Configure Group Policy to allow Teleport connections
+
+{/* TODO: script this using PowerShell */}
+
+Next, we need to configure Active Directory to trust Teleport for user
+authentication and allow the certificate-based mechanism that Teleport uses under the hood
+(smart cards).
+
+Get the Teleport user CA certificate:
+
+```
+$ tctl auth export --type=windows > user-ca.cer
+```
+
+Transfer the `user-ca.cer` file to your Domain Controller.
+
+Log into your Domain Controller open "Start" menu and run "Group Policy
+Management". On the left pane, navigate to `$FOREST > Domains > $DOMAIN`,
+selecting your forest and domain names respectively. Right click on "Default
+Domain Policy" and select "Edit...".
+
+### Import Teleport CA
+
+In the group policy editor, select:
+
+```text
+Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
+```
+
+Right click on `Trusted Root Certification Authorities` and select `Import`.
+Click through the wizard, selecting your CA file.
+
+
+ 
+
+
+### Allow remote RDP connections
+
+Next, select:
+
+```text
+Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections
+```
+
+Right click on `Allow users to connect remotely by using Remote Desktop
+Services` and select "Edit". Select "Enable" and "OK".
+
+
+ 
+
+
+
+Select:
+
+```text
+Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security
+```
+
+Right click `Require user authentication for remote connections by using
+Network Level Authentication`, edit, select **"Disable"** and "OK".
+
+### Enable the Smart Card service
+
+Teleport performs certificate based authentication by emulating a smart card.
+To enable the smart card service, select:
+
+```text
+Computer Configuration > Policies > Windows Settings > Security Settings > System Services
+```
+
+Double click on `Smart Card`, select `Define this policy setting` and switch to
+`Automatic`. Click "OK".
+
+
+ 
+for common problems and solutions.
diff --git a/docs/pages/desktop-access/introduction.mdx b/docs/pages/desktop-access/introduction.mdx
new file mode 100644
index 00000000000..3e107fc43a4
--- /dev/null
+++ b/docs/pages/desktop-access/introduction.mdx
@@ -0,0 +1,67 @@
+---
+title: Desktop Access
+description: Teleport Desktop Access introduction and resources.
+---
+
+
+ Desktop Access is currently in Preview. Do not use this feature for any critical
+ infrastructure and keep a backup option for accessing your desktop hosts.
+
+ Desktop Access Beta:
+
+ - is not compatible with HSM integration.
+ - does not support clipboard sharing.
+ - does not support session recording.
+ - does not support per-session MFA.
+ - may have worse performance than a native RDP client.
+
+
+# Desktop Access
+
+Teleport manages graphical desktop access to remote hosts. With Teleport
+Desktop Access, you get:
+
+- A password-less login experience backed by strong cryptographic
+ authentication.
+- Role-based access control (RBAC) for groups of hosts and users.
+- Audit log and recording of all desktop connections.
+
+
+ Only Windows hosts accessible over RDP are supported currently. Specifically:
+
+ - Windows Server 2012 R2 / Windows 10 or newer
+ - Hosts connected to an Active Directory domain
+
+
+## Getting started
+
+
+
+ Connect an Active Directory domain.
+
+
+
+## Resources
+
+{/*
+
+To learn more about configuring role-based access control for Desktop Access,
+check out [RBAC](./rbac.mdx) section.
+
+TODO: Complete the RBAC section
+
+*/}
+
+See [Reference](./reference.mdx) for an overview of
+Desktop Access related configuration and CLI commands.
+
+## Troubleshooting
+
+If you hit any issues, check out the [Troubleshooting documentation](./troubleshooting.mdx)
+for common problems and solutions.
diff --git a/docs/pages/desktop-access/reference.mdx b/docs/pages/desktop-access/reference.mdx
new file mode 100644
index 00000000000..e4a43eb4da1
--- /dev/null
+++ b/docs/pages/desktop-access/reference.mdx
@@ -0,0 +1,83 @@
+---
+title: Desktop Access reference
+description: Teleport Desktop Access configuration and CLI reference.
+---
+
+
+ Desktop Access is currently in Beta. Do not use this feature for any critical
+ infrastructure and keep a backup option for accessing your desktop hosts.
+
+
+# Configuration and CLI reference
+
+## teleport.yaml
+
+{/* TODO: add RBAC labels */}
+
+`teleport.yaml` fields related to Desktop Access:
+
+```yaml
+# Main service responsible for Desktop Access.
+#
+# You can have multiple Desktop Access services in your cluster (but not in the
+# same teleport.yaml), connected to the same or different Active Directory
+# domains.
+windows_desktop_service:
+ enabled: yes
+ # This is the address that windows_desktop_service will listen on.
+ listen_addr: "localhost:3028"
+ # (optional) This is the address that windows_desktop_service will advertise
+ # to the rest of Teleport for incoming connections. Only proxy_service should
+ # connect to windows_desktop_service, users connect to the proxy's web UI
+ # instead.
+ public_addr: "desktop-access.example.com:3028"
+ ldap:
+ # Address of the Domain Controller for LDAP connections. Usually, this
+ # address will use port 389, like: domain-controller.example.com:389.
+ addr: '$LDAP_SERVER_ADDRESS'
+ # Active Directory domain name you are connecting to.
+ domain: '$LDAP_DOMAIN_NAME'
+ # LDAP username for authentication. This username must include the domain
+ # NetBIOS name.
+ #
+ # For example, if your domain is "example.com", the NetBIOS name for it is
+ # likely "EXAMPLE". When connecting as the "Administrator" user, you should
+ # use the format: "EXAMPLE\Administrator".
+ username: '$LDAP_USERNAME'
+ # LDAP password for authentication. This is usually the same password you
+ # use to login to the Domain Controller.
+ password: '$LDAP_PASSWORD'
+```
+
+{/*
+
+## RBAC
+
+TODO: add RBAC role settings
+
+*/}
+
+## CLI
+
+CLI commands related to Desktop Access.
+
+Generate a join token for Desktop Access service:
+
+```sh
+$ tctl nodes add --roles=WindowsDesktop
+```
+
+List registered Desktop Access services:
+
+```sh
+$ tctl get windows_desktop_service
+```
+
+List registered Windows hosts in the domain:
+
+```sh
+$ tctl get windows_desktop
+```
diff --git a/docs/pages/desktop-access/troubleshooting.mdx b/docs/pages/desktop-access/troubleshooting.mdx
new file mode 100644
index 00000000000..ae52092de88
--- /dev/null
+++ b/docs/pages/desktop-access/troubleshooting.mdx
@@ -0,0 +1,150 @@
+---
+title: Troubleshooting Desktop Access
+description: Common issues and resolutions for Teleport's Desktop Access
+---
+
+
+ Desktop Access is currently in Preview. Do not use this feature for any critical
+ infrastructure and keep a backup option for accessing your desktop hosts.
+
+
+Common issues and resolution steps.
+
+## Auto-login does not work
+
+### Issue 1
+
+You connect to a Windows host from the Teleport UI, land on the Windows login
+screen and nothing happens.
+
+You can click on the username, click `Sign-in options` and click on the smart
+card icon. The error message is: **"No Valid Certificates Were Found on This
+Smart Card"**.
+
+### Solution 1
+
+Usually, this means that the Smart Card service is not running on the target
+host.
+
+First, make sure that you [enable the Smart Card service in Group
+Policy](./getting-started.mdx#enable-the-smart-card-service).
+
+If that doesn't help, log into the target host directly, open the "Services"
+program from the "Start" menu and check that the "Smart Card" service is in the
+"Running" state.
+
+If the "Smart Card" service is not running, open PowerShell and run
+`gpupdate.exe /force`. This forces a Group Policy sync and should pick up the
+service changes.
+
+### Issue 2
+
+You connect to a Windows host from the Teleport UI, land on the Windows login
+screen and see an error message: **"The smartcard certificate used for
+authentication was not trusted"** (or similar).
+
+### Solution 2
+
+This means that the host does not trust the Teleport CA.
+
+First, make sure that you [import the Teleport CA into Group
+Policy](./getting-started.mdx#import-teleport-ca). Note that if the
+Teleport CA was rotated since the last import, you will have to fetch the
+new CA using `tctl auth export --type=windows >user-ca.cer`
+
+If that doesn't help, log into the target host directly, open PowerShell and
+run `gpupdate.exe /force`. This forces a Group Policy sync and should pick up
+the new CA.
+
+## New session "hangs"
+
+### Issue
+
+You click `CONNECT` on a Windows host from the Teleport UI, a new tab opens but
+nothing is displayed other than the top bar. After a while, an error is
+displayed about a failed connection.
+
+### Solution
+
+This happens when the `windows_desktop_service` can't reach the target Windows
+host.
+
+First, make sure that you [open the RDP
+port](./getting-started.mdx#open-firewall-to-inbound-rdp-connections) and [allow
+remote RDP connections in Group
+Policy](./getting-started.mdx#allow-remote-rdp-connections).
+
+If that does not help, check if the target host is online and try to `ping` it
+from the Linux server that runs `windows_desktop_service`. If the host is
+online but not reachable, there is some other networking barrier in the way,
+specific to your infrastructure.
+
+## Teleport fails to start
+
+### Issue 1
+
+Teleport fails to start with an error similar to:
+
+```text
+LDAP Result Code 49 "Invalid Credentials": 80090308: LdapErr: DSID-0C0903C5, comment: AcceptSecurityContext error, data 52e, v2580\x00
+```
+
+### Solution 1
+
+This means that your LDAP username and password were not correct. Double-check
+them in the `ldap` section of `windows_desktop_service`.
+
+Note that the LDAP username must be formatted as `DOMAIN\User`, where `DOMAIN`
+is the NetBIOS name for the domain. For example, user `Administrator` in domain
+`example.com` should be formatted as `EXAMPLE\Administrator`.
+
+### Issue 2
+
+Teleport fails to start with an error similar to:
+
+```text
+LDAP Result Code 10 "Referral": 0000202B: RefErr: DSID-0310082F, data 0, 1 access points
+"\tref 1: 'xample.com'"
+"\x00"
+```
+
+### Solution 2
+
+This means that your domain name is likely wrong. Double-check the `domain`
+field in the `ldap` section of `windows_desktop_service`.
+
+### Issue 2
+
+Teleport fails to start with an error similar to:
+
+```text
+LDAP Result Code 200 "Network Error": dial tcp ad.example.com:389: i/o timeout
+```
+
+### Solution 2
+
+This means that your Domain Controller is down or unreachable. Double-check the
+`addr` field in the `ldap` section of `windows_desktop_service`. If it's
+correct, check that the Domain Controller is up and reachable from the server
+that runs `windows_desktop_service`.
+
+### Issue 3
+
+Teleport fails to start with an error similar to:
+
+```text
+LDAP Result Code 52 "Unavailable": 00000000: LdapErr: DSID-0C090F78, comment: Error initializing SSL/TLS, data 0, v2580\x00
+```
+
+### Solution 3
+
+This means that you do not have Active Directory Certificate Services (AD CS)
+installed in your domain. AD CS provides the certificate for TLS connections to
+LDAP and Teleport refuses to authenticate to LDAP over an insecure connection.
+
+You must [install AD
+CS](https://docs.microsoft.com/en-us/windows-server/networking/core-network-guide/cncg/server-certs/install-the-certification-authority)
+on one of the Domain Controllers and reboot it.