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'
    # The security identifier of the service account specified by the username
    # field above. This looks like a string starting with "S-".
    # Any AD user with permission to read user objects can obtain this value
    # by opening a PowerShell and running
    # ```
    # Get-AdUser -Identity $LDAP_USERNAME | Select SID
    # ```
    # The value can be obtained over LDAP by constructing a query with the
    # filter = (&(objectCategory=person)(objectClass=user)(sAMAccountName=$LDAP_USERNAME))
    # and requesting the attribute = objectSid
    sid: '$LDAP_USER_SID'
    # 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 provided as a PEM encoded certificate using ldap_ca_cert variable.
    # You can provide a filepath with der_ca_file, but this behavior is deprecated.
    insecure_skip_verify: false
    # PEM encoded LDAP CA certificate.
    ldap_ca_cert: |
      -----BEGIN CERTIFICATE-----
          *certificate data*
      -----END CERTIFICATE-----
    # DER encoded LDAP CA certificate.
    # deprecated: prefer ldap_ca_cert instead
    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
    # (optional) LDAP attributes to convert into Teleport labels.
    # The key of the label will be "ldap/" + the value of the attribute.
    - location
  # 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

  # Labels to attach to the Windows Desktop Service. This is used internally, so
  # any custom labels added won't affect the Windows hosts.
    teleport.internal/resource-id: "resource-id"


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_server 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.proxy_server at a Teleport Proxy.