Sign In

Sign in to Teleport

Teleport Cloud LoginLogin to your Teleport AccountDashboard LoginLegacy Login & Teleport Enterprise Downloads
Get Started
Fork me on GitHub

Teleport

Getting Started

Version 11.0
Improve

The features documented on this page are available in Teleport 10.2.6 and higher.

This guide will help you configure Teleport and Active Directory in order to provide secure, passwordless access to Windows desktops.

Teleport Desktop Access is desiged to be a secure access solution for Windows environments. Teleport implements a minimal feature set of the RDP protocol with security as a priority, and may not be as performant as standard RDP clients. Consider Desktop Accesss to manage access to your most sensitive Windows environments, not as a drop-in replacement for other tools to provide general access to Windows desktops.

Prerequisites

  • One or more hosts to run the Teleport Auth and Proxy services on.
  • A server or virtual machine running a Windows Server operating system. In this guide, we'll install Active Directory on this server in order to support passwordless logins with Teleport to the Windows desktops in the Active Directory domain.
  • A Linux host where you will run the Teleport Desktop Service. This guide assumes that you will run Teleport's Windows Desktop Service on a dedicated host. To install Desktop Access into an existing Teleport instance running other services, see the Manual Setup guide for Desktop Access.
  • An Active Directory domain, configured for LDAPS (Teleport requires an encrypted LDAP connection). Typically this means installing AD CS

Step 1/2. Install Teleport

Set up the Teleport Auth and Proxy Services

On the host where you will run the Auth Service and Proxy Service, download the latest version of Teleport for your platform from our downloads page and follow the installation instructions.

Teleport requires a valid TLS certificate to operate and can fetch one automatically using Let's Encrypt's ACME protocol. Before Let's Encrypt can issue a TLS certificate for the Teleport Proxy host's domain, the ACME protocol must verify that an HTTPS server is reachable on port 443 of the host.

You can configure the Teleport Proxy service to complete the Let's Encrypt verification process when it starts up.

Run the following teleport configure command, where tele.example.com is the domain name of your Teleport cluster and [email protected] is an email address used for notifications (you can use any domain):

teleport configure --acme [email protected] --cluster-name=tele.example.com > /etc/teleport.yaml

The --acme, --acme-email, and --cluster-name flags will add the following settings to your Teleport configuration file:

proxy_service:
  enabled: "yes"
  web_listen_addr: :443
  public_addr: tele.example.com:443
  acme:
    enabled: "yes"
    email: [email protected]

Port 443 on your Teleport Proxy Service host must allow traffic from all sources.

Next, start the Teleport Auth and Proxy Services:

sudo teleport start

If you do not have a Teleport Cloud account, use our signup form to get started. Teleport Cloud manages instances of the Proxy Service and Auth Service, and automatically issues and renews the required TLS certificate.

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  11.0.3
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  10.3.8
CA pin   sha256:sha-hash-here

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

Step 2/2. Run the discovery wizard

In your web browser, access the teleport Web UI at teleport.example.com. Click on your user name at the top right and select Manage Access, Select "Desktop" from the main menu, then NEXT:

If you already have Active Directory installed, skip to the next step. Otherwise, copy and paste the first command provided into a Windows PowerShell window. If you aren't already running AD Certificate services, copy and paste the second command after the first one completes and the server restarts:

Install Active Directory

Once the server is restarted from one or both command executions, click NEXT.

Copy and paste the provided command into a Windows PowerShell window to download and run the 'configure Active Directory' script:

Configure Active Directory

Click NEXT.

The PowerShell script will output a Teleport configuration block. Copy this block to a temporary location. Click Next.

On the Linux host you installed Teleport to run as the Desktop Access connector, edit /etc/teleport.yaml and paste the configuration provided by the output of the previous step. Review and edit the addition as necessarily for your environment:

version: v3
teleport:
  auth_token: 2239...c5b21
  proxy_server: teleport.example.com:443

auth_service:
  enabled: no
ssh_service:
  enabled: no
proxy_service:
  enabled: no

windows_desktop_service:
  enabled: yes
  ldap:
    addr:     '10.10.1.50:636'
    domain:   'windows.teleport.example.com'
    username: 'WIN\svc-teleport'
    server_name: 'windows-server-hostname'
    insecure_skip_verify: false
    ldap_ca_cert: |
        -----BEGIN CERTIFICATE-----
        MIIDnzCCAoegAwIBAgIQT/UIn+MT4aZC9ix/QuiV9zANBgkqhkiG9w0BAQsFADBi
        ...
        31qA4dO3if7RdikD9hVbiIF9jQ==
        -----END CERTIFICATE-----

  discovery:
    base_dn: '*'
  labels:
    teleport.internal/resource-id: 42d8859c-60d0-4d7f-9767-bdd66b63fce6

Click Next.

Once you've saved /etc/teleport.yaml, start Teleport:

This command assumes the root user. Prepend sudo otherwise.

systemctl start teleport.service

Copy the join token to a file on the instance where you will run the Windows Desktop Service, and then use the following configuration:

version: v3
teleport:
  auth_token: /path/to/token
  proxy_server: teleport.example.com # replace with your proxy address
windows_desktop_service:
  enabled: yes
  ldap:
    # Port must be included for the addr.
    # LDAPS port is 636 by default,
    # e.g. example.com:636
    addr: "$LDAP_SERVER_ADDRESS"
    domain: "$LDAP_DOMAIN_NAME"
    username: '$LDAP_USERNAME'
    # This should be the path to the certificate exported in Step 4.
    der_ca_file: /path/to/cert
  discovery:
    base_dn: "*"
auth_service:
  enabled: no
proxy_service:
  enabled: no
ssh_service:
  enabled: no

From the directory containing the Teleport binary:

./teleport start --config=/etc/teleport.yaml

Copy the join token to a file on the instance where you will run Windows Desktop Service, and then use the following configuration:

version: v3
teleport:
  auth_token: /path/to/token
  proxy_server: mytenant.teleport.sh # replace with your cloud tenant
windows_desktop_service:
  enabled: yes
  ldap:
    # Port must be included for the addr.
    # LDAPS port is 636 by default,
    # e.g. example.com:636
    addr: "$LDAP_SERVER_ADDRESS"
    domain: "$LDAP_DOMAIN_NAME"
    username: '$LDAP_USERNAME'
    # This should be the path to the certificate exported in Step 5.
    der_ca_file: /path/to/cert
  discovery:
    base_dn: "*"
auth_service:
  enabled: no
proxy_service:
  enabled: no
ssh_service:
  enabled: no

The access wizard will detect when the new Teleport instance has joined the cluster, and you can then click Next.

Teleport will discover available Windows desktops in the domain, and list them under Desktops. Click Finish then BROWSE EXISTING RESOURCES to see them:

Desktops Discovered

Troubleshooting

If you hit any issues, check out the Troubleshooting documentation for common problems and solutions.

Have a suggestion or can’t find something?
IMPROVE THE DOCS