desktop

README

Windows Desktop Access Beta

How to set up Desktop Access on Windows

Install Windows Server 2012

Download and instal a trial version of Windows Server 2012 R2 from: https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2012-r2

Windows Server 2012 is the oldest version we support.

See this appendix if using VirtualBox.

Set up Active Directory

AD DS

First, we need to install Active Directory Domain Services (AD DS). Save the following file as domain-controller.ps1, replacing $domain with your desired domain name.

$ErrorActionPreference = "Stop"

$domain = 'example.com'
$netbiosDomain = ($domain -split '\.')[0].ToUpperInvariant()

echo 'Installing the AD services and administration tools...'
Install-WindowsFeature AD-Domain-Services,RSAT-AD-AdminCenter,RSAT-ADDS-Tools

echo 'Installing AD DS (be patient, this may take a while to install)...'
Import-Module ADDSDeployment
Install-ADDSForest `
    -InstallDns `
    -CreateDnsDelegation:$false `
    -ForestMode 'Win2012R2' `
    -DomainMode 'Win2012R2' `
    -DomainName $domain `
    -DomainNetbiosName $netbiosDomain `
    -SafeModeAdministratorPassword (Read-Host "Enter Your Password" -AsSecureString) `
    -NoRebootOnCompletion `
    -Force

Restart-Computer -Force

AD CS

Next, we'll install Active Directory Certificate Services (AD CS) to enable TLS on LDAP connections. While AD CS is not strictly required, it is the easiest way to generate a keypair and ensure that the server supports LDAPS.

Save the following file as certificate-services.ps1

$ErrorActionPreference = "Stop"

Add-WindowsFeature Adcs-Cert-Authority -IncludeManagementTools
Install-AdcsCertificationAuthority -CAType EnterpriseRootCA -HashAlgorithmName SHA384 -Force
Restart-Computer -Force

Restart the VM after configuring AD CS.

Follow The Docs

Now follow the Getting Started documentation on the Teleport website to complete the installation.

Appendix: VirtualBox notes

Some advice to make the setup easier with VirtualBox.

First, install VirtualBox Guest Additions.

Next, create a shared folder via VM settings in VirtualBox. This will let you easily transfer files between host and VM.

Finally, switch the Network Adapter to Bridged Adapter mode. This lets you connect to the VM from your host. To get the VM IP, run ipconfig.exe from PowerShell.

Documentation

Overview

Package desktop implements Desktop Access services, like windows_desktop_access.

Index

• Constants
• Variables
• type HeartbeatConfig
  • func (cfg *HeartbeatConfig) CheckAndSetDefaults() error
• type WindowsService
  • func NewWindowsService(cfg WindowsServiceConfig) (*WindowsService, error)
  • func (s *WindowsService) Close() error
  • func (s *WindowsService) Serve(plainLis net.Listener) error
• type WindowsServiceConfig
  • func (cfg *WindowsServiceConfig) CheckAndSetDefaults() error

Constants

const (
	// SNISuffix is the server name suffix used during SNI to specify the
	// target desktop to connect to. The client (proxy_service) will use SNI
	// like "${UUID}.desktop.teleport.cluster.local" to pass the UUID of the
	// desktop.
	SNISuffix = ".desktop." + constants.APIDomain
	// WildcardServiceDNS is a wildcard DNS address to embed in the service TLS
	// certificate for SNI-based routing. Note: this is different from ALPN SNI
	// routing on the proxy.
	WildcardServiceDNS = "*" + SNISuffix
)

Variables

var ComputerAttributes = []string{
	windows.AttrName,
	windows.AttrCommonName,
	windows.AttrDistinguishedName,
	windows.AttrDNSHostName,
	windows.AttrObjectGUID,
	windows.AttrOS,
	windows.AttrOSVersion,
	windows.AttrPrimaryGroupID,
}

ComputerAttributes are the attributes we fetch when discovering Windows hosts via LDAP see: https://docs.microsoft.com/en-us/windows/win32/adschema/c-computer#windows-server-2012-attributes

Types

type HeartbeatConfig

type HeartbeatConfig struct {
	// HostUUID is the UUID of the host that this service runs on. Used as the
	// name of the created API object.
	HostUUID string
	// PublicAddr is the public address of this service.
	PublicAddr string
	// OnHeartbeat is called after each heartbeat attempt.
	OnHeartbeat func(error)
	// StaticHosts is an optional list of static Windows hosts to register
	StaticHosts []servicecfg.WindowsHost
}

HeartbeatConfig contains the configuration for service heartbeats.

func (*HeartbeatConfig) CheckAndSetDefaults

func (cfg *HeartbeatConfig) CheckAndSetDefaults() error

type WindowsService

type WindowsService struct {
	// contains filtered or unexported fields
}

WindowsService implements the RDP-based Windows desktop access service.

This service accepts mTLS connections from the proxy, establishes RDP connections to Windows hosts and translates RDP into Teleport's desktop protocol.

func NewWindowsService

func NewWindowsService(cfg WindowsServiceConfig) (*WindowsService, error)

NewWindowsService initializes a new WindowsService.

To start serving connections, call Serve. When done serving connections, call Close.

func (*WindowsService) Close

func (s *WindowsService) Close() error

Close instructs the server to stop accepting new connections and abort all established ones. Close does not wait for the connections to be finished.

func (*WindowsService) Serve

func (s *WindowsService) Serve(plainLis net.Listener) error

Serve starts serving TLS connections for plainLis. plainLis should be a TCP listener and Serve will handle TLS internally.

type WindowsServiceConfig

type WindowsServiceConfig struct {
	// Log is the logging sink for the service.
	Log logrus.FieldLogger
	// Clock provides current time.
	Clock   clockwork.Clock
	DataDir string
	// Authorizer is used to authorize requests.
	Authorizer authz.Authorizer
	// LockWatcher is used to monitor for new locks.
	LockWatcher *services.LockWatcher
	// Emitter emits audit log events.
	Emitter events.Emitter
	// TLS is the TLS server configuration.
	TLS *tls.Config
	// AccessPoint is the Auth API client (with caching).
	AccessPoint auth.WindowsDesktopAccessPoint
	// AuthClient is the Auth API client (without caching).
	AuthClient auth.ClientI
	// ConnLimiter limits the number of active connections per client IP.
	ConnLimiter *limiter.ConnectionsLimiter
	// Heartbeat contains configuration for service heartbeats.
	Heartbeat HeartbeatConfig
	// HostLabelsFn gets labels that should be applied to a Windows host.
	HostLabelsFn func(host string) map[string]string
	// ShowDesktopWallpaper determines whether desktop sessions will show a
	// user-selected wallpaper vs a system-default, single-color wallpaper.
	ShowDesktopWallpaper bool
	// LDAPConfig contains parameters for connecting to an LDAP server.
	// LDAP functionality is disabled if Addr is empty.
	windows.LDAPConfig
	// PKIDomain optionally configures a separate Active Directory domain
	// for PKI operations. If empty, the domain from the LDAP config 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.
	PKIDomain string
	// DiscoveryBaseDN is the base DN for searching for Windows Desktops.
	// Desktop discovery is disabled if this field is empty.
	DiscoveryBaseDN string
	// DiscoveryLDAPFilters are additional LDAP filters for searching for
	// Windows Desktops. If multiple filters are specified, they are ANDed
	// together into a single search.
	DiscoveryLDAPFilters []string
	// DiscoveryLDAPAttributeLabels are optional LDAP attributes to convert
	// into Teleport labels.
	DiscoveryLDAPAttributeLabels []string
	// Hostname of the windows desktop service
	Hostname string
	// ConnectedProxyGetter gets the proxies teleport is connected to.
	ConnectedProxyGetter *reversetunnel.ConnectedProxyGetter
	Labels               map[string]string
}

WindowsServiceConfig contains all necessary configuration values for a WindowsService.

func (*WindowsServiceConfig) CheckAndSetDefaults

func (cfg *WindowsServiceConfig) CheckAndSetDefaults() error