Citrix Director 7.15 puppet & powershell DSC module

Introduction

Director provides advanced monitoring capabilities of a XenApp/XenDesktop deployment. This modules installs and configures a Citrix Director 7.x, links it to the XenApp/XenDesktop site Delivery Controllers, and enables Kerberos SSO access.

Director can be deployed reduncdantly with load-balancing capabilities in front of two Director nodes.

Xd7director Puppet Module

Integration data

Director runs with service account to improve security and allow the deployment of multiple Director instances (Director Pool) configured for Kerberos SSO login behind a load-balancer.
All the Director nodes in a Director Pool must have their Director IIS ApplicationPool be configured with the same service account and the same SPN.

The SSL certificate provided needs to be a password protected p12/pfx certificate including the private key. IIS HTTPS binding has to be activated manuelly with the SSL certificate deployed by puppet because of a compatibility issue between xWebsite DSC ressource and Storefront SDK powershell scripts.

The module can be installed on a Standard, Datacenter version of Windows 2012R2 or Windows 2016. **Core version is not supported by Citrix for delivery Controller installation**.

Warning : Delagation has to be manually configured in Active Directory on Director service account delegation tab to enable Kerberos SSO :

  • Check Trust this computer for delegation to any service (Kerberos only) to enable Kerberos SSO for domain users. Users need to be logged on a domain computer to be able to access Director.
  • Check Trust this computer for delegation to specified service only (Use any authentication protocol) if you want to configure alternate authentication method (smartcard for example) with Kerberos Constrainded Delegation in front of Director. In this scenario, Director has to be able to impersonate the user identity and to use this identity to authenticate on Delivery Controllers to grab the data whose the user is authorized to access.

Module usage

director_svc_username : (string format username) : Director service account (on which Director IIS ApplicationPool will run). Use **username** format. **DO NOT** use DOMAIN\username format.

director_svc_password : Password of the Director service account. Should be encrypted with hiera-eyaml.

setup_svc_username : (string) Privileged account used by Puppet for installing the software.

setup_svc_password : (string) Password of the privileged account. Should be encrypted with hiera-eyaml.

sourcePath : (string) Path of a folder containing the Xendesktop 7.x installer (unarchive the ISO image in this folder).

deliveryControllers : (String) List of Citrix Delivery Controllers of the XenDesktop7 site ‘srv-cxdc01.domain.net, srv-cxdc012.domain.net’

domainName : (string) Active Directory domain name (full)

domainNetbiosName : (string) : Active Directory domain NETBIOS name.

loadbalandedDirector : true or false. Is Director deployed behind a load-balancer ? Default : false

loadbalancedDirectorFqdn : (string)(optionnal) FQDN of the Director pool associated to the virtual server IP configured on the loadbalancer

https : (boolean) : true or false. Deploy SSL certificate on IIS and activate SSL access to Storefront ? Default : false

sslCertificateSourcePath : (string) Location of the SSL certificate (p12 / PFX format with private key). Can be local folder, UNC path, HTTP URL)

sslCertificatePassword : (string) Password protecting the p12/pfx SSL certificate file.

sslCertificateThumbprint : (string) Thumbprint of the SSL certificate (available in the SSL certificate).

caCertificateSourcePath : (string) Location of the SSL Certification Autority root certificate (PEM or CER format). Can be local folder, UNC path, HTTP URL)

caCertificateThumbprint : (string) Thumbprint of the SSL Certification Autority root certificate (available in the SSL certificate).

node 'director' {
	class{'xd7director':
	  director_svc_username => 'svc-director',
	  director_svc_password => 'P@ssw0rd',
	  setup_svc_username => 'TESTLAB\svc-puppet',
	  setup_svc_password => 'P@ssw0rd',
	  sourcepath => '\\fileserver\xendesktop715',
	  deliverycontrollers => 'srv-cxdc01.testlab.com, srv-cxdc02.testlab.com',
	  domainName => 'TESTLAB.COM',
	  domainNetbiosName=> 'TESTLAB',
	  loadbalandedDirector => true,
	  loadbalancedDirectorFqdn => 'director.testlab.com',
	  https => true,
	  sslCertificateSourcePath => '\\fileserver\ssl\cxdirector.pfx',
	  sslCertificatePassword => 'P@ssw0rd',
	  sslCertificateThumbprint => '44cce73845feef4da4d369a37386c862eb3bd4e1',
	  caCertificateSourcePath => '\\fileserver\ssl\ca-root.pem',
	  caCertificateThumbprint => '48jise7dssdsd4da4d369a3738dsdsdeeb3sdiu3'
	}
}

