Fork me on GitHub

Teleport

Desktop Access with Active Directory (Manual)

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise
Getting started with Teleport Desktop Access for Windows Servers

Getting started with Teleport Desktop Access for Windows Servers

Length: 24:47

This guide demonstrates how to connect an Active Directory domain to Teleport using the Desktop Service and log into a Windows desktop from that domain.

Use The Wizard

Starting with Teleport 10.2.6, you can install Active Directory and configure the Teleport Desktop Service through the Teleport Web UI. See Desktop Access with Active Directory for more information.

Teleport Enterprise users can configure Windows Access for local users by following Getting Started with Windows Access.

Continue with this guide if:

  • You're running an older version of Teleport and can't upgrade.
  • You want to install the Desktop Service using the same instance of teleport running the Proxy/Auth Services.

Prerequisites

This guide requires you to have:

  • An Active Directory domain, configured for LDAPS (Teleport requires an encrypted LDAP connection). Typically this means installing AD CS
Azure AD

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

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.

  • Access to a Domain Controller
  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.0.0.

    You can download these tools by visiting your Teleport account workspace.

  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 14.0.0.

    See Installation for details.

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.0.0.

    You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21


tsh version

Teleport v13.3.9 go1.21

Proxy version: 13.3.9Proxy: teleport.example.com
  • A Linux server to run the Teleport Desktop Service on.

    You can reuse an existing server running any other Teleport instance.

  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:

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

    Cluster teleport.example.com

    Version 14.0.0

    CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/7. Create a restrictive service account

Teleport requires a service account to connect to your Active Directory domain. We recommend creating a dedicated service account with restrictive permissions for maximum security.

To create the service account, open a PowerShell prompt and copy-paste in the commands below. A password for this service account will be randomly generated, but immediately discarded. Teleport does not need this password, as it uses x509 certificates for LDAP authentication. You can reset the password for this account should you need to perform password authentication.

$Name="Teleport Service Account"
$SamAccountName="svc-teleport"

# Generate a random password that meets the "Password must meet complexity
# requirements" security policy setting.
# Note: if the minimum complexity requirements have been changed from the
# Windows default, this part of the script may need to be modified.
Add-Type -AssemblyName 'System.Web'
do {
   $Password=[System.Web.Security.Membership]::GeneratePassword(15,1)
} until ($Password -match '\d')
$SecureStringPassword=ConvertTo-SecureString $Password -AsPlainText -Force

New-ADUser `
  -Name $Name `
  -SamAccountName $SamAccountName `
  -AccountPassword $SecureStringPassword `
  -Enabled $true

Next, in the same PowerShell prompt, enter the following commands to limit your service account's permissions.

# Save your domain's distinguished name to a variable.
$DomainDN=$((Get-ADDomain).DistinguishedName)

# Create the CDP/Teleport container.
# If the command fails with "New-ADObject : An attempt was made to add an object
# to the directory with a name that is already in use", it means the object
# already exists and you can move on to the next step.
New-ADObject -Name "Teleport" -Type "container" -Path "CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN"

# Gives Teleport the ability to create LDAP containers in the CDP container.
dsacls "CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):CC;container;"
# Gives Teleport the ability to create and delete cRLDistributionPoint objects in the CDP/Teleport container.
dsacls "CN=Teleport,CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):CCDC;cRLDistributionPoint;"
# Gives Teleport the ability to write the certificateRevocationList property in the CDP/Teleport container.
dsacls "CN=Teleport,CN=CDP,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN " /I:T /G "$($SamAccountName):WP;certificateRevocationList;"
# Gives Teleport the ability to create and delete certificationAuthority objects in the NTAuthCertificates container.
dsacls "CN=NTAuthCertificates,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):CCDC;certificationAuthority;"
# Gives Teleport the ability to write the cACertificate property in the NTAuthCertificates container.
dsacls "CN=NTAuthCertificates,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):WP;cACertificate;"

