# Configure Access for Local Windows Users 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. ## How it works The Teleport Desktop Service proxies traffic between the Teleport Proxy Service and remote Windows desktops in your infrastructure. Teleport users connect to a Windows desktop using Teleport Connect or the Teleport Web UI. These graphical clients use the proprietary Teleport Desktop Protocol to send traffic to and receive traffic from the Teleport Desktop Service, which converts TDP messages to and from Remote Desktop Protocol messages. To access a remote desktop, a Teleport user must have a role with the appropriate permissions for that desktop. An administrator configures the desktop to trust the Teleport certificate authority, and the Windows Desktop Service uses certificate-based authentication to access the desktop. ## Prerequisites To complete the steps in this guide, verify your environment meets the following requirements: - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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 run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` 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: 1. Open a Command Prompt (`cmd.exe`) window on the Windows computer you want to enroll. 2) Export the Teleport certificate authority by running the following command, assigning teleport.example.com to your Teleport cluster address: ``` $ curl.exe -fo teleport.cer https://teleport.example.com/webapi/auth/export?type=windows ``` If your Teleport cluster uses HSM or AWS KMS-backed keys, there will be multiple CA certificates (one for each Auth Service instance). You can download a bundle containing all certificates by appending `&format=zip` to the URL. --- WINDOWS CA Teleport v18.7.0 introduced the Windows CA for issuance of Windows Desktop Access certificates. Prior to that the user CA was used. Clusters updated to v18.7.0 (or newer) automatically clone the user CA to the Windows CA, so existing trust relationships hold true until the Windows CA is rotated. --- 3) Download the Teleport Windows Auth setup program: ``` $ curl.exe -fo teleport-windows-auth-setup-v19.0.0-dev-amd64.exe https://cdn.teleport.dev/teleport-windows-auth-setup-v19.0.0-dev-amd64.exe ``` 4. 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. If you are using Teleport's support for HSM-backed keys and you downloaded a zip file in step 2, then you should extract the zip file and repeat the process below for each CA certificate. You can defer the reboot until you have installed all of the certificates. 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. In versions below Teleport 17.4.0, the Windows auth package for local users is "greedy" and attempts to process all smart card logins. This prevents smart card logins from outside of Teleport from working, and also makes it impossible to use Teleport to connect as Active Directory users. This is no longer the case with Teleport 17.4.0 and up. To connect as local users and Active Directory users on the same host, you need to register the host twice with Teleport, once with `ad: true` and once with `ad: false`. Note: in order for the Windows Local Security Authority (LSA) to load the Teleport DLL, [LSA protection](https://learn.microsoft.com/en-us/windows-server/security/credentials-protection-and-management/configuring-additional-lsa-protection) must be disabled. 5. 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-v19.0.0-dev-amd64.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: 1. Sign in to the Teleport cluster from your administrative workstation to authenticate your identity. 2. Generate a short-lived invitation token by running the following command: ``` $ tctl tokens add --type=windowsdesktop ``` The command displays information similar to the following: ``` The invite token: abcd123-insecure-do-not-use-this This token will expire in 60 minutes. ``` 3. 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. 4. Check whether Teleport is installed on the Linux server where you want to run the Windows Desktop Service by running the following command: ``` $ teleport version ``` If Teleport isn't installed on the Linux server, follow the appropriate [Installation instructions](https://goteleport.com/docs/installation/linux.md) for your environment. 5. 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: true static_hosts: - name: host1 ad: false addr: 192.0.2.156 auth_service: enabled: false proxy_service: enabled: false ssh_service: enabled: false ``` 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](https://github.com/gravitational/teleport/tree/master/examples/desktop-registration). 6. (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 the `datacenter: dc1` label: ``` version: v3 teleport: nodename: windows.teleport.example.com proxy_server: teleport.example.com:443 auth_token: /tmp/token windows_desktop_service: enabled: true 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: true 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](https://goteleport.com/docs/enroll-resources/desktop-access/rbac.md). 7. 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. **Package Manager** On the host where you will run the Teleport Windows Desktop Service, enable and start Teleport: ``` $ sudo systemctl enable teleport $ sudo systemctl start teleport ``` **TAR Archive** On 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.service $ sudo systemctl enable teleport $ sudo systemctl start teleport ``` You can check the status of the Teleport Windows Desktop Service with `systemctl status teleport` and view its logs with `journalctl -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: 1. Sign in to the Teleport cluster from your administrative workstation to authenticate your identity. 2. 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 [Automatic User Creation](https://goteleport.com/docs/enroll-resources/desktop-access/reference/user-creation.md). 3. Apply the new role to your cluster by running the following command: ``` $ tctl create -f windows-desktop-admins.yaml ``` --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- 4. Assign the `windows-desktop-admins` role to your Teleport user by running the appropriate commands for your authentication provider: **Local User** 1. Retrieve your local user's roles as a comma-separated list: ``` $ ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') ``` 2. 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" ``` 3. Sign out of the Teleport cluster and sign in again to assume the new role. **GitHub** 1. Open your `github` authentication connector in a text editor: ``` $ tctl edit github/github ``` 2. Edit the `github` connector, adding `windows-desktop-admins` to the `teams_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 ``` 3. Apply your changes by saving and closing the file in your editor. 4. Sign out of the Teleport cluster and sign in again to assume the new role. **SAML** 1. Retrieve your `saml` configuration resource: ``` $ tctl get --with-secrets saml/mysaml > saml.yaml ``` Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` to the `saml.yaml` file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. 2. Edit `saml.yaml`, adding `windows-desktop-admins` to the `attributes_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 ``` 3. Apply your changes: ``` $ tctl create -f saml.yaml ``` 4. Sign out of the Teleport cluster and sign in again to assume the new role. **OIDC** 1. Retrieve your `oidc` configuration resource: ``` $ tctl get oidc/myoidc --with-secrets > oidc.yaml ``` Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` to the `oidc.yaml` file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. 2. Edit `oidc.yaml`, adding `windows-desktop-admins` to the `claims_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 ``` 3. Apply your changes: ``` $ tctl create -f oidc.yaml ``` 4. 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. Alternatively, you can connect using Teleport Connect. To connect to a Windows desktop: 1. Sign in to the Teleport cluster using an account that's assigned the `windows-desktop-admins` role. 2. Select **Resources**. 3. Click **Type**, then select **Desktops**. 4. Click **Connect** for the Windows desktop you want to access, then select the Windows login to use for the connection. ![Connect to a Windows desktop from the Teleport Web UI](/docs/assets/images/passwordless-desktop-fcf0c2e08f4a797aae10ec198f929be5.png) 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**. ![Disconnect from a Windows desktop ](/docs/assets/images/desktop-disconnect-51d31c4cecbb254df0d89a13f6d7f016.png) To view the recording, select **Audit** in the Teleport Web UI, then click **Session Recordings** in the menu. ## 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](https://goteleport.com/docs/zero-trust-access/rbac-get-started/role-demo.md). For more specific information about configuring Windows-specific role permissions, see [Role-Based Access Control for Desktops](https://goteleport.com/docs/enroll-resources/desktop-access/rbac.md).