Fork me on GitHub
Teleport

Getting Started With Desktop Access

Improve
Getting started with Teleport Desktop Access for Windows Servers

Getting started with Teleport Desktop Access for Windows Servers

Length: 24:47

Getting Started

In this guide we will connect an Active Directory domain to Teleport using Desktop Access and log into a Windows desktop from that domain.

Prerequisites

This guide requires you to have:

  • An Active Directory domain, configured for LDAPS (Teleport requires an encrypted LDAP connection)

  • Access to a Domain Controller

  • An existing Teleport cluster with one of the following versions:

    Open Source or Enterprise: version 8.0 or newer

    Teleport Cloud: version 9.0 or newer

    See Teleport Getting Started if you're new to Teleport.

  • A Linux server to run the Teleport Desktop Access service on.

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

  • The tctl administration tool version >= 9.3.7

    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 9.3.7

    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 9.3.8

    CA pin sha256:sha-hash-here

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

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

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
  1. Double click Deny log on locally and in the popup, check Define these policy settings.
  2. 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.
  3. Repeat steps 3 and 4 for Deny log on through Remote Desktop Services (in lieu of Deny log on locally).

Deny Interactive Login

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.

User CA Rotation

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

  1. Get the Teleport user CA certificate by running:
tctl auth export --type=windows > user-ca.cer
  1. Transfer the user-ca.cer file to a Windows machine where you can manage your group policy.
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)
  1. Again open the Group Policy Management program, and on the left pane, navigate to $FOREST > Domains > $DOMAIN > Group Policy Objects.
  2. Right click on the GPO you just made (Teleport Access Policy), and select Edit....
  3. In the group policy editor, select:
Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
  1. Right click on Trusted Root Certification Authorities and select Import.
  2. 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
  1. 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
  1. Double click on Smart Card, select Define this policy setting and switch to Automatic then click OK.

Enable Smartcard

Open firewall to inbound RDP connections

Warning

During testing on a Windows Server 2012 R2 server, we found that the following firewall rule would sometimes mysteriously dissapear. If connections through Teleport later appear to be hanging for a few seconds and then failing, double check that this rule is still in effect.

  1. Select:
Computer Configuration > Policies > Windows Settings > Security Settings > Windows Firewall with Advanced Security (x2)
  1. Right click on Inbound Rules and select New Rule....
  2. Under Predefined select Remote Desktop.
  3. Only select the rule for User Mode (TCP-in).
  4. On the next screen, select Allow the connection and finish.

Open the Firewall

Allow remote RDP connections

  1. Next, select:
Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections
  1. Right click on Allow users to connect remotely by using Remote Desktop Services and select Edit. Select Enabled and OK.
  2. Select:
Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security
  1. Right click Require user authentication for remote connections by using Network Level Authentication, edit, select Disable and OK.

Disable Require

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 Domain Controller 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
  1. Open your CA computer and right-click on Certificate Templates, then select Manage.
  2. Find the Computer template on the list, right-click on it, then select Duplicate Template.
  3. In the Compatibility tab change Certification Authority to Windows Server 2012 R2 and click OK.
  4. In the same tab change Certificate recipient to Windows Server 2012 R2 and click OK.
  5. Go to the General tab and change Template display name to RemoteDesktopAccess. Make sure Template name is also RemoteDesktopAccess.
  6. In the Cryptography tab change Provider Category to Key Storage Provider, then Algorithm name to ECDH_P384. Also, change Request hash to SHA384.
  7. Next, in the Extensions tab select Application Polices and click the Edit button.
  8. Remove all entries from the list.
  9. Go to the Security tab, select Domain Controllers and give the group Read and Enroll permissions.
  10. Finally, create a template by clicking OK.
  11. Go back to the Certificate Authority window and right-click on Certificate Templates. Then:
New > Certificate Template to Issue

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

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

Teleport CA

Prior to v8.0, the Teleport CA was not compatible with Windows logins. If you're setting up Desktop Access in an existing cluster created before v8.0, you must first perform a CA rotation in order to resolve this.

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

windows_desktop_service:
  enabled: yes
  listen_addr: "0.0.0.0:3028"
  ldap:
    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: "*"

For Teleport Cloud, Windows Desktop Service should establish a reverse tunnel to the hosted proxy. This requires setting auth_servers 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:

teleport:
  auth_token: /path/to/token
  auth_servers:
  - mytenant.teleport.sh # replace with your cloud tenant
windows_desktop_service:
  enabled: yes
  ldap:
    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: "*"

After updating teleport.yaml, start Teleport as usual using teleport start.

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:

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

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

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.

Connect to your Windows desktop

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

On the left pane, select Desktops (preview). 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.

Troubleshooting

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