What's new

This release includes fixes and improvements to the XenDesktop Setup Wizard with enhancements to the Active Directory group enumeration method. See the fixed and known issues for additional information about this release of Provisioning Services.

The Provisioning Services Console contains the XenDesktop Setup Wizard, which provides integration tasks between Provisioning Services, XenDesktop and Windows Active Directory. The Wizard, accessible from the PVS Console, creates the VMs and any necessary objects in PVS, XenDesktop and Windows Active Directory. This implementation was limited due to the absence of an exposed API, without it, PVS users could not execute various automated testing paradigms in their environments.

At this release, XenDesktop Setup Wizard and Streamed VM Wizard functionality are exposed with a new service on the PVS Server through a Powershell API. This API provides a PowerShell front end that can be used to automate the functionality provided by the Streamed VM Setup Wizard and the XenDesktop Setup Wizard.

The PVS API service uses a SSL connection requiring a X.509 certificate on the PVS server. The certificate’s CA certificate must also be present on the PVS server and console machine. 

To create a self-signed certificate for PVS API: 

1. Download and install the Windows SDK for your PVS Server operating system. 
2. Open a command prompt and navigate to the bin folder of the SDK.  By default: C:\Program Files (x86)\Windows Kits\SDK_Version\bin\x64>. 
3. Run the following commands: 

a. Create a certificate to act as your root certificate authority: 

makecert -n "CN=PVSRootCA" -r -sv PVSRootCA.pvk PVSRootCA.cer 

b. Create and install the service certificate: 

makecert -sk PVSAPI -iv PVSRootCA.pvk -n "CN=FQDN of the PVS Server" -ic PVSRootCA.cer -sr localmachine -ss my -sky exchange -pe 

c. Install the root CA certificate in the Trusted Root Certification Authorities location on the server and console Machines: 

certmgr -add "PVSRootCA.cer" -s -r localMachine Root 

4. Run the Configuration Wizard. On the Soap SSL Configuration page, select the certificate created. 

After installing the latest Provisioning Services Server:

1. Run the configuration wizard.
2. Open the Services window on the PVS Server and verify that the PVS API is installed and configured to run as a PVS administrator:

3. Open a PowerShell window on your PVS server:

a. Import-Module, C:Program Files\Citrix\Provisioning Services\Citrix.ProvisioningServices.dll

b. Get-Command-Module.

The image below illustrates command options available at this release:

c. Ping the PVS API service:

Get-PvsApiServiceStatus -PvsServerAddress <FQDN of PVS Server> -PvsServerPort <Port PVS API is configured to listen on> 

d. Login to the PVS API (use either of the following commands):

Use Domain/Username/Password parameters:

Get-PvsConnection -PvsServerAddress <FQDN of PVS Server> -PvsServerPort <SOAP Port +1 PVS API is configured to listen on> -Domain <PVS Admin Domain> -Username <PVS Admin username> -Password <PVS Admin password>

Use Pass-in PSCredential object:

Get-PvsConnection -PvsServerAddress <Address of PVS Server> PvsServerPort-Credentials <PSCredential Object returned by Get-Credential>

The following cmdlets are included with the new PVS API implementation:

• Get-PvsApiServiceStatus. Pings the service to determine whether the service is up and running at a particular address/port.
• Get-PvsConnection. Log into the PVS API. 
• Clear-PvsConnection. Logout of PVS API; this adds the Auth Token to the blacklist.
• Start-PvsProvisionXdMachines. Used for XenDesktop Setup Wizard automation.
• Start-PvsProvisionMachines. Used for Streaming VM Setup Wizard automation.
• Get-PvsProvisioningStatus. Uses the ID returned from either of the previous two commands to get the status of the current provisioning session.
• Stop-PvsProvisionMachines. Uses the ID returned from either of the previous two commands to cancel the current provisioning session.

Examples for these Powershell cmdlets can be accessed using the Get-Help CommandName –Examples:

When connecting to the API using the Set-PvsConnection PowerShell command, a connection object is returned, resembling the image below:  

Within Provisioning Services, the user access control method is based on the user’s Active Directory login credentials and the PVS administrative group configuration. As a result of this method, AD group enumeration is repeatedly triggered by events associated with Configuration Wizard and Console operations; in complex AD environments where spurious logins can occur, the system can become sluggish, with slow responses resulting in connection timeouts to the PVS Console. This release resolves such issues by improving the method responsible for AD group enumeration.

Prior to this release, AD group enumeration occurred by scanning memberships associated with the user’s login in its domain and the entirety of the trusted domains until all the user’s group memberships are determined, or if there are no additional domains to search. The identified groups are compared to the PVS administrative groups defined in the database to determine the user’s access rights.

With this release, AD group enumeration has been enhanced to intelligently search preferred domains for a user’s login memberships, rather than searching the entirety of groups over all domains. The PVS administrative group name associated with the user’s login credential is used to provide the preferred domain list. The user’s domain list is searched first, followed by the preferred list; during this search, if a Farm’s administrative group is discovered, the search halts because the user already has full access rights to the PVS Farm.  This new search paradigm also includes a mechanism that uses the domain security ID to verify if the domain contains the intended groups. This modified searching approach of domains for a user’s login membership should address the needs of most AD environments, resulting in faster Configuration Wizard and Console operations.

For some special AD environments, typically those with complex nested groups and domains with many trust associations, the default method may be unable to find the user’s expected PVS administrative memberships. To resolve such scenarios, a registry setting has been added enabling you to change the search approach:

1. In the registry setting, locate HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ProvisioningServices.
2. Create a DWORD named “DomainSelectOption”.
3. In the DomainSelectOption DWORD, set one of the following values (in decimal format) for the desired search approach:

0 – The default search. This method searches the user’s domain followed by PVS administrative group domains.

1 –  Search in the user’s domain and in the PVS administrative group domain, followed by other trusted domains within a user’s domain.

2 – Obsolete. 

3 – Search in the user’s domain followed by PVS administrative group domains; the groups that are discovered are further enumerated over the parent’s domain. 

4 – Search the user’s domain and in the PVS administrative group domain, followed by other trusted domains within a user’s domain; the groups that are discovered are further enumerated over the parent’s domain.