![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Configure access for local Windows users
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
![Getting Started With Teleport Windows Access](/docs/_next/image/?url=https%3A%2F%2Fi.ytimg.com%2Fvi%2F9DyKQbg4ORc%2Fdefault.jpg&w=256&q=75)
Getting Started With Teleport Windows Access
Length: 08:57
This guide demonstrates how to configure Teleport to provide secure, passwordless access to Microsoft Windows desktops for local Windows users.
Passwordless access for local users is limited to 5 desktops in Teleport Community Edition.
If you have more than 5 desktops registered under static_hosts
with ad: false
, Teleport
Community Edition will not allow connections to any of them.
Teleport Enterprise users can have unlimited number of desktops.
Prerequisites
To complete the steps in this guide, verify your environment meets the following requirements:
-
A running Teleport cluster version 16.2.1 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctl
admin tool andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- A Linux server to run the Teleport Windows Desktop Service. You can reuse an existing server running any other Teleport instance. However, you must generate a new invitation token to add the Windows Desktop Service to an existing Teleport instance.
- A physical or virtual machine running Microsoft Windows with Remote Desktop enabled and the RDP port (typically port 3389) open for inbound connections from the Linux server.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/4. Prepare Windows
Before you can enroll a Microsoft Windows desktop as a resource to be protected by Teleport, you need to prepare the Microsoft Windows environment with a certificate from the Teleport certificate authority (CA) and modify the default authentication service for remote desktop access.
To prepare a Windows computer:
- Open a Command Prompt (
cmd.exe
) window on the Windows computer you want to enroll.
-
Export the Teleport user certificate authority by running the following command using your Teleport cluster address:
curl.exe -fo teleport.cer https://teleport.example.com/webapi/auth/export?type=windows
- Download the Teleport Windows Auth setup program:
curl.exe -fo teleport-windows-auth-setup-v16.2.1-amd64.exe https://cdn.teleport.dev/teleport-windows-auth-setup-v16.2.1-amd64.exe
- Download the Teleport Windows Auth setup program:
curl.exe -fo teleport-windows-auth-setup-v16.1.7-amd64.exe https://cdn.teleport.dev/teleport-windows-auth-setup-v16.1.7-amd64.exe
-
Double-click the executable you downloaded to run the Teleport Windows Auth Setup program interactively and select the Teleport certificate that you exported when prompted.
The setup program:
- Enables Windows to trust the Teleport certificate authority.
- Installs the required dynamic link library (DLL) for Teleport to use.
- Disables Network Level Authentication (NLA) for remote desktop services.
- Enables RemoteFX compression, if using Teleport version 15 or newer.
- Restart the computer.
If you want to automate the installation process, you can run the setup program from an administrative Command Prompt or PowerShell console with the following command:
teleport-windows-auth-setup.exe install --cert=teleport.cer -r
Step 2/4. Configure the Windows Desktop Service
Now that you have prepared the Windows computer to enroll in the cluster, the next steps involve:
- Generating an invitation token on your administrative workstation.
- Configuring a Linux server to run the Windows Desktop Service.
To configure the Windows Desktop Service:
-
Sign in to the Teleport cluster from your administrative workstation to authenticate your identity.
-
Generate a short-lived invitation token by running the following command:
tctl tokens add --type=windowsdesktopThe command displays information similar to the following:
The invite token: abcd123-insecure-do-not-use-this This token will expire in 60 minutes.
-
Copy the token from your administrative workstation and paste it into a file on the Linux server where you want to run the Windows Desktop Service.
For example, create a file named
/tmp/token
on the Linux server and paste the token into the file. -
Check whether Teleport is installed on the Linux server where you want to run the Windows Desktop Service by running the following command:
teleport versionIf Teleport isn't installed on the Linux server, follow the appropriate Installation instructions for your environment.
-
Configure the
/etc/teleport.yaml
file on the Linux server with settings similar to the following for the Windows Desktop Service:version: v3 teleport: nodename: windows.teleport.example.com proxy_server: teleport.example.com:443 auth_token: /tmp/token windows_desktop_service: enabled: yes static_hosts: - name: host1 ad: false addr: 192.0.2.156 auth_service: enabled: no proxy_service: enabled: no ssh_service: enabled: no
In this file:
- Set the
proxy_server
to the address of your Teleport cluster. - List the Windows desktops under
static_hosts
.
Teleport can't automatically discover Windows desktops without Active Directory. Therefore, you must specify the Windows IP addresses or host names that you want to enroll using the Teleport configuration file or use the Teleport API to build your own integration.
You can find an example of API integration on GitHub.
- Set the
-
(Optional) Add labels for the Windows Desktop Service to the configuration file.
You can add labels to Windows computers using the
labels
section of the host config. For example, the following adds thedatacenter: dc1
label:version: v3 teleport: nodename: windows.teleport.example.com proxy_server: teleport.example.com:443 auth_token: /tmp/token windows_desktop_service: enabled: yes static_hosts: - name: host1 ad: false addr: 192.0.2.156 + labels: + datacenter: dc1
Alternatively, you can attach labels to Windows computers by matching to their hostnames. For example, the following adds the
cloud: ec2
label to computers that have host names ending with.us-east-2.compute.internal
:version: v3 teleport: nodename: windows.teleport.example.com proxy_server: teleport-proxy.example.com:443 windows_desktop_service: enabled: yes static_hosts: - name: host1 ad: false - addr: 192.0.2.156 + addr: ip-192-0-2-156.us-east-2.compute.internal + host_labels: + - match: '.*\.us-east-2.compute.internal' + labels: + cloud: ec2
For more information about using labels and roles, see Configure Windows-specific role permissions.
-
Configure the Teleport Windows Desktop Service to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed the Teleport Windows Desktop Service.
On the host where you will run the Teleport Windows Desktop Service, enable and start Teleport:
sudo systemctl enable teleportsudo systemctl start teleportOn the host where you will run the Teleport Windows Desktop Service, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo systemctl start teleportYou can check the status of the Teleport Windows Desktop Service with
systemctl status teleport
and view its logs withjournalctl -fu teleport
.
Step 3/4. Configure remote Windows desktop access
To access a remote desktop, a Teleport user must have a role with the appropriate permissions for that desktop.
To configure a role for desktop access:
-
Sign in to the Teleport cluster from your administrative workstation to authenticate your identity.
-
Create a
windows-desktop-admins.yaml
file to define a new role:kind: role version: v6 metadata: name: windows-desktop-admins spec: allow: windows_desktop_labels: "*": "*" windows_desktop_logins: ["Administrator", "alice"]
In this file:
- Set
windows_desktop_labels
to specify any labels you want to use to allow or deny access to specific hosts. - Set
windows_desktop_logins
to specify the Windows logins that Teleport users assigned to the role can use to access Windows desktops.
Depending on how you configure role-based access controls for Windows, Teleport can create local user logins automatically from the
windows_desktop_logins
you specify. For more information about enabling Teleport to create local Windows logins, see Logins. - Set
-
Apply the new role to your cluster by running the following command:
tctl create -f windows-desktop-admins.yaml -
Assign the
windows-desktop-admins
role to your Teleport user by running the appropriate commands for your authentication provider:-
Retrieve your local user's roles as a comma-separated list:
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') -
Edit your local user to add the new role:
tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},windows-desktop-admins" -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
github
authentication connector:tctl get github/github --with-secrets > github.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thegithub.yaml
file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource. -
Edit
github.yaml
, addingwindows-desktop-admins
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - windows-desktop-admins
-
Apply your changes:
tctl create -f github.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingwindows-desktop-admins
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
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 -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingwindows-desktop-admins
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - windows-desktop-admins
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Step 4/4. Connect
Now that you have configured a Linux server to run the Windows Desktop Service and
created a role to allow a Teleport user to connect to Microsoft Windows with a local
Windows login, you can use the Teleport user assigned the windows-desktop-admins
role
to connect to Windows desktops from the Teleport Web UI.
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 desktop you want to access, then select the Windows 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 Management in the Teleport Web UI, then click Session Recordings in the Activity section.
Uninstall
If you are using Teleport's Windows auth package to provide passwordless logins for local users, you can remove it by running the setup program from an administrative command prompt:
> teleport-windows-auth-setup.exe uninstall
A reboot is necessary after the uninstall completes in order to fully remove the package.
Next steps
For more general information about how to create, assign, and update roles, see Access Controls Getting Started. For more specific information about configuring Windows-specific role permissions, see Role-Based Access Control for Desktops.