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.7To connect to Teleport, log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster 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 usetctl
remotely:tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster 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
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
- 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"
- Create the new GPO by running (from the same prompt):
New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
Deny interactive login
- 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 selectEdit...
from the context menu. - Select:
Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment
- Double click
Deny log on locally
and in the popup, checkDefine these policy settings
. - Then click
Add User or Group...
,Browse ...
, enter the SAM account name of the user you created above (svc-teleport
) and hitCheck Names
select your Group, and then hitOK
on all the windows. - Repeat steps 3 and 4 for
Deny log on through Remote Desktop Services
(in lieu ofDeny 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.
These steps will need to be repeated if Teleport's user certificate authority is rotated.
- Get the Teleport user CA certificate by running:
tctl auth export --type=windows > user-ca.cer
- Transfer the
user-ca.cer
file to a Windows machine where you can manage your group policy.
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
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.
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.
- 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)
- Again open the
Group Policy Management
program, and on the left pane, navigate to$FOREST > Domains > $DOMAIN > Group Policy Objects
. - Right click on the GPO you just made (
Teleport Access Policy
), and selectEdit...
. - In the group policy editor, select:
Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies
- Right click on
Trusted Root Certification Authorities
and selectImport
. - Click through the wizard, selecting your CA file.
Publish the Teleport CA to the Active Directory domain
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.
- Publish the CA to LDAP:
certutil –dspublish –f <PathToCertFile.cer> NTAuthCA
- 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.
- Still editing your
Teleport Access Policy
, select:
Computer Configuration > Policies > Windows Settings > Security Settings > System Services
- Double click on
Smart Card
, selectDefine this policy setting
and switch toAutomatic
then clickOK
.
Open firewall to inbound RDP connections
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.
- Select:
Computer Configuration > Policies > Windows Settings > Security Settings > Windows Firewall with Advanced Security (x2)
- Right click on
Inbound Rules
and selectNew Rule...
. - Under
Predefined
selectRemote Desktop
. - Only select the rule for
User Mode (TCP-in)
. - On the next screen, select
Allow the connection
and finish.
Allow remote RDP connections
- Next, select:
Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections
- Right click on
Allow users to connect remotely by using Remote Desktop Services
and selectEdit
. SelectEnabled
andOK
. - Select:
Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security
- Right click
Require user authentication for remote connections by using Network Level Authentication
, edit, selectDisable
andOK
.
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
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.
- Open the Microsoft Management Console (MMC)
Start > Control Panel > Administrative Tools > Certificate Authority
- Open your CA computer and right-click on
Certificate Templates
, then selectManage
. - Find the
Computer
template on the list, right-click on it, then selectDuplicate Template
. - In the
Compatibility
tab changeCertification Authority
toWindows Server 2012 R2
and clickOK
. - In the same tab change
Certificate recipient
toWindows Server 2012 R2
and clickOK
. - Go to the
General
tab and changeTemplate display name
toRemoteDesktopAccess
. Make sureTemplate name
is alsoRemoteDesktopAccess
. - In the
Cryptography
tab changeProvider Category
toKey Storage Provider
, thenAlgorithm name
toECDH_P384
. Also, changeRequest hash
toSHA384
. - Next, in the
Extensions
tab selectApplication Polices
and click theEdit
button. - Remove all entries from the list.
- Go to the
Security
tab, selectDomain Controllers
and give the groupRead
andEnroll
permissions. - Finally, create a template by clicking
OK
. - 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.
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
- Begin by navigating to
Start > Control Panel > Administrative Tools > Certificate Authority
to open the CA Microsoft Management Console (MMC) GUI. - Right click on your CA computer and select
Properties
. - From
General
tab, clickView Certificate
. - Select the
Details
view and clickCopy to File
. - Click
Next
in the Certificate Export Wizard, and ensure thatDER encoded binary X.509 (.CER)
is selected - 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
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"]
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:
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.