Skip to main content
Version: 16.x

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) Configures the address of the Kerberos Key Distribution Center,
  # which is used to support RDP Network Level Authentication (NLA).
  # If empty, the LDAP address will be used instead.
  #
  # example: kdc.example.com:88.
  # The port is optional and defaults to port 88 if unspecified.
  #
  # Note: NLA is only supported in Active Directory environments - this field has
  # no effect when connecting to desktops as local Windows users.
  kdc_address: '$KDC_SERVER_ADDRESS'

  # (optional) 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.
  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.

Screen size​

By default, Teleport will set the screen size of the remote desktop session based on the size of your browser window. In some cases, you may wish to configure specific hosts to use a specific screen size. To do this, set the screen_size attribute on the windows_desktop resource:

kind: windows_desktop
metadata:
  name: fixed-screen-size
spec:
  host_id: 307e091b-7f6b-42e0-b78d-3362ad10b55d
  addr: 192.168.1.153:3389
  non_ad: true

  # Optional - ensures that all sessions use the same screen size,
  # no matter what the size of the browser window is.
  # Leave blank to use the size of the browser window.
  screen_size:
    width: 1024
    height: 768