To save yourself time later, you can use the same prompt to get the security identifier of your new service account by running this command:

Get-AdUser -Identity $SamAccountName | Select SID

Note this value (beginning with "S-") down, as it will be used as the sid field in the ldap section of your configuration file in a later step.

Step 2/7. Prevent the service account from performing interactive logins

gpupdate.exe

Throughout this step and the next one, you will be modifying GPOs, and sometimes GPO modifications can take some time to propagate to all hosts. You can force your changes to take effect immediately on your current host at any time by opening a PowerShell prompt and running gpupdate.exe /force (though their effects may still take time to propagate to other machines on the domain).

The Teleport service account is only needed to authenticate over LDAP, meaning that it needn't be able to log in to Windows machines like an ordinary user. Restrict it from doing so by creating a new Group Policy Object (GPO) linked to your entire domain, and then deny it interactive login.

Create a GPO

  1. Open a PowerShell prompt and change the $GPOName variable below to your desired GPO name, or leave the recommended name:
$GPOName="Block teleport-svc Interactive Login"
  1. Create the new GPO by running (from the same prompt):
New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)

Deny interactive login

  1. Open the program named Group Policy Management and find the GPO you just created ($FOREST > Domains > $DOMAIN > Group Policy Objects > Block teleport-svc Interactive Login), right-click on it and select Edit... from the context menu.

  2. Select:

    Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment
    
  3. Double click Deny log on locally and in the popup, check Define these policy settings.

  4. Then click Add User or Group..., Browse ..., enter the SAM account name of the user you created above (svc-teleport) and hit Check Names select your Group, and then hit OK on all the windows.

  5. Repeat steps 3 and 4 for Deny log on through Remote Desktop Services (in lieu of Deny log on locally).

Deny Interactive Login
Disabling Password Authentication

For added security, consider disabling username/password authentication completely via the GPO, requiring access via Teleport's virtual smart card.

Step 3/7. Configure a GPO to allow Teleport connections

Next, we need to configure a GPO to allow Teleport desktop sessions. This includes telling your computers to trust Teleport's CA, allowing the certificate-based smart card authentication, and ensuring RDP is enabled.

Export the Teleport CA

The following step requires an existing cluster. If you don't already have a Teleport cluster up and running, see our general Getting Started guide to set up a demo cluster.

User CA Rotation

These steps will need to be repeated if Teleport's user certificate authority is rotated.

Get the Teleport user CA certificate by running the following in the Windows machine where you can manage your group policy, assigning proxy to the address of your Teleport Proxy Service:

curl -o user-ca.cer https://proxy/webapi/auth/export?type=windows
Take note of the location

Take note of the path to the user-ca.cer file, as you will need this in the next step.

Create another GPO and import the Teleport CA

Domain Wide Policy

For the purposes of this guide, we apply the GPO we are about to create to our entire AD domain. In the case where you wish for only a subset of computers within your AD domain to be accessible via Teleport, you should apply the GPO to an OU that includes only such computers.

Differences when using AWS Managed Active Directory

When using AWS Managed Active Directory, AWS Delegated Domain Administrator accounts are not granted permissions to apply GPOs at the domain level.

Instead, you should apply this GPO to the automatically-created OU with the NetBIOS domain name containing Computers and Users which is nested one level beneath the domain root.

AWS Managed AD OU Location
  1. Create another new GPO, this time giving it a name like Teleport Access Policy:

    $GPOName="Teleport Access Policy"
    New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
    
  2. Open the Group Policy Management program, and on the left pane, navigate to $FOREST > Domains > $DOMAIN > Group Policy Objects.

  3. Right click on the GPO you just made (Teleport Access Policy), and select Edit....

  4. In the group policy editor, select:

    Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
    
  5. Right click on Trusted Root Certification Authorities and select Import.

  6. Click through the wizard, selecting your CA file.

    Import Teleport CA