Xd7director module structure

init.pp : defines the structure of the module

The following options are available for a production-grade installation :

  • Security : IIS SSL configuration to secure communications between Director and the client device. The SSL certificate provided needs to be a password protected p12/pfx certificate including the private key.
  • Resiliency : Deployment of a Director pool in a load-balanced environment with SPN setup and Kerberos SSO capability.

class xd7director ( $director_svc_username, $director_svc_password, $setup_svc_username, $setup_svc_password, $sourcePath = ‘C:\\XD715’, $deliveryControllers = ‘srv-cxdc01, srv-cxdc02’, $domainName, $domainNetbiosName=‘TESTLAB’, $loadbalandedDirector = false, $loadbalancedDirectorFqdn = ‘’, $https = false, $sslCertificateSourcePath = ‘’, $sslCertificatePassword = ‘’, $sslCertificateThumbprint = ‘’, $caCertificateSourcePath = ‘’, $caCertificateThumbprint = '' ) { contain xd7director::install contain xd7director::serviceaccounts contain xd7director::config contain xd7director::sslconfig #Install Sirector & IIS before configuring the service account (IIS_IUSRS group needed in serviceaccounts.pp) Class['::xd7director::install'] -> Class['::xd7director::serviceaccounts'] -> Class['::xd7director::config'] -> Class['::xd7director::sslconfig'] reboot { ‘dsc_reboot’: when => pending, timeout => 15, } }

serviceaccounts.pp : service account creation and rights assignment

The submodule creates the Director service account needed to Director IIS ApplicationPool to run under a service account identity. Director http/ is associated to the service account.

Despite requiring additional configuration, this setup has several advantages in enterprise environment :

