Fork me on GitHub

Desktop Access Configuration Reference


Windows Desktop Service configuration

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 LDAP server for secure LDAP connections.
    # Usually, this address will use port 636, like:
    # For best results, this address should point to a highly-available
    # endpoint (a load balancer, VIP, or round-robin DNS) rather than
    # a single domain controller.
    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. The use of single quotes here is intentional in order to
    # avoid the need to escape the backslash (\) character.
    # For example, if your domain is "", the NetBIOS name for it is
    # likely "EXAMPLE". When connecting as the "svc-teleport" user, you should
    # use the format: "EXAMPLE\svc-teleport".
    username: '$LDAP_USERNAME'
    # You can skip LDAPS certificate verification by setting
    # this to true. It is recommended that this be set to false
    # and the certificate added your system's trusted repository,
    # or its filepath provided in with the der_ca_file variable below.
    insecure_skip_verify: false
    # DER encoded LDAP CA certificate.
    der_ca_file: /path/to/cert
  # (optional) hosts is a list of hostnames to register as WindowsDesktop
  # objects in Teleport.
  - ...
  # (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


The Windows Desktop Service can be deployed in two modes.

Direct mode

In direct mode, Windows Desktop Services registers directly with the Teleport Auth Server, and listens for desktop connections from the Teleport Proxy. To enable direct mode, set windows_desktop_service.listen_addr in teleport.yaml, and ensure that teleport.auth_servers points directly at the Auth Server. Direct mode requires network connectivity from the Teleport Proxy to Windows Desktop Service, and from Windows Desktop Service to the Auth Server.

IoT mode (reverse tunnel)

In IoT mode, Windows Desktop Service only needs to be able to make an outbound connection to a Teleport Proxy. The Windows Desktop Service establishes a reverse tunnel to the proxy, and both registration with the Auth Server and desktop sessions are performed over this tunnel. To enable this mode, ensure that windows_desktop_service.listen_addr is unset, and point teleport.auth_servers at a Teleport Proxy.