Publish the Teleport CA to the Active Directory domain

Differences when using AWS Managed Active Directory

When using AWS Managed Active Directory, you should run this command using an account which is part of the AWS Delegated Domain Administrators group, such as the AWS-provided admin account.

On a machine which is joined to your domain and logged in as an account in the Domain Administrators group, run the two commands below at a PowerShell prompt to publish the Teleport CA to your Active Directory domain (using the path to the exported Teleport user-ca.cer file that you copied above):

certutil –dspublish –f <PathToCertFile.cer> RootCA

This step enables the domain controllers to trust the Teleport CA, which will allow smart card logons via Teleport to succeed.

Publish the Teleport CA to the NTAuth Store

In order for authentication with Teleport-issued certificates to succeed, the Teleport CA needs to be published to the enterprise NTAuth store. Teleport will periodically publish its CA after it is able to authenticate, but this step needs to be performed manually the first time in order for Teleport to have LDAP access.

  1. Publish the CA to LDAP:

    certutil –dspublish –f <PathToCertFile.cer> NTAuthCA
    
  2. Force the retrieval of the CA from LDAP. While this step is not required, it speeds up the process and allows you to proceed to the next steps without waiting for the certificate to propagate.

    certutil -pulse
    

Enable the Smart Card service

Teleport performs certificate based authentication by emulating a smart card.

  1. Still editing your Teleport Access Policy, select:

    Computer Configuration > Policies > Windows Settings > Security Settings > System Services
    
  2. Double click on Smart Card, select Define this policy setting and switch to Automatic then click OK.

    Enable the Smart Card Service

Allow remote RDP connections

  1. Next, select:

    Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections
    
  2. Right click on Allow users to connect remotely by using Remote Desktop Services and select Edit. Select Enabled and OK.

  3. Select:

    Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security
    
  4. Right click Require user authentication for remote connections by using Network Level Authentication, edit, select Disable and OK.

    Disable Require user authentication...
  5. Right click Always prompt for password upon connection, edit, select Disabled and . Teleport's smart card based authentication generates a random smart card PIN for each desktop session and provides the PIN to the desktop during the RDP connection establishment. Since the PIN is never provided to the Teleport user, this setting must be disabled in order for authentication to complete.

Allow credentials to be provided over RDP

Select:

Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security > "Always prompt for password upon connection"

Set to Disabled and click OK.

Open firewall to inbound RDP connections

  1. Select:

    Computer Configuration > Policies > Windows Settings > Security Settings > Windows Firewall with Advanced Security (x2)
    
  2. Right click on Inbound Rules and select New Rule....

  3. Under Predefined select Remote Desktop.

  4. Only select the rule for User Mode (TCP-in).

  5. On the next screen, select Allow the connection and finish.

    Open the Firewall

Ensure your GPO is updated

If you have not done so already, ensure your GPO is updated by opening a PowerShell prompt and running:

gpupdate.exe /force

Step 4/7. Configure a certificate for RDP connections

Secure Cipher Suites

Teleport's RDP client supports only secure algorithms for making TLS connections, so we have to configure our Domain Controller to support those cipher suites as well. This step is only necessary for Windows Server 2012 R2 as it does not support secure algorithms by default. If it does not apply to you, you can skip this step and go to the next step.

In this step we'll create a new certificate template that uses elliptic curve cryptography, and then configure our GPO to use the newly created template to issue certificates used for Remote Desktop connections.

Create a certificate template

