Fork me on GitHub

Teleport

Getting Started with Desktop Access

Improve
Getting Started With Teleport Windows Access

Getting Started With Teleport Windows Access

Length: 08:57

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

Note

Passwordless access for local users is an Enterprise-only feature.

For open source Teleport, consider integrating Teleport with Active Directory for automatic discovery by reading Desktop Access with Active Directory.

Teleport Enterprise users can also mix the Teleport Active Directory integration with the static host definitions described below.

Passwordless access for local users is available starting from Teleport v12. Previous versions of Teleport can implement Windows Access by integrating with an Active Directory domain.

Prerequisites

  • A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.

    tctl version

    Teleport Enterprise v12.1.1 go1.19

    tsh version

    Teleport v12.1.1 go1.19

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.
  • 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.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 12.1.1

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status

Cluster myinstance.teleport.sh

Version 12.1.2

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

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.

Headless Installation

The Teleport Windows Auth Setup can be run in a shell environment with elevated privileges. You can use this to automate installation, uninstallation, and certificate updates. The following command will install the Teleport Certificate, load the required DLL, disable NLA, and reboot the Windows machine:

teleport-windows-auth-setup.exe install --cert=teleport.cer -r

Teleport Authentication Package installed

Use the --help flag to learn more.

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.

Teleport Edition

Add the Teleport repository to your repository list:

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

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

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

In the example commands below, update $SYSTEM-ARCH with the appropriate value (amd64, arm64, or arm). All example commands using this variable will update after one is filled out.

After Downloading the .deb file for your system architecture, install it with dpkg. The example below assumes the root user:

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 ...

After Downloading the .rpm file for your system architecture, install it with rpm:

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

For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:

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
Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

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.

You can attach labels to your Windows hosts by matching to their hostnames. For example, to add the cloud: ec2 label to hosts with EC2 private IP DNS names:

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.

RBAC Configuration

Ensure that each Teleport user is only assigned Windows logins that they should be allowed to access.

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:

Retrieve your local user's configuration resource:

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

Edit out.yaml, adding windows-desktop-admins to the list of existing roles:

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

Apply your changes:

tctl create -f out.yaml

Retrieve your github configuration resource:

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

Edit github.yaml, adding windows-desktop-admins to the teams_to_roles section. The team you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest team possible within your organization. This team must also include your user.

Here is an example:

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

Apply your changes:

tctl create -f github.yaml
Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to saml.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Retrieve your saml configuration resource:

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

Edit saml.yaml, adding windows-desktop-admins to the attributes_to_roles section. The attribute you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

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

Apply your changes:

tctl create -f saml.yaml
Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to saml.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Retrieve your oidc configuration resource:

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

Edit oidc.yaml, adding windows-desktop-admins to the claims_to_roles section. The claim you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

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

Apply your changes:

tctl create -f saml.yaml
Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to saml.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

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:

Connecting to a Windows desktop from the 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.