Skip to content

Latest commit

 

History

History
227 lines (173 loc) · 6.81 KB

getting-started.mdx

File metadata and controls

227 lines (173 loc) · 6.81 KB
title description videoBanner
Getting Started with Desktop Access
Passwordless access to Windows systems for local users
9DyKQbg4ORc

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

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](./active-directory.mdx).
Passwordless access for local users is not yet compatible with Windows Server 2022.

Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

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

(!docs/pages/includes/tctl.mdx!)

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.

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: (=presets.tokens.first=)
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.

(!docs/pages/includes/install-linux.mdx!)

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.

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

(!docs/pages/includes/add-role-to-user.mdx role="windows-desktop-admins" !)

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.