In this section, we will create a certificate template that uses elliptic curve P-384 and uses SHA384 as the signature algorithm.

  1. Open the Microsoft Management Console (MMC)

    Start > Control Panel > Administrative Tools > Certificate Authority
    
  2. Open your CA computer and right-click on Certificate Templates, then select Manage.

  3. Find the Computer template on the list, right-click on it, then select Duplicate Template.

  4. In the Compatibility tab change Certification Authority to Windows Server 2012 R2 and click OK.

  5. In the same tab change Certificate recipient to Windows Server 2012 R2 and click OK.

  6. Go to the General tab and change Template display name to RemoteDesktopAccess. Make sure Template name is also RemoteDesktopAccess.

  7. In the Cryptography tab change Provider Category to Key Storage Provider, then Algorithm name to ECDH_P384. Also, change Request hash to SHA384.

  8. In the Extensions tab select Application Polices and click the Edit button.

  9. Remove all entries from the list.

  10. Go to the Security tab, select Domain Computers and give the group Read and Enroll permissions.

  11. Finally, create a template by clicking OK.

  12. Go back to the Certificate Authority window and right-click on Certificate Templates. Then:

    New > Certificate Template to Issue
    
  13. Select RemoteDesktopAccess and click OK.

Update GPO to use a new certificate template

In the group policy editor for Teleport Access Policy, select:

Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security

Right-click on Server authentication certificate template, Edit, then select Enabled and fill Certificate Template Name with RemoteDesktopAccess.

RDP Certificate Template

Configure server certificate auto-enrollment

In the group policy editor for Teleport Access Policy, select:

Computer Configuration > Policies > Windows Settings > Public Key Policies

Double-click on Certificate Services Client - Auto-Enrollment, then select Enabled in the Configuration Model.

Ensure your GPO is updated

If you have not done so already, ensure your GPO is updated by opening a PowerShell prompt and running:

gpupdate.exe /force

Step 5/7. Export your LDAP CA certificate

Teleport connects to your Domain Controller via LDAPS. This means that you must let Teleport know that the certificate sent by your Domain Controller during the initial SSL connection is trusted. If your Domain Controller's certificate is trusted by the system repository on the system running Teleport, you can skip this step.

If you are unable to acquire the LDAP CA certificate, you can skip TLS verification by setting insecure_skip_verify: true. We do not recommend skipping TLS verification in production environments.

To export a CA certificate

  1. Begin by navigating to Start > Control Panel > Administrative Tools > CertificateAuthority to open the CA Microsoft Management Console (MMC) GUI.
  2. Right click on your CA computer and select Properties.
  3. From General tab, click View Certificate.
  4. Select the Details view and click Copy to File.
  5. Click Next in the Certificate Export Wizard, and ensure that DER encoded binary X.509 (.CER) is selected
  6. Select a name and location for you certificate and click through the wizard.

Now transfer the exported file to the system where you're running Teleport. You can either add this certificate to your system's trusted repository or provide the filepath to the der_ca_file configuration variable.

Step 6/7. Configure Teleport

Install Teleport on the host where you will run the Teleport Desktop Service:

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

Teleport Edition

curl https://goteleport.com/static/install.sh | bash -s 13.3.9

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

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 1 major version behind, but do not support clients that are on a newer major version. For example, an 8.x.x Proxy Service is compatible with 7.x.x resource services and 7.x.x tsh, but we don't guarantee that a 9.x.x resource service will work with an 8.x.x Proxy Service. 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 Services and resource services do not support Auth Services that are on an older major version, and will fail to connect to older Auth Services by default. This behavior can be overridden by passing --skip-version-check when starting Proxy Services and resource services.
curl https://goteleport.com/static/install.sh | bash -s 14.0.0

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

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

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

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

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

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-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v14.0.0-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-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz.sha256

<checksum> <filename>

curl -O https://cdn.teleport.dev/teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v14.0.0-linux-$SYSTEM_ARCH-fips-bin.tar.gz

Verify that the checksums match

tar -xvf teleport-ent-v14.0.0-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 nameDescription
stable/<major>Receives releases for the specified major release line, i.e. v14
stable/cloudRolling channel that receives releases compatible with current Cloud version
stable/rollingRolling channel that receives all published Teleport releases
Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

In order to enable desktop access in Teleport, add the following section in /etc/teleport.yaml on your Linux server. For a detailed description of these configuration fields, see the configuration reference page.

