docs/pages/enroll-resources/desktop-access/active-directory.mdx
This guide demonstrates how to connect an Active Directory domain and how to log into a Windows desktop from the connected domain.
You should note that Teleport requires the Kerberos authentication protocol to support certificate-based authentication for Active Directory. Because Microsoft Entra ID doesn't use Kerberos, you can't use the Teleport Windows Desktop Service for Microsoft Entra ID.
To complete the steps in this guide, verify your environment meets the following requirements:
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
For relatively simple Active Directory environments, you can use the tctl generated configuration script
to bootstrap your Active Directory domain for use with Teleport. At a high level, the script does the following:
Teleport Service Account with the SAM account name svc-teleport and create the necessary LDAP containers.Block teleport-svc Interactive Login.Teleport Access Policy to allow Teleport connections, including:
For more complex Active Directory environments, you may need to modify the generated script to meet your specific requirements. It may also be easier to comprehend what the script does by following the manual configuration steps below.
To use the tctl generated configuration script, run the following command:
# Generate the script and save it to a file named configure-ad.ps1.
tctl desktop bootstrap > configure-ad.ps1
After generating the script, transfer it to a Windows domain controller and run it in a PowerShell console as a domain administrator.
Teleport requires a service account to connect to your Active Directory domain. You should create a dedicated service account with restrictive permissions for maximum security.
To create the service account:
Open PowerShell on a Windows domain computer.
Create a service account with a randomly-generated password by copying and pasting the following script into the PowerShell console:
$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
The password generated for the service account is discarded immediately. Teleport doesn't need the password because it uses x509 certificates for LDAP authentication. You can reset the password for the service account if you need to perform password authentication.
Set the minimum permissions that must granted to the service account by running the following script in the PowerShell console:
# 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"
# Allow Teleport 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;"
# Allow Teleport 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;"
# Allow Teleport 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;"
# Allow Teleport to read the cACertificate property in the NTAuthCertificates container.
dsacls "CN=NTAuthCertificates,CN=Public Key Services,CN=Services,CN=Configuration,$DomainDN" /I:T /G "$($SamAccountName):RP;cACertificate;"
Get the security identifier for the new service account. For example, run the following command:
Get-AdUser -Identity $SamAccountName | Select SID
The command returns the security identifier for the specified account:
SID
---
S-1-5-21-209875886-835680547-4265310078-1113
Copy the full security identifier—beginning with S-—returned.
You'll use this value for the sid field when you configure the ldap settings
in a later step.
The next steps modify group policy objects (GPOs). Changes to group policies
can take time to propagate to all hosts. You can force changes to take effect
immediately on your current host by opening PowerShell and running
gpupdate.exe /force. However, the change might still take time to propagate to other
hosts in the domain.
The Teleport service account is only needed to authenticate over LDAP. The account doesn't need to log on to Windows computers like an ordinary user. You can prevent the service account from being used to log on by creating a new Group Policy Object (GPO) linked to your entire domain, and then denying interactive logins.
Open PowerShell and specify a name for the new group policy object with the $GPOName variable:
$GPOName="Block teleport-svc Interactive Login"
Create the new GPO by running the following command in the PowerShell console:
New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
Open Group Policy Management and expand Forest > Domains > $YOUR_DOMAIN > Group Policy Objects
to locate the group policy object you just created.
Select the group policy object, click Action, then select Edit.
Expand Computer Configuration > Policies > Windows Settings > Security Settings > Local Policies > User Rights Assignment.
Double-click Deny log on locally, then select Define these policy settings.
Click Add User or Group, then click Browse.
Type all or part of the service account name—for example, svc-teleport—then click Check Names.
Verify the Teleport Service Account is selected, then click OK in all the dialogs.
Repeat these steps for Deny log on through Remote Desktop Services.
For added security, you can disable username and password authentication completely. If you disable username and password authentication, only the Teleport virtual smart card can be used to access Windows computers in the domain.
To enable access to Windows desktop sessions through Teleport, you must configure a group policy object that allows Windows computers to trust the Teleport certificate authority and accept certificate-based smart card authentication.
You need to do the following to configure the group policy object:
You must repeat these steps if you rotate the Teleport certificate authority.
To export the Teleport CA certificate:
Log on to a Windows host where you can access Group Policy Management.
Open PowerShell and download the Teleport CA by running the following
command and replacing teleport.example.com with the address of your Teleport cluster:
$ curl.exe -fo teleport.cer https://<Var name="teleport.example.com"/>/webapi/auth/export?type=windows
If you are using Teleport's support for HSM-backed keys, then your Teleport
cluster has multiple CA certificates (one for each Auth Service instance).
You can download a bundle containing all certificates by appending
&format=zip to the URL.
(!docs/pages/includes/desktop-access/windows-ca-note.mdx!)
Take note of the path to file you just downloaded for use in a later step.
To configure the group policy object:
Create a new group policy object with the name Teleport Access Policy by running the following
command:
$GPOName="Teleport Access Policy"
New-GPO -Name $GPOName | New-GPLink -Target $((Get-ADDomain).DistinguishedName)
This command applies the GPO to the entire Active Director domain. If you only want to protect a subset of computers in the domain, you can apply the GPO to a specific organizational unit (OU) that only includes those computers.
If you use AWS Managed Microsoft 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 nested one level inside the domain root.
Open Group Policy Management and expand Forest, Domains, your domain, and Group Policy Objects to locate the GPO you just created.
Select the new GPO—for example, Teleport Access Policy, right-click, then select Edit.
In the group policy editor, expand
Computer Configuration > Policies > Windows Settings > Security Settings > Public Key Policies.
Right-click Trusted Root Certification Authorities, then click Import.
Use the wizard to select and import the Teleport certificate.
If you are using HSM-backed keys, you should repeat this step for each CA certificate.
To ensure your GPO update takes effect immediately on this host, open PowerShell and run the following command (optional):
gpupdate.exe /force
To publish the Teleport certificate in the Active Directory domain:
Log on to a Windows computer that is joined to the Active Directory domain with an account that's a member of the Domain Administrators or AWS Delegated Domain Administrators group.
Open PowerShell and run the following command using the path to the
teleport.cer file you exported from Teleport:
certutil -dspublish -f <Var name="teleport.cer"/> RootCA
This command enables the domain controllers to trust the Teleport CA so that certificate-based smart card authentication through Teleport can succeed.
If you are using HSM-backed keys, you should repeat this step for each CA certificate in the zip file you exported earlier in this guide.
For authentication with Teleport-issued certificates to succeed, the Teleport CA also must be published to the enterprise NTAuth store. Teleport periodically publishes its CA after it is able to authenticate, but this step must be performed manually the first time for Teleport to have LDAP access.
If you are using HSM-backed keys, you should repeat these steps for each CA certificate in the bundle.
To publish the Teleport CA to LDAP:
Open PowerShell and run the following command using the path to the
teleport.cer file:
certutil -dspublish -f <Var name="teleport.cer"/> NTAuthCA
Force the retrieval of the CA from LDAP by running the following command:
certutil -pulse
This step isn't strictly required. However, it allows you to proceed to the next steps without waiting for the certificate to propagate.
Teleport performs certificate-based authentication by emulating a smart card.
To add smart card authentication to your group policy object:
Verify that you have the Teleport Access Policy group policy object open in the
group policy editor.
Expand Computer Configuration > Policies > Windows Settings > Security Settings > System Services.
Double-click Smart Card and select Define this policy setting.
Select Automatic, then click OK.
To ensure your GPO update takes effect immediately on this host, open PowerShell and run the following command (optional):
gpupdate.exe /force
Next you need to configure policies that allow remote connections to domain computers.
Verify that you have the Teleport Access Policy group policy object open in the
group policy editor.
Expand Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections.
Right-click Allow users to connect remotely by using Remote Desktop Services, select Edit, select Enabled, then click OK.
Under Remote Desktop Session Host, select Security.
Right-click Require user authentication for remote connections by using Network Level Authentication, select Edit, select Disabled, then click OK.
<Admonition type="note" title="NLA Support"> Teleport 16.2.0 and later support NLA. If you are running a supported version and enable NLA, you can skip this step. Read more in the [NLA](#network-level-authentication-nla) section. </Admonition>Right-click Always prompt for password upon connection, select Edit, select Disabled, then click OK.
The Teleport certificate-based smart card authentication generates a random smart card PIN for each desktop session and provides the PIN to the desktop when establishing the RDP connection. Because the PIN is never provided to the Teleport user, the Always prompt for password upon connection policy must be disabled for authentication to succeed.
Expand Computer Configuration, Policies, Windows Settings, Security Settings to select Windows Firewall with Advanced Security.
Right-click Inbound Rules, select New Rule.
To ensure your GPO update takes effect immediately on this host, open PowerShell and run the following command (optional):
gpupdate.exe /force
To finish configuring the Teleport Access Policy group policy object, you must
enable RemoteFX. RemoteFX is a compression technology that significantly improves
the performance of remote desktop connections.
Verify that you have the Teleport Access Policy group policy object open in the
group policy editor.
Expand Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment > RemoteFX for Windows Server 2008 R2
Right-click Configure RemoteFX, select Edit, select Enabled, then click OK.
Now left-click Remote Session Environment
(Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Remote Session Environment in the left pane)
and from the items in the right pane, right-click Enable RemoteFX encoding for RemoteFX clients designed for Windows Server 2008 R2 SP1, select Edit, select Enabled, then click OK.
Again left-click Remote Session Environment in the left pane, and from the items in the right pane, right-click Limit maximum color depth, select Edit, select Enabled, then click OK.
Open PowerShell and run the following command to update your Teleport group policy object:
gpupdate.exe /force
The Teleport RDP client requires secure cryptographic algorithms to make TLS connections. However, Windows Server 2012 R2 doesn't support these algorithms by default.
You can configure Windows Server 2012 R2 to support the required algorithms by doing the following:
If your hosts support the required algorithms, you can skip this step and go to Export your LDAP CA certificate.
To create a certificate template that uses elliptic curve P-384 and SHA384 as the signature algorithm:
Click Start, Control Panel, and Administrative Tools to select Certificate Authority.
Open your CA computer, right-click Certificate Templates, then select Manage.
Select the Computer template, right-click, then select Duplicate Template.
Select the Compatibility tab:
Select the General tab:
Select the Cryptography tab:
Select the Extensions tab:
Select the Security tab:
Click OK to create the Template.
Go back to the Certificate Authority console, right-click Certificate Templates.
Click New, select Certificate Template to Issue, then select RemoteDesktopAccess.
Click OK.
To update the Teleport group policy object to use the new certificate template:
Open the Teleport Access Policy group policy object in the group policy editor.
Expand Computer Configuration > Policies > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Security.
Right-click Server authentication certificate template, select Edit, select Enabled, then set the Certificate Template Name to RemoteDesktopAccess.
Expand Computer Configuration, Policies, and Windows Settings to select Public Key Policies.
Double-click Certificate Services Client - Auto-Enrollment, then select Enabled in the Configuration Model.
Open PowerShell and run the following command to update your Teleport group policy object:
gpupdate.exe /force
Teleport connects to your domain controller using LDAPS. This means that you must let Teleport know that the certificate sent by your domain controller during the initial 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. However, you shouldn't
skip TLS verification in production environments.
To export a CA certificate:
ldap_ca_cert configuration field.To configure Teleport to protect access to Windows desktops:
Install Teleport on the Linux host that will run the Teleport Windows Desktop Service:
(!docs/pages/includes/install-linux.mdx!)
Sign in to your Teleport cluster from your administrative workstation.
Generate an invitation token for the cluster with the following command:
$ tctl tokens add --type=windowsdesktop
Copy the invitation token to a file on the Linux host that will run the Windows Desktop Service.
Add the configuration for the Windows Desktop Service to the /etc/teleport.yaml
on the Linux host.
The /etc/teleport.yaml should include configuration settings similar to the following:
version: v3
teleport:
auth_token: "path/to/token"
proxy_server: <Var name="teleport.example.com"/> # replace with your proxy address
windows_desktop_service:
enabled: true
ldap:
# Address (including port) of an LDAP server.
# Can be omitted if `locate_server` is enabled.
# LDAPS port is 636 by default (example.com:636)
addr: "$LDAP_SERVER_ADDRESS"
domain: "$LDAP_DOMAIN_NAME"
username: "$LDAP_USERNAME"
sid: "$LDAP_USER_SID"
# Contents of the LDAP server certificate you exported.
ldap_ca_cert: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
discovery_configs:
- base_dn: "*"
auth_service:
enabled: false
proxy_service:
enabled: false
ssh_service:
enabled: false
For a detailed description of the configuration fields, see Desktop Configuration Reference.
Configure LDAP server selection.
To find desktops to connect to in Active Directory, Teleport must be given the
address of an LDAP server. There are two ways to specify the LDAP server, either
by providing a single LDAP server address in the addr field, or by enabling
locate_server to automatically discover the LDAP server from DNS SRV records.
If you opt to use addr, for the best results, the address should point to a
highly-available endpoint to avoid downtime. The port for LDAPS should also be
included, which is typically 636.
Alternatively, you can enable locate_server to automatically discover an
LDAP server from the DNS SRV records of your specified domain. This is useful
if you have multiple LDAP servers for high availability and load balancing.
Optionally, you can specify a site to limit the discovery to a specific
Active Directory site.
(!docs/pages/includes/start-teleport.mdx service="the Teleport Desktop Service"!)
Teleport users must have appropriate permissions to access remote Windows desktops. For example, you can create a role that gives its users access to all Windows desktop labels and the local "Administrator" user.
To create a role for accessing Windows desktops:
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
(!docs/pages/includes/add-role-to-user.mdx role="windows-desktop-admins"!)
Now that you have a Linux host running the Windows Desktop Service and
a role that allows Teleport users to connect to Windows computers, you can
use the Teleport user assigned the windows-desktop-admins role
to connect to Windows desktops from the Teleport Web UI.
Alternatively, you can connect using Teleport Connect.
To connect to a Windows desktop:
Sign in to the Teleport cluster using an account that's assigned the
windows-desktop-admins role.
Select Resources.
Click Type, then select Desktops.
Click Connect for the Windows computer you want to access, then select the login to use for the connection.
Teleport opens a remote desktop connection and starts recording the desktop session. When you're finished working with the Windows desktop, click the More items menu, then click Disconnect.
To view the recording, select Audit in the Teleport Web UI, then click Session Recordings in the menu.
In Active Directory environments, Teleport can be configured to discover hosts
via LDAP. LDAP discovery is enabled by adding one or more discovery configs to
the discovery_configs field in the Teleport Windows Desktop Service
configuration. You can set base_dn to a wildcard '*' to search from the root
of the domain, or you can specify an alternate base distinguished name to search
from.
By default, all hosts discovered via LDAP will be registered with a port of 3389. You can override the RDP port for each discovery configuration.
windows_desktop_service:
enabled: true
discovery_configs:
- base_dn: 'OU=prod,DC=example,DC=com'
- base_dn: 'OU=staging,DC=example,DC=com'
rdp_port: 9989
Teleport optionally accepts a set of filters that can be used to narrow the search results for discovery. The filters are specified with LDAP Filter syntax. Teleport will automatically compute a logical AND of all filters specified.
windows_desktop_service:
enabled: true
discovery_configs:
- base_dn: '*'
filters:
- '(location=Oakland)'
- '(!(primaryGroupID=516))'
It is often necessary to apply labels to discovered hosts to control access. You
can configure Teleport to convert LDAP attributes to Teleport labels by setting
the label_attributes field in the discovery configuration.
windows_desktop_service:
enabled: true
discovery_configs:
- base_dn: '*'
label_attributes:
- 'location'
- 'department'
Each of the specified attributes will be placed in a Teleport label prefixed with ldap/.
For example, if an AD computer object had a location attribute with a value of Oakland,
and a department attribute with a value of Engineering, the Teleport resource for this
host would have both ldap/location=Oakland and ldap/department=Engineering labels.
In addition, you can also specify a set of static labels that apply to all hosts discovered via this policy:
windows_desktop_service:
enabled: true
discovery_configs:
- base_dn: 'OU=Engineering,OU=Servers,DC=example,DC=com'
labels:
team: engineering
- base_dn: 'OU=Sales,OU=Servers,DC=example,DC=com'
labels:
team: sales
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 you only grant this right to administrators or other privileged groups.
To change the default domain policy:
Each windows_desktop_service is designed to support connecting to hosts in a
single Active Directory domain. If you have multiple independent domains, you
can deploy multiple Teleport Agents to service them.
If you have multiple domains with a trust relationship between them, you can configure Teleport to perform PKI operations against one domain, while generating certificates for users in another domain.
In order for this to work, the hosts that you want to connect to and the AD users that you want to connect as must reside in the same domain.
For example, suppose you have a root domain at example.com and a child domain
for developers at dev.example.com. If your PKI is configured at the root, but
you want to allow users in the child domain to connect to hosts in the child
domain, you would do the following:
windows_desktop_service:
enabled: true
# configure LDAP settings to point at the child domain
ldap:
addr: dev.example.com:636
username: 'DEV\svc-teleport'
# optional: configure discovery for the child domain
discovery:
base_dn: CN=Computers,DC=dev,DC=example,DC=com
# perform PKI against the root domain
pki_domain: root.example.com
With this configuration, Teleport will generate certificates for users in
dev.example.com, but it will publish its CA and CRLs to example.com.
With Teleport 16.2.0 and later, you can configure windows_desktop_service to
perform Network Level Authentication (NLA) when connecting to Windows hosts. NLA
is a security feature that authenticates the user prior to establishing the
remote desktop connection, which ensures that the remote Windows host doesn't
consume system resources to present a login screen to an unauthenticated user.
In order to perform NLA, Teleport's windows_desktop_service needs to be able
to make an outbound Kerberos connection to a key distribution center (KDC). This
is most commonly performed on TCP port 88.
Teleport determines the address of the KDC by checking the following (in order of priority):
kdc_address is set, Teleport will use this address.locate_server is enabled and kdc_address is not set, Teleport will
attempt to discover the KDC address via DNS SRV records.locate_server or kdc_address is specified, Teleport will
assume that a KDC is available on the same host that is specified in the
ldap configuration's addr field.For example, you can set the KDC address by specifying the kdc_address
in your Teleport configuration file.
windows_desktop_service:
enabled: true
kdc_address: kdc.example.com # defaults to port 88 if unspecified
If you're using the locate_server option, Teleport will perform a DNS
SRV lookup on the provided domain (e.g. _kerberos._tcp.my-site._sites.example.com).
NLA will be performed against the highest-priority and reachable KDC.
windows_desktop_service:
enabled: true
locate_server:
enabled: true
site: "my-site" # optional
domain: example.com
If server location is disabled and kdc_address isn't specified, with the following configuration,
Teleport will attempt to perform NLA against example.com:88.
windows_desktop_service:
enabled: true
ldap:
addr: example.com:636
To enable NLA, set the TELEPORT_ENABLE_RDP_NLA environment variable to yes
on any hosts running the Teleport's windows_desktop_service. The process for
setting an environment variable varies depending on the environment in which you
are running Teleport.
If you're running Teleport in Kubernetes, you'll need to edit the Pod configuration.
If you're running Teleport as a systemd service, then you'll want to create a
systemd override using systemctl edit teleport:
$ sudo systemctl edit teleport
This will open a text editor where you can insert an override for the environment:
### Editing /etc/systemd/system/teleport.service.d/override.conf
### Anything between here and the comment below will become the contents of the drop-in file
[Service]
Environment="TELEPORT_ENABLE_RDP_NLA=yes"
Note that NLA is only supported when connecting to hosts that are part of an Active Directory domain. Teleport will not perform NLA when connecting to hosts as a local Windows user.
NLA is not supported when Teleport runs in FIPS mode.
In order to complete a successful authentication flow, Teleport needs to know
the hostname of the target Windows server. If you are using Teleport's
LDAP-based discovery no action is necessary - Teleport will default to using the
teleport.dev/computer_name label which is automatically populated. If this
label is not present then Teleport will use the desktop's addr field.
If you register your Windows hosts via configuration file or via Teleport's API and you want to enable NLA, then you should either:
teleport.dev/computer_name label to the proper hostnameaddr is its actual hostnameIf you encounter any issues, see Troubleshooting for common problems and solutions. For information about configuring Windows-specific role permissions, see Role-Based Access Control for Desktops.