Teleport 15 Unveiled: Elevating Access and Security Across Infrastructure
Feb 21
Virtual
Register Today
Teleport logoTry For Free
Fork me on GitHub

Teleport

Configure access for local Windows users

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise
Getting Started With Teleport Windows Access

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. For details on how to set this up, see the Getting Started guide.

  • The tctl admin tool and tsh client tool version >= 15.0.2.

    See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 14.3.4.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.4 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.4 go1.21

Proxy version: 14.3.4Proxy: teleport.example.com
  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 15.0.2.

    You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v15.0.2 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v15.0.2 go1.21

Proxy version: 15.0.2Proxy: teleport.example.com
  • A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.

  • The Enterprise tctl admin tool and tsh client tool version >= 14.3.4.

    You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v14.3.4 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v14.3.4 go1.21

Proxy version: 14.3.4Proxy: teleport.example.com
  • 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 protected]
    tctl status

    Cluster teleport.example.com

    Version 15.0.2

    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.
  1. Export the Teleport user certificate authority by running the following command using your Teleport cluster address:

    curl -o teleport.cer https://teleport.example.com/webapi/auth/export?type=windows
  1. Download the Teleport Windows Auth setup program:
curl -o teleport-windows-auth-setup-v15.0.2-amd64.exe https://cdn.teleport.dev/teleport-windows-auth-setup-v15.0.2-amd64.exe
  1. Download the Teleport Windows Auth setup program:
curl -o teleport-windows-auth-setup-v14.3.4-amd64.exe https://cdn.teleport.dev/teleport-windows-auth-setup-v14.3.4-amd64.exe
  1. 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.
  1. 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:

  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: var7510aeed20e5491baa2d258dc44acede
      proxy_server: varf5b924b630904a7291b5de23254e07c7
      auth_token: var256d9e8eaeeb4e5799dde51865751869
    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.

    On the host where you will run the Teleport Windows Desktop Service, enable and start Teleport:

    sudo systemctl enable teleport
    sudo systemctl start teleport

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

  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:

    1. Retrieve your local user's configuration resource:

      tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
    2. Edit out.yaml, adding windows-desktop-admins to the list of existing roles:

        roles:
         - access
         - auditor
         - editor
      +  - windows-desktop-admins 
      
    3. Apply your changes:

      tctl create -f out.yaml
    4. Sign out of the Teleport cluster and sign in again to assume the new role.

    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.

    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.

    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.

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.