Fork me on GitHub

Desktop Access reference


Desktop Access is currently in Preview. Do not use this feature for any critical infrastructure and keep a backup option for accessing your desktop hosts.

Configuration and CLI reference


teleport.yaml fields related to Desktop Access:

# Main service responsible for Desktop Access.
# You can have multiple Desktop Access services in your cluster (but not in the
# same teleport.yaml), connected to the same or different Active Directory
# domains.
  enabled: yes
  # This is the address that windows_desktop_service will listen on.
  listen_addr: "localhost:3028"
  # (optional) This is the address that windows_desktop_service will advertise
  # to the rest of Teleport for incoming connections. Only proxy_service should
  # connect to windows_desktop_service, users connect to the proxy's web UI
  # instead.
  public_addr: ""
    # Address of the Domain Controller for LDAP connections. Usually, this
    # address will use port 389, like:
    addr:     '$LDAP_SERVER_ADDRESS'
    # Active Directory domain name you are connecting to.
    domain:   '$LDAP_DOMAIN_NAME'
    # LDAP username for authentication. This username must include the domain
    # NetBIOS name.
    # For example, if your domain is "", the NetBIOS name for it is
    # likely "EXAMPLE". When connecting as the "Administrator" user, you should
    # use the format: "EXAMPLE\Administrator".
    username: '$LDAP_USERNAME'
    # Plain text file containing the LDAP password for authentication.
    # This is usually the same password you use to login to the Domain Controller.
    password_file: /var/lib/ldap-pass
  # (optional) settings for enabling automatic desktop discovery via LDAP
    # The wildcard '*' character tells Teleport to discover all the hosts in
    # the Active Directory Domain. To refine the search, specify a custom DN.
    # To disable automatic discovery, leave this field blank.
    base_dn: '*'
    # (optional) LDAP filters for further customizing the LDAP search.
    # See for details on LDAP filter syntax.
    - '(location=Oakland)'
    - '(!(primaryGroupID=516))' # exclude domain controllers
  # Rules for applying labels to Windows hosts based on regular expressions
  # matched against the host name. If multiple rules match, the desktop will
  # get the union of all matching labels.
  - match: '^.*\.dev\.example\.com$'
      environment: dev
  - match: '^.*\.prod\.example\.com$'
      environment: prod

This host_labels configuration would apply the environment: dev label to a Windows desktop named, and the environment: prod label to a desktop named


Teleport's Role-based access control (RBAC) allows administrators to set up granular access policies for Windows desktops connected to Teleport.

Teleport's "role" resource provides the following instruments for controlling desktop access:

kind: role
version: v4
  name: developer
    # Label selectors for desktops this role has access to.
    # See above for how labels are applied to desktops.
      environment: ["dev", "stage"]

    # Windows user accounts this role can connect as.
    windows_desktop_logins: ["Administrator", "{{internal.windows_logins}}"]

It is possible to use wildcards ("*") to match all desktop labels.

Like with SSH access, the windows_desktop_logins field supports the special {{internal.windows_logins}} variable for local users which will map to any logins that are supplied when the user is created with tctl users add alice --windows-logins=Administrator,DBUser.

For new clusters, the "access" role will have windows_desktop_logins: ["{{internal.windows_logins}}"] set by default.


CLI commands related to Desktop Access.

Generate a join token for Desktop Access service:

$ tctl nodes add --roles=WindowsDesktop

List registered Desktop Access services:

$ tctl get windows_desktop_service

List registered Windows hosts in the domain:

$ tctl get windows_desktop
Have a suggestion or can’t find something?