Desktop Access Beta documentation (#8504)

* Desktop Access documentation

First draft of the Desktop Access docs. This is for Beta and has the
warnings on every page to make that clear.

* Apply suggestions from code review

Co-authored-by: Isaiah Becker-Mayer <isaiah@goteleport.com>

Co-authored-by: Isaiah Becker-Mayer <isaiah@goteleport.com>

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/",

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
+---
+
+<Admonition
+  type="warning"
+  title="Warning"
+>
+  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.
+</Admonition>
+
+# 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
+
+<Admonition
+  type="note"
+  title="Teleport CA"
+>
+  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.
+</Admonition>
+
+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.
+
+<Figure align="left" bordered caption="Import Teleport CA">
+  ![Import Teleport CA](../../img/desktop-access/ca.png)
+</Figure>
+
+### 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".
+
+<Figure align="left" bordered caption="Enable Remote Desktop Services">
+  ![Enable RDP](../../img/desktop-access/rdp.png)
+</Figure>
+
+
+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".
+
+<Figure align="left" bordered caption="Enable the Smart Card Service">
+  ![Enable Smartcard(../../img/desktop-access/smartcard.png)
+</Figure>
+
+
+### Open firewall to inbound RDP connections
+
+Finally, select:
+
+```text
+Computer Configuration > Policies > Windows Settings > Security Settings > Windows Firewall and Advanced Security
+```
+
+Right click on `Inbound Rules` and select `New Rule...`. Under `Predefined`
+select `Remote Desktop`. Only select the rule for `User Mode (TCP-in)`. On the
+next screen, select `Allow the connection` and finish.
+
+## Step 3/3. Log in using Teleport
+
+{/* TODO: add screenshots */}
+
+At this point everything should be ready for Desktop Access connections. Open
+the Teleport web UI and log in.
+
+On the left pane, select `Desktops`. You should see the list of all computers
+and Domain Controllers connected to your domain. Select one and click `CONNECT`
+on the right.
+
+A new tab will open and, after a few seconds, you should be logged in to your
+target Windows host.
+
+## Troubleshooting
+
+If you hit any issues, check out the [Troubleshooting documentation](./troubleshooting.mdx)
+for common problems and solutions.

docs/pages/desktop-access/introduction.mdx

@@ -0,0 +1,67 @@
+---
+title: Desktop Access
+description: Teleport Desktop Access introduction and resources.
+---
+
+<Admonition
+  type="warning"
+  title="Warning"
+>
+  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.
+</Admonition>
+
+# 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.
+
+<Admonition
+  type="note"
+  title="Supported platforms"
+>
+  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
+</Admonition>
+
+## Getting started
+
+<TileSet>
+  <Tile icon="desktop" title="Getting started" href="./getting-started.mdx">
+    Connect an Active Directory domain.
+  </Tile>
+</TileSet>
+
+## 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.

docs/pages/desktop-access/reference.mdx

@@ -0,0 +1,83 @@
+---
+title: Desktop Access reference
+description: Teleport Desktop Access configuration and CLI reference.
+---
+
+<Admonition
+  type="warning"
+  title="Warning"
+>
+  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.
+</Admonition>
+
+# 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
+```

docs/pages/desktop-access/troubleshooting.mdx

@@ -0,0 +1,150 @@
+---
+title: Troubleshooting Desktop Access
+description: Common issues and resolutions for Teleport's Desktop Access
+---
+
+<Admonition
+  type="warning"
+  title="Warning"
+>
+  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.
+</Admonition>
+
+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.