Desktop Access with Active Directory

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

Azure AD

Microsoft's Azure Active Directory (Azure AD) offering does not support the Kerberos authentication protocol, which is required for Teleport's certificate-based authentication.

At this time, Teleport does not support integration with Azure AD, however Teleport Enterprise customers can access Windows desktops (including those joined to Azure AD) using local accounts via the process described in Getting Started with Desktop Access.

Compare Desktop Access to other RDP clients

The Teleport Desktop Service is designed 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 the Desktop Service 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

• A running Teleport cluster version 14.3.33 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• 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.
• An Active Directory domain, configured for LDAPS (Teleport requires an encrypted LDAP connection). Typically this means installing AD CS.

Step 1/2. Run the discovery wizard

In this step, you will use the Teleport Web UI to download and run two scripts:

• An Active Directory installation script to run on your Windows Server host
• An installation script for the Teleport Desktop Service, which you will run on your Linux host

Install Active Directory

In your web browser, access the Teleport Web UI at the address of your Proxy Service host, e.g., example.teleport.sh. Go to the Desktops section, then select Add Desktop. Select Active Directory resource to start the guided enrollment from the Enroll New Resource section.

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

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:

Click NEXT.

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

Install the Teleport Desktop Service

On the Linux host where you will run the Teleport Desktop Service, create a file called /etc/teleport.yaml and paste the configuration provided by the output of the previous step.

tip

If you would like to run the Teleport Desktop Service from a Teleport process that is already running other services, copy and paste only the windows_desktop_service section.

The configuration file will resemble the following:

version: v3
teleport:
  auth_token: abcd123-insecure-do-not-use-this
  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 prevents teleport from authenticating the LDAP CA
    # against the systems trust store.
    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

Install the Teleport Desktop Service on your Linux host.

Select an edition, then follow the instructions for that edition to install Teleport.

Teleport Community Edition

The following command updates the repository for the package manager on the local operating system and installs the provided Teleport version:

$ curl https://cdn.teleport.dev/install-v14.3.33.sh | bash -s 14.3.33

Teleport Enterprise

Debian 9+/Ubuntu 16.04+ (apt)

# 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 v14. You'll need to update this
# file for each major release of Teleport.
$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v14" \
| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

$ sudo apt-get update
$ sudo apt-get install teleport-ent

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

$ sudo apt-get install teleport-ent-fips

Amazon Linux 2/RHEL 7 (yum)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for v14. You'll need to update this
# file for each major release of Teleport.
# First, get the major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
$ sudo yum install -y yum-utils
$ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"
$ sudo yum install teleport-ent
#
# 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

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

$ sudo yum install teleport-ent-fips

Amazon Linux 2/RHEL 7 (zypper)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport Zypper repository for v14. You'll need to update this
# file for each major release of Teleport.
# First, get the OS major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
# Use zypper to add the teleport RPM repo
$ sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")
$ sudo yum install teleport-ent
#
# 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

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

$ sudo yum install teleport-ent-fips

Amazon Linux 2023/RHEL 8+ (dnf)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for v14. You'll need to update this
# file for each major release of Teleport.
# First, get the major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
# Use the dnf config manager plugin to add the teleport RPM repo
$ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport.repo")"

# Install teleport
$ sudo dnf install teleport-ent

# 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

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

$ sudo dnf install teleport-ent-fips

SLES 12 SP5+ and 15 SP5+ (zypper)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport Zypper repository.
# First, get the OS major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
# Use Zypper to add the teleport RPM repo
$ sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v14/teleport-zypper.repo")

# Install teleport
$ sudo zypper install teleport-ent

For FedRAMP/FIPS-compliant installations, install the teleport-ent-fips package instead:

$ sudo zypper install teleport-ent-fips

Tarball

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://cdn.teleport.dev/teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz
$ shasum -a 256 teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-bin.tar.gz
# Verify that the checksums match
$ tar -xvf teleport-ent-v14.3.33-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://cdn.teleport.dev/teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256
# <checksum> <filename>
$ curl -O https://cdn.teleport.dev/teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-fips-bin.tar.gz
$ shasum -a 256 teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-fips-bin.tar.gz
# Verify that the checksums match
$ tar -xvf teleport-ent-v14.3.33-linux-$SYSTEM_ARCH-fips-bin.tar.gz
$ cd teleport-ent
$ sudo ./install

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
stable/<major>	Receives releases for the specified major release line, i.e. v14
stable/cloud	Rolling channel that receives releases compatible with current Cloud version
stable/rolling	Rolling channel that receives all published Teleport releases

