

Getting Started With Teleport Windows Access
Length: 08:57
This guide will help you configure Teleport to provide secure, passwordless access to Windows desktops. This configuration does not require an Active Directory domain.
Passwordless access for local users is an Enterprise-only feature.
For open source Teleport, consider integrating Teleport with Active Directory for automatic discovery by reading Desktop Access with Active Directory.
Teleport Enterprise users can also mix the Teleport Active Directory integration with the static host definitions described below.
Passwordless access for local users is available starting from Teleport v12
.
Previous versions of Teleport can implement Windows Access by integrating with
an Active Directory domain.
Prerequisites
-
A running Teleport Enterprise cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
- A Linux server to run the Teleport Desktop Access service on. You can reuse an existing server running any other Teleport instance.
- A server or virtual machine running a Windows operating system with Remote Desktop enabled and the RDP port available to the Linux server.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster 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.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster 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/4. Prepare Windows
In this section we'll import the Teleport certificate authority (CA) file to your Windows system, and prepare it for passwordless access through Teleport.
Import the Teleport root certificate
Use tctl
to export the Teleport user certificate authority:
tctl auth export --type=windows > teleport.cer
Copy this certificate to your Windows system, if you didn't run tctl
from there.
Install the Teleport service for Windows
From the Windows system, download the Teleport Windows Auth
Setup.
Extract the .exe
file from the archive and run it. When prompted, select the
Teleport certificate file from the previous step. Once complete, reboot the system.
The Teleport Windows Auth Setup can be run in a shell environment with elevated privileges. You can use this to automate installation, uninstallation, and certificate updates. The following command will install the Teleport Certificate, load the required DLL, disable NLA, and reboot the Windows machine:
teleport-windows-auth-setup.exe install --cert=teleport.cer -rTeleport Authentication Package installed
Use the --help
flag to learn more.
Step 2/4. Install the Teleport Desktop Service
On your local system, authenticated to your Teleport cluster, generate a short-lived join token:
tctl tokens add --type=windowsdesktopThe invite token: abcd123-insecure-do-not-use-this
This token will expire in 60 minutes.
This token enables Desktop Access. See https://goteleport.com/docs/desktop-access/
for detailed information on configuring Teleport Desktop Access with this token.
Copy the token to the Linux host where you will run the Desktop service as /tmp/token
.
Use the appropriate commands for your environment to install your package.
Teleport Edition
Add the Teleport repository to your repository list:
Download Teleport's PGP public key
sudo curl https://apt.releases.teleport.dev/gpg \-o /usr/share/keyrings/teleport-archive-keyring.ascSource variables about OS version
source /etc/os-releaseAdd 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/nullsudo apt-get updatesudo apt-get install teleport
Source variables about OS version
source /etc/os-releaseAdd 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 teleportTip: 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
In the example commands below, update $SYSTEM-ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
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.gzshasum -a 256 teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleportsudo ./install
In the example commands below, update $SYSTEM-ARCH
with the appropriate
value (amd64
, arm64
, or arm
). All example commands using this variable
will update after one is filled out.
After Downloading the .deb
file for your system architecture, install it with
dpkg
. The example below assumes the root
user:
dpkg -i ~/Downloads/teleport-ent_12.1.1_$SYSTEM-ARCH.debSelecting 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 ...
After Downloading the .rpm
file for your system architecture, install it with rpm
:
rpm -i ~/Downloads/teleport-ent-12.1.1.$SYSTEM-ARCH.rpmwarning: 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.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-bin.tar.gzcd teleport-entsudo ./install
For FedRAMP/FIPS-compliant installations of Teleport Enterprise, package URLs will be slightly different:
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.gzshasum -a 256 teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzVerify that the checksums match
tar -xvf teleport-ent-v12.1.1-linux-$SYSTEM-ARCH-fips-bin.tar.gzcd teleport-entsudo ./install
Please use the latest version of Teleport Enterprise documentation.
Create /etc/teleport.yaml
and configure it for Desktop Access. Update the proxy_server
value to your Teleport proxy service or cloud tenant, and put the Windows machine address
under non_ad_hosts
:
version: v3
teleport:
nodename: windows.teleport.example.com
proxy_server: teleport-proxy.example.com:443
auth_token: /tmp/token
windows_desktop_service:
enabled: yes
non_ad_hosts:
- 192.0.2.156
auth_service:
enabled: no
proxy_service:
enabled: no
ssh_service:
enabled: no
Note that without Active Directory, Teleport cannot automatically discover your Desktops. Instead you must define the Windows systems configured for access through Teleport in your config file, or use Teleport's API to build your own integration. An example API integration is available on GitHub.
You can attach labels to your Windows hosts by matching to their hostnames.
For example, to add the cloud: ec2
label to hosts with EC2 private IP DNS names:
version: v3
teleport:
nodename: windows.teleport.example.com
proxy_server: teleport-proxy.example.com:443
windows_desktop_service:
enabled: yes
non_ad_hosts:
- - 192.0.2.156
+ - ip-192-0-2-156.us-east-2.compute.internal
+ host_labels:
+ - match: '.*\.us-east-2.compute.internal'
+ labels:
+ cloud: ec2
auth_service:
enabled: no
proxy_service:
enabled: no
ssh_service:
enabled: no
Start or restart the Teleport Service. For new Teleport nodes, the examples below depend on how you installed Teleport (from a system package or a TAR archive):
sudo systemctl start teleport.service
sudo teleport install systemd --output=/etc/systemd/system/teleport.service;sudo systemctl enable teleport;sudo systemctl start teleport;
Step 3/4. Configure Windows access
In order to gain access to a remote desktop, a Teleport user needs to have the appropriate permissions for that desktop.
Create the file windows-desktop-admins.yaml
:
kind: role
version: v6
metadata:
name: windows-desktop-admins
spec:
allow:
windows_desktop_labels:
"*": "*"
windows_desktop_logins: ["Administrator", "alice"]
You can restrict access to specific hosts by defining values for
windows_desktop_labels
, and adjust the array of usernames this role has access
to in windows_desktop_logins
.
Ensure that each Teleport user is only assigned Windows logins that they should be allowed to access.
Apply the new role to your cluster:
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:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding windows-desktop-admins
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - windows-desktop-admins
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding windows-desktop-admins
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - windows-desktop-admins
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding windows-desktop-admins
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - windows-desktop-admins
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding windows-desktop-admins
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - windows-desktop-admins
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
Step 4/4. Connect
You can now connect to your Windows desktops from the Teleport Web UI:

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