  • It enhances web server security. A problem arose over time in Windows systems as more and more services started to run by default as Network Service : running as Network Service can tamper with other services that run under the same identity. IIS worker processes are the most exposed in that environment as they run third-party code (Classic ASP, ASP.NET, PHP code, ..). Isolation of IIS worker processes from other Windows system services is done by making them running under unique identities (service accounts) with low privileges.
  • It allows Kerberos SSO in a load-balanced Director deployment, which makes this module suitable for a resilient Director deployment in a Xendesktop site.

xActiveDirectory DSC ressource is used to create the service account and associate the director SPN to it.

class xd7director::serviceaccounts inherits xd7director { #Needed for ActiveDirectory remote management using Powershell dsc_windowsfeature{ ‘RSAT-AD-Powershell’: dsc_ensure => ‘Present’, dsc_name => ‘RSAT-AD-Powershell’ } #Director service account creation (Active Directory) dsc_xaduser{‘SvcDirectorAccount’: dsc_domainname => $domainName, dsc_domainadministratorcredential => {‘user’ => $setup_svc_username, ‘password’ => $setup_svc_password}, dsc_username => $director_svc_username, dsc_password => {‘user’ => $director_svc_username, ‘password’ => $director_svc_password}, dsc_ensure => ‘Present’, require => Dsc_windowsfeature[‘RSAT-AD-Powershell’] } #Configure SPN on Director service account #In A load-balanced deployment, the SPN is linked to the FQDN of the Director virtual server configured on the load-balancer if $loadbalandedDirector { dsc_xadserviceprincipalname{‘DirectorLoadBalancedSPN’: dsc_account => $director_svc_username, dsc_serviceprincipalname => “http/${loadbalancedDirectorFqdn}”, dsc_ensure => present, dsc_psdscrunascredential => {‘user’ => $setup_svc_username, ‘password’ => $setup_svc_password}, require => Dsc_xaduser[‘SvcDirectorAccount’] } } #In a standalone deployment, the SPN is linked to the computer FQDN else { dsc_xadserviceprincipalname{‘DirectorStandaloneSPN’: dsc_account => $director_svc_username, dsc_serviceprincipalname => “http/${fqdn}”, dsc_ensure => present, dsc_psdscrunascredential => {‘user’ => $setup_svc_username, ‘password’ => $setup_svc_password}, require => Dsc_xaduser[‘SvcDirectorAccount’] } } #Add service accounts to local admins IIS_IUSRS group (local machine) dsc_xgroup{‘SvcDirectorIISGroup’: dsc_groupname => ‘IIS_IUSRS’, dsc_ensure => ‘Present’, dsc_memberstoinclude => “$domainNetbiosName\\$director_svc_username”, #dsc_psdscrunascredential => {‘user’ => $setup_svc_username, ‘password’ => $setup_svc_password}, require => Dsc_xaduser[‘SvcDirectorAccount’] } #Grant “Log on as a batch job” and “Impersonate a client after authentication” to Director service account dsc_userrightsassignment{‘AssignLogOnAsBatchToDirector’: dsc_policy => ‘Log_on_as_a_batch_job’, dsc_identity => ["$domainNetbiosName\\$director_svc_username", ‘Administrators’, ‘Backup Operators’, ‘Performance Log Users’], require => Dsc_xaduser[‘SvcDirectorAccount’] } dsc_userrightsassignment{‘AssignImpersonateAfterAuthenticationToDirector’: dsc_policy => ‘Impersonate_a_client_after_authentication’, dsc_identity => ["$domainNetbiosName\\$director_svc_username", ‘Administrators’, ‘Local Service’, ‘Network Service’, ‘Service’], require => Dsc_xaduser[‘SvcDirectorAccount’] } }

install.pp : iis and director 7.15 installation

Director is installed using the Virtualengine/XenDesktop7 DSC module which handles calls to the XenDesktop installer with the correct parameters ans installs the requested XenDesktop feature. The setup media can be located locally on the computer or on a remote fileshare (recommended for a splitted deployment where Citrix roles are installed on separate servers).

class xd7director::install inherits xd7director { #Install Citrix Director dsc_xd7feature { ‘XD7Director’: dsc_role => ‘Director’, dsc_sourcepath => $sourcePath, dsc_ensure => ‘present’ } }

config.pp : director 7.15 configuration

This part of the module links Director to the Delivery Controllers of the XenDesktop site.

The IIS application pool is also configured to run under the service account identity. This configuration enables Kerberos SSO in a load-balanced environment, all the Director services behind the load-balancer running under the same service account with the same Kerberos Service Principal Name (SPN).

class xd7director::config inherits xd7director { #Pairing Director to Delivery Controllers dsc_xwebconfigkeyvalue{ ‘ServiceAutoDiscovery’: dsc_configsection => ‘AppSettings’, dsc_key => ‘Service.AutoDiscoveryAddresses’, dsc_value => $deliveryControllers, dsc_isattribute => false, dsc_websitepath => ‘IIS:\Sites\Default Web Site\Director’ } #Configue Director ApplicationPool service account dsc_xwebapppool{‘DirectorAppPool’: dsc_name => ‘Director’, dsc_ensure => ‘Present’, dsc_autostart => true, dsc_enable32bitapponwin64 => false, dsc_managedruntimeversion => ‘v4.0’, dsc_managedpipelinemode => ‘Integrated’, dsc_disallowoverlappingrotation => true, dsc_disallowrotationonconfigchange => true, dsc_restartschedule => [‘00:00:00’], dsc_identitytype => ‘SpecificUser’, dsc_credential => {‘user’ => “${domainNetbiosName}\\${director_svc_username}”, ‘password’ => $director_svc_password}, dsc_state => ‘Started’, } #Changing authentication mode to use ApplicationPool dsc_script{ ‘DirectorUseAppPoolCredentials’: dsc_getscript => ‘$useAppPoolCredentials = Get-WebConfigurationProperty -pspath \‘MACHINE/WEBROOT/APPHOST\’ -location \‘Default Web Site/Director\’ -filter \‘system.webServer/security/authentication/windowsAuthentication\’ -name \‘useAppPoolCredentials\’ return @{ Result = $useAppPoolCredentials.Value }’, dsc_testscript => ‘$useAppPoolCredentials = Get-WebConfigurationProperty -pspath \‘MACHINE/WEBROOT/APPHOST\’ -location \‘Default Web Site/Director\’ -filter \‘system.webServer/security/authentication/windowsAuthentication\’ -name \‘useAppPoolCredentials\’ return (\‘true\’ -eq $useAppPoolCredentials.Value)’, dsc_setscript => ‘Set-WebConfigurationProperty -pspath \‘MACHINE/WEBROOT/APPHOST\’ -location \‘Default Web Site/Director\’ -filter \‘system.webServer/security/authentication/windowsAuthentication\’ -name \‘useAppPoolCredentials\’ -value \‘true\’’ } #Disable kernel mode authentication dsc_script{ ‘DirectorDisableKernelMode’: dsc_getscript => ‘$useKernelMode = Get-WebConfigurationProperty -pspath \‘MACHINE/WEBROOT/APPHOST\’ -location \‘Default Web Site/Director\’ -filter \‘system.webServer/security/authentication/windowsAuthentication\’ -name \‘useKernelMode\’ return @{ Result = $useKernelMode.Value }’, dsc_testscript => ‘$useKernelMode = Get-WebConfigurationProperty -pspath \‘MACHINE/WEBROOT/APPHOST\’ -location \‘Default Web Site/Director\’ -filter \‘system.webServer/security/authentication/windowsAuthentication\’ -name \‘useKernelMode\’ return (\‘false\’ -eq $useKernelMode.Value)’, dsc_setscript => ‘Set-WebConfigurationProperty -pspath \‘MACHINE/WEBROOT/APPHOST\’ -location \‘Default Web Site/Director\’ -filter \‘system.webServer/security/authentication/windowsAuthentication\’ -name \‘useKernelMode\’ -value \‘false\’’ } }

sslconfig.pp : director 7.15 SSL configuration

This manifest donwloads and installs the webserver’s SSL certificate on the server WebHosting certificate store. The xWebsite DSC resource is used to configure the HTTPS IIS binding using the downloaded certificate to secure the Citrix XML service. Secure Director access is mandatory when NTLM or login/password authentiction method are used to maintain confidentiality of the privileged administrators or operators credentials.

class xd7director::sslconfig inherits xd7director { if $https { if ($caCertificateSourcePath != ‘') { #Import and install CA certificate in LocalMachine Root store dsc_file{ ‘CACert’: dsc_sourcepath => $caCertificateSourcePath, dsc_destinationpath => ‘c:\SSL\ca.pem’, dsc_type => ‘File’ } dsc_xcertificateimport{ ‘ImportCACert’: dsc_thumbprint => $caCertificateThumbprint, dsc_path => ‘c:\SSL\ca.pem’, dsc_location => ‘LocalMachine’, dsc_store => ‘Root’, require => Dsc_file[‘CACert’] } } #Import and install server certificate dsc_file{ ‘SSLCert’: dsc_sourcepath => $sslCertificateSourcePath, dsc_destinationpath => ‘c:\SSL\cert.pfx’, dsc_type => ‘File’ } dsc_xpfximport{ ‘ImportSSLCert’: dsc_thumbprint => $sslCertificateThumbprint, dsc_path => ‘c:\SSL\cert.pfx’, dsc_location => ‘LocalMachine’, dsc_store => ‘WebHosting’, dsc_credential => {‘user’ => ‘cert’, ‘password’ => $sslCertificatePassword }, require => Dsc_file[‘SSLCert’] } dsc_xwebsite{ ‘DefaultWebSiteSSL’: dsc_name => ‘Default Web Site’, dsc_bindinginfo => [ { protocol => ‘HTTPS’, port => ‘443’, certificatethumbprint => $sslCertificateThumbprint, certificatestorename => ‘WebHosting’ } ], require => Dsc_xpfximport[‘ImportSSLCert’] } } else { dsc_xwebsite{ ‘DefaultWebSite’: dsc_name => ‘Default Web Site’, #dsc_physicalpath => ‘%SystemDrive%\inetpub\wwwroot’, dsc_bindinginfo => [ { protocol => ‘HTTP’, port => ‘80’} ], } } }