Product Documentation

What's new

Mar 07, 2018

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.

Note

Use the most recent version of the Citrix License Server to get the latest features. If you are upgrading from an existing version of Provisioning Services to the newest version of Provisioning Services, the most recent version of the license server is available by using the product software. When you do not upgrade to the latest version of the license server, the product license enters the 30-day grace period. For more information, see Licensing.

Provisioning API improvements

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.

Tip

The PVS API servivce uses a SSL connection which requires you to configure a X.509 certificate on the PVS server.

Configure X.509 certificate

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. 

Note

When you run the PowerShell commands, use the "FQDN of the PVS Server" for PvsServerAddress and 54324 (default) for PvsServerPort

Using the PVS API

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:

Tip

PVS administrative privileges are configured as the same SOAP user. 

localized image

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:

localized image

c. Ping the PVS API service:

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

Tip

The PVS server port number is the one used for SOAP server communication.

localized image

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>

localized image
localized image

Cmdlet overview

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:

localized image

Note

The rest of the PowerShell cmdlets are all part of the DatabaseAccess layer. 

PVS API authentication

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

localized image

Enhanced multi-tier Active Directory group search

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.

Modifying the search approach

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.

Tip

When using registry options 3 or 4, enhanced multi-tier AD Group search uses groups discovered using a flat search method; with this method, groups discovered in the domains are used to enumerate over their parent domains. This special enumeration uses the domain group’s MemberOf attribute, which is specifically used for AD environments possessing indirectly related groups in different domains; in such environments the flat search method cannot locate all the groups.