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
# (optional) configure a set of label selectors for dynamic registration.
# If specified, this service will monitor the cluster for dynamic_windows_desktop
# and automatically proxy connections for desktops with matching labels.
resources:
- labels:
"env": "dev"
# (optional) 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