Desktop Access Configuration Reference

teleport.yaml fields related to desktop access:

# Main service responsible for desktop access.
#
# You can have multiple Desktop Service instances in your cluster (but not in the
# same teleport.yaml), connected to the same or different Active Directory
# domains.
windows_desktop_service:
  enabled: yes
  # This is the address that windows_desktop_service will listen on.
  listen_addr: "0.0.0.0: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: "desktop-access.example.com:3028"
  # (optional) Determines whether desktop sessions will show a user-selected wallpaper
  # vs a system-default, single-color wallpaper. For improved visual performance,
  # set this to false (its default value).
  show_desktop_wallpaper: false
  # (optional) ldap contains configuration keys used when connecting Teleport
  # to an Active Directory domain. This enables the discovery service for
  # Windows desktops belonging to an Active Directory domain configured for
  # Teleport access.
  ldap:
    # Address of the LDAP server for secure LDAP connections.
    # Usually, this address will use port 636, like: ldap.example.com:636.
    # For best results, this address should point to a highly-available
    # endpoint rather than a single domain controller.
    addr: '$LDAP_SERVER_ADDRESS'
    # Optional: the server name to use when validating the LDAP server's
    # certificate. Useful in cases where addr is an IP but the server
    # presents a cert with some other hostname.
    server_name: '$LDAP_SERVER_NAME'
    # 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
    # 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 "example.com", 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'

  # (optional) When AD support is used, this field allows you to override
  # the domain that Teleport uses for PKI operations. If empty, the domain
  # from the ldap section is used. This can be useful for cases where PKI
  # is configured in a root domain but Teleport is used to provide access
  # to users and computers in a child domain.
  pki_domain: root.example.com

  # (optional) hosts is a list of hostnames to register as WindowsDesktop
  # objects in Teleport. These hosts must be part of the Active Directory
  # domain configured to grant Teleport access.
  hosts:
  - win1.dev.example.com
  - win2.dev.example.com
  # (optional) non_ad_hosts is a list of hostnames that are not part of an
  # Active Diretory domain to register as WindowsDesktop objects in Teleport.
  # These hosts require the Teleport CA certificate and service, as described in
  # https://goteleport.com/docs/desktop-access/getting-started/
  non_ad_hosts:
  - win3.prod.example.com
  - win4.prod.example.com
  # (optional, available from 14.3) static_hosts is a list of hosts to register as WindowsDesktop
  # objects in Teleport. You can define host name and labels directly.
  static_hosts:
    - name: example1
      ad: false
      addr: win1.dev.example.com
      labels:
        datacenter: dc1
    - ad: true
      addr: win2.dev.example.com # name will be generated based on address
      labels:
        controller: all
  # (optional) settings for enabling automatic desktop discovery via LDAP
  discovery:
    # 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 https://ldap.com/ldap-filters for details on LDAP filter syntax.
    filters:
    - '(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.
    label_attributes:
    - 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.
  #
  # The rules for matching static hosts (static_hosts, hosts and non_ad_hosts) and discovered hosts
  # are slightly different. See https://goteleport.com/docs/desktop-access/rbac/
  # for details.
  host_labels:
  - match: '^.*\.dev\.example\.com'
    labels:
      environment: dev
  - match: '^.*\.prod\.example\.com'
    labels:
      environment: prod
  - match: '^EC2AMAZ-'
    labels:
      environment: discovered-in-aws

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

Deployment

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

• from the Teleport Proxy to the Windows Desktop Service.
• from the Windows Desktop Service to the Auth Service.

For these reasons direct mode is not available in Teleport cloud, only self-hosted Teleport clusters.

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.