Desktop Access with Active Directory (Manual)

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). Typically this means installing AD CS

• 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 >= 12.1.1

  Make sure you can connect to Teleport

  oss

  enterprise

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

  Make sure you can connect to Teleport

  cloud

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

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

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"

2. 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).

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.

1. Get the Teleport user CA certificate by running:

tctl auth export --type=windows > user-ca.cer

2. Transfer the user-ca.cer file to a Windows machine where you can manage your group policy.

Create another GPO and import the Teleport CA

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.

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

Publish the Teleport CA to the Active Directory domain

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.

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.

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.

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

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. Next, 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

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.

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.

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

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

Use the appropriate commands for your environment to install your package.

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 v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \| sudo tee /etc/apt/sources.list.d/teleport.list > /dev/null
sudo apt-get update
sudo apt-get install teleport

Source variables about OS version
source /etc/os-release
Add the Teleport YUM repository for v12. You'll need to update this
file for each major release of Teleport.
Note: if using a fork of RHEL/CentOS or Amazon Linux you may need to use '$ID_LIKE'
and the codename your distro was forked from instead of '$ID'
Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L133-L153
sudo yum-config-manager --add-repo $(rpm --eval "https://yum.releases.teleport.dev/$ID/$VERSION_ID/Teleport/%{_arch}/stable/v12/teleport.repo")
sudo yum install teleport
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
Optional:  Use DNF on newer distributions
$ sudo dnf config-manager --add-repo https://rpm.releases.teleport.dev/teleport.repo
$ sudo dnf install teleport

curl https://get.gravitational.com/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport
sudo ./install

dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.deb
Selecting previously unselected package teleport-ent.
(Reading database ... 30810 files and directories currently installed.)
Preparing to unpack teleport-ent_12.1.1_$SYSTEM_ARCH.deb ...
Unpacking teleport-ent 12.1.1 ...
Setting up teleport-ent 12.1.1 ...

rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpm
warning: teleport-ent-12.1.1.$SYSTEM-ARCH.rpm: Header V4 RSA/SHA512 Signature, key ID 6282c411: NOKEY

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gz
cd teleport-ent
sudo ./install

curl https://get.gravitational.com/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz.sha256
<checksum> <filename>
curl -O https://cdn.teleport.dev/teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
shasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
Verify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gz
cd teleport-ent
sudo ./install

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.

tctl tokens add --type=windowsdesktop

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

Start Teleport after updating /etc/teleport.yaml:

sudo teleport start -c /etc/teleport.yaml

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

Create the role:

tctl create -f windows-desktop-admins.yaml

Assign the windows-desktop-admins role to your Teleport user by running the following commands, depending on whether you authenticate as a local Teleport user or via the github, saml, or oidc authentication connectors:

tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml

  roles:
   - access
   - auditor
   - editor
+  - windows-desktop-admins

tctl create -f out.yaml

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

  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - windows-desktop-admins

tctl create -f github.yaml

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

  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - windows-desktop-admins

tctl create -f saml.yaml

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

  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - windows-desktop-admins

tctl create -f saml.yaml

Log out of your Teleport cluster and log in again to assume the new 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:

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.