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.

Prerequisites

To complete the steps in this guide, verify your environment meets the following requirements:

• A running Teleport cluster version 15.4.22 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 and tsh client tool.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• 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. tctl is supported on macOS and Linux machines. For example:

  $ tsh login --proxy=teleport.example.com --user=email@example.com
  $ tctl status
  # Cluster  teleport.example.com
  # Version  15.4.22
  # 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 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

3. Download the Teleport Windows Auth setup program:

$ curl.exe -fo teleport-windows-auth-setup-v15.4.22-amd64.exe https://cdn.teleport.dev/teleport-windows-auth-setup-v15.4.22-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.

   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.

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-v15.4.22-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 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: 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.

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: 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.

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.

3. Apply the new role to your cluster by running the following command:

   $ tctl create -f windows-desktop-admins.yaml

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. Retrieve your github authentication connector:

      $ tctl get github/github --with-secrets > github.yaml

      Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.

   2. Edit github.yaml, 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:

      $ tctl create -f github.yaml

   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.

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.

   

   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.