The Teleport Windows Desktop Service will establish a reverse tunnel to the Proxy Service. This requires setting proxy_server to your Proxy Service address and providing a join token.

First, generate a join token with the following command:

tctl tokens add --type=windowsdesktop

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"
    sid: "$LDAP_USER_SID"
    # 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

For Teleport Team and Teleport Enterprise Cloud, the Windows Desktop Service should establish a reverse tunnel to the hosted Teleport Proxy Service. This requires setting proxy_server to your cloud tenant and providing a join token.

First, generate a join token with the following command:

tctl tokens add --type=windowsdesktop

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"
    sid: "$LDAP_USER_SID"
    # 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

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.

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

sudo systemctl enable teleport
sudo systemctl start teleport

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.

Step 7/7. Log in using Teleport

Create a Teleport user/role for Windows Desktop Access

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

For example, you can create a role that gives its users access to all Windows desktop labels and the "Administrator" user. To do so, create a file called windows-desktop-admins.yaml with the following content:

kind: role
version: v5
metadata:
  name: windows-desktop-admins
spec:
  allow:
    windows_desktop_labels:
      "*": "*"
    windows_desktop_logins: ["jsmith"]
RBAC Configuration

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

Usernames shared between domain and local users will create login conflicts.

Create the role:

tctl create -f windows-desktop-admins.yaml

Assign the windows-desktop-admins role to your Teleport user by running the appropriate commands for your authentication provider:

  1. Retrieve your local user's configuration resource:

    tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
  2. Edit out.yaml, adding windows-desktop-admins to the list of existing roles:

      roles:
       - access
       - auditor
       - editor
    +  - windows-desktop-admins 
    
  3. Apply your changes:

    tctl create -f out.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

  1. Retrieve your github authentication connector:

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

    Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.

  2. Edit github.yaml, adding windows-desktop-admins to the teams_to_roles section.

    The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

    Here is an example:

      teams_to_roles:
        - organization: octocats
          team: admins
          roles:
            - access
    +       - windows-desktop-admins
    
  3. Apply your changes:

    tctl create -f github.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

  1. Retrieve your saml configuration resource:

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

    Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

  2. Edit saml.yaml, adding windows-desktop-admins to the attributes_to_roles section.

    The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

    Here is an example:

      attributes_to_roles:
        - name: "groups"
          value: "my-group"
          roles:
            - access
    +       - windows-desktop-admins
    
  3. Apply your changes:

    tctl create -f saml.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

  1. Retrieve your oidc configuration resource:

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

    Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

  2. Edit oidc.yaml, adding windows-desktop-admins to the claims_to_roles section.

    The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

    Here is an example:

      claims_to_roles:
        - name: "groups"
          value: "my-group"
          roles:
            - access
    +       - windows-desktop-admins
    
  3. Apply your changes:

    tctl create -f oidc.yaml
  4. Sign out of the Teleport cluster and sign in again to assume the new role.

Connect to your Windows desktop

At this point everything is ready for Desktop Service connections. Open the Teleport web UI and log in with a user with the role created above.

On the left pane, select Desktops. You should see the list of all computers and Domain Controllers connected to your domain. Select one and click CONNECT on the right, selecting one of the available logins:

Select Desktop

A new tab will open and, after a few seconds, you should be logged in to your target Windows host.

Security hardening

By default, the Default Domain Policy grants the "Add workstations to domain user" right to all authenticated users. As a security best practice, Teleport recommends that this level of access is only granted to administrators or other privileged groups.

To make this change, open the Group Policy Management Console, navigate to $FOREST > Domains > $DOMAIN > Group Policy Objects, right-click on Default Domain Controller Policy and select Edit.

In the Group Policy Editor, navigate to

Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment

Double click the "Add workstations to domain" policy and ensure that the "Authenticated Users" group is not present.

Troubleshooting

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