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

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

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

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

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.

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.

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.

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

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

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: "*"

tctl tokens add --type=windowsdesktop

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

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:

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.