Teleport Enterprise Cloud

Debian 9+/Ubuntu 16.04+ (apt)

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 cloud.
$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/cloud" \
| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null

# Provide your Teleport domain to query the latest compatible Teleport version
$ export TELEPORT_DOMAIN=example.teleport.com
$ export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

# Update the repo and install Teleport and the Teleport updater
$ sudo apt-get update
$ sudo apt-get install "teleport-ent=$TELEPORT_VERSION" teleport-ent-updater

Amazon Linux 2/RHEL 7/CentOS 7 (yum)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for cloud.
# First, get the OS major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
$ sudo yum install -y yum-utils
$ sudo yum-config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

# Provide your Teleport domain to query the latest compatible Teleport version
$ export TELEPORT_DOMAIN=example.teleport.com
$ export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

# Install Teleport and the Teleport updater
$ sudo yum install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

# 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

Amazon Linux 2023/RHEL 8+ (dnf)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport YUM repository for cloud.
# First, get the OS major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
# Use the dnf config manager plugin to add the teleport RPM repo
$ sudo dnf config-manager --add-repo "$(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-yum.repo")"

# Provide your Teleport domain to query the latest compatible Teleport version
$ export TELEPORT_DOMAIN=example.teleport.com
$ export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

# Install Teleport and the Teleport updater
$ sudo dnf install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

# 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

SLES 12 SP5+ and 15 SP5+ (zypper)

# Source variables about OS version
$ source /etc/os-release
# Add the Teleport Zypper repository for cloud.
# First, get the OS major version from $VERSION_ID so this fetches the correct
# package version.
$ VERSION_ID=$(echo $VERSION_ID | grep -Eo "^[0-9]+")
# Use Zypper to add the teleport RPM repo
$ sudo zypper addrepo --refresh --repo $(rpm --eval "https://zypper.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/cloud/teleport-zypper.repo")

# Provide your Teleport domain to query the latest compatible Teleport version
$ export TELEPORT_DOMAIN=example.teleport.com
$ export TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

# Install Teleport and the Teleport updater
$ sudo zypper install "teleport-ent-$TELEPORT_VERSION" teleport-ent-updater

OS repository channels

The following channels are available for APT, YUM, and Zypper repos. They may be used in place of stable/v14 anywhere in the Teleport documentation.

Channel name	Description
stable/<major>	Receives releases for the specified major release line, i.e. v14
stable/cloud	Rolling channel that receives releases compatible with current Cloud version
stable/rolling	Rolling channel that receives all published Teleport releases

Is my Teleport instance compatible with Teleport Enterprise Cloud?

Before installing a teleport binary with a version besides v16, read our compatibility rules to ensure that the binary is compatible with Teleport Enterprise Cloud.

Teleport uses Semantic Versioning. Version numbers include a major version, minor version, and patch version, separated by dots. When running multiple teleport binaries within a cluster, the following rules apply:

• Patch and minor versions are always compatible, for example, any 8.0.1 component will work with any 8.0.3 component and any 8.1.0 component will work with any 8.3.0 component.
• Servers support clients that are one major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service instance is compatible with 7.x.x agents and 7.x.x tsh, but we don't guarantee that a 9.x.x agent will work with an 8.x.x Proxy Service instance. This also means you must not attempt to upgrade from 6.x.x straight to 8.x.x. You must upgrade to 7.x.x first.
• Proxy Service instances and agents do not support Auth Service instances that are on an older major version, and will fail to connect to older Auth Service instances by default. You can override version checks by passing --skip-version-check when starting agents and Proxy Service instances.

In the Teleport Web UI, click Next.

Step 2/2. Start Teleport

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

Configure the Teleport Desktop Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Desktop Service.

Package Manager

On the host where you will run the Teleport Desktop Service, enable and start Teleport:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

TAR Archive

On the host where you will run the Teleport Desktop Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:

$ sudo teleport install systemd -o /etc/systemd/system/teleport.service
$ sudo systemctl enable teleport
$ sudo systemctl start teleport

You can check the status of the Teleport Desktop Service with systemctl status teleport and view its logs with journalctl -fu teleport.

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:

Troubleshooting

If you hit any issues, check out the Troubleshooting documentation for common problems and solutions. For information about configuring Windows-specific role permissions, see Role-Based Access Control for Desktops.