Getting Started with Desktop Access

This guide will help you configure Teleport to provide secure, passwordless access to Windows desktops. This configuration does not require an Active Directory domain.

Prerequisites

• A Linux server to run the Teleport Desktop Access service on. You can reuse an existing server running any other Teleport instance.
• A server or virtual machine running a Windows operating system with Remote Desktop enabled and the RDP port available to the Linux server.

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  12.1.1
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  12.1.2
CA pin   sha256:sha-hash-here

Step 1/4. Prepare Windows

In this section we'll import the Teleport certificate authority (CA) file to your Windows system, and prepare it for passwordless access through Teleport.

Import the Teleport root certificate

Use tctl to export the Teleport user certificate authority:

tctl auth export --type=windows > teleport.cer

Copy this certificate to your Windows system, if you didn't run tctl from there.

Install the Teleport service for Windows

From the Windows system, download the Teleport Windows Auth Setup. Extract the .exe file from the archive and run it. When prompted, select the Teleport certificate file from the previous step. Once complete, reboot the system.

teleport-windows-auth-setup.exe install --cert=teleport.cer -r
Teleport Authentication Package installed

Step 2/4. Install the Teleport Desktop Service

On your local system, authenticated to your Teleport cluster, generate a short-lived join token:

tctl tokens add --type=windowsdesktop
The invite token: abcd123-insecure-do-not-use-this
This token will expire in 60 minutes.
This token enables Desktop Access.  See https://goteleport.com/docs/desktop-access/
for detailed information on configuring Teleport Desktop Access with this token.

Copy the token to the Linux host where you will run the Desktop service as /tmp/token.

Use the appropriate commands for your environment to install your package.

Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.asc
Source variables about OS version
source /etc/os-release
Add the Teleport APT repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/teleport.repo")
sudo yum install teleport
Tip: Add /usr/local/bin to path used by sudo (so 'sudo tctl users add' will work as per the docs)
echo "Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin" > /etc/sudoers.d/secure_path
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

curl https://get.gravitational.com/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...

rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpm
warning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

Create /etc/teleport.yaml and configure it for Desktop Access. Update the proxy_server value to your Teleport proxy service or cloud tenant, and put the Windows machine address under non_ad_hosts:

version: v3
teleport:
  nodename: windows.teleport.example.com
  proxy_server: teleport-proxy.example.com:443
  auth_token: /tmp/token
windows_desktop_service:
  enabled: yes
  non_ad_hosts:
    - 192.0.2.156
auth_service:
  enabled: no
proxy_service:
  enabled: no
ssh_service:
  enabled: no

Note that without Active Directory, Teleport cannot automatically discover your Desktops. Instead you must define the Windows systems configured for access through Teleport in your config file, or use Teleport's API to build your own integration. An example API integration is available on GitHub.

version: v3
teleport:
  nodename: windows.teleport.example.com
  proxy_server: teleport-proxy.example.com:443
windows_desktop_service:
  enabled: yes
  non_ad_hosts:
-    - 192.0.2.156
+    - ip-192-0-2-156.us-east-2.compute.internal
+ host_labels:
+    - match: '.*\.us-east-2.compute.internal'
+      labels:
+        cloud: ec2
auth_service:
  enabled: no
proxy_service:
  enabled: no
ssh_service:
  enabled: no

Start or restart the Teleport Service. For new Teleport nodes, the examples below depend on how you installed Teleport (from a system package or a TAR archive):

sudo systemctl start teleport.service

sudo teleport install systemd --output=/etc/systemd/system/teleport.service;
sudo systemctl enable teleport;
sudo systemctl start teleport;

Step 3/4. Configure Windows access

In order to gain access to a remote desktop, a Teleport user needs to have the appropriate permissions for that desktop.

Create the file windows-desktop-admins.yaml:

kind: role
version: v6
metadata:
  name: windows-desktop-admins
spec:
  allow:
    windows_desktop_labels:
      "*": "*"
    windows_desktop_logins: ["Administrator", "alice"]

You can restrict access to specific hosts by defining values for windows_desktop_labels, and adjust the array of usernames this role has access to in windows_desktop_logins.

Apply the new role to your cluster:

tctl create -f windows-desktop-admins.yaml

Assign the windows-desktop-admins role to your Teleport user by running the following commands, depending on whether you authenticate as a local Teleport user or via the github, saml, or oidc authentication connectors:

tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml

  roles:
   - access
   - auditor
   - editor
+  - windows-desktop-admins

tctl create -f out.yaml

tctl get github/github --with-secrets > github.yaml

  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - windows-desktop-admins

tctl create -f github.yaml

tctl get --with-secrets saml/mysaml > saml.yaml

  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - windows-desktop-admins

tctl create -f saml.yaml

tctl get oidc/myoidc --with-secrets > oidc.yaml

  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - windows-desktop-admins

tctl create -f saml.yaml

Log out of your Teleport cluster and log in again to assume the new role.

Step 4/4. Connect

You can now connect to your Windows desktops from the Teleport Web UI:

Next Steps

• See the RBAC page for more information about setting up Windows Desktop Access permissions.
• See the Access Controls Getting Started guide for instructions on how to create or update a user with a given role.