APIs

Citrix Provisioning APIs are available on the Citrix Developer Documentation site:

PowerShell SDK files after upgrading

Files located in C:\Program Files\Citrix\PowerShell SDK are missing after upgrading. This issue occurs because the CDF version used by Citrix Provisioning does not match the version used by other components associated with Citrix Virtual Apps and Desktops. As a result, newer CDF files have a lower version number than previous ones. This issue does not affect the functionality of importing CPV device collections into CVAD machine catalogs. To resolve this issue:

  1. Close Citrix Studio.
  2. Mount the new Citrix Virtual Apps and Desktops ISO.
  3. In the mounted ISO, navigate to \x64\DesktopStudio.
  4. Right-click PVS PowerShell SDK x64 to expose a contextual menu.
  5. Select Repair.
  6. Run the Repair option. The installation adds the two CDF files as needed.

Active Directory group enumeration method

The Citrix Provisioning console contains the Citrix Virtual Apps and Desktops Setup Wizard, providing integration tasks between Citrix Provisioning, Citrix Virtual Apps and Desktops and Windows Active Directory. The Wizard creates the VMs and any necessary objects in Citrix Provisioning, Citrix Virtual Apps and Desktops and Windows Active Directory.

Note:

This implementation was limited in earlier releases due to the absence of an exposed API. Without it, Citrix Provisioning users cannot execute various automated testing paradigms in their environments.

Citrix Virtual Apps and Desktops and Streamed VM Wizard functionality are exposed by a service on the Provisioning Server through a PowerShell API. This API provides a PowerShell front end. It can be used to automate the functionality provided by the Streamed VM Setup Wizard and the Citrix Virtual Apps and Desktops Setup Wizard.

Tip:

The Citrix Provisioning API service uses an SSL connection which requires you to configure an X.509 certificate on the Provisioning Server.

Configure the X.509 certificate

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

To create a self-signed certificate for Citrix Provisioning API:

  1. Download and install the Windows SDK for your provisioning 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> and execute the following commands.
  3. Create a certificate to act as your root certificate authority: makecert -n "CN= PVSRoot CA" -r -sv PVSRoot CA.pvk PVSRoot CA.cer.
  4. Create and install the service certificate: makecert -sk PVSAP I -iv PVSRoot CA.pvk -n "CN= FQDN of the PVS Server" -ic PVSRoot CA.cer -sr localmachine -ss my -sky exchange -pe.
  5. Install the root CA certificate in the Trusted Root Certification Authorities location on the server and console Machines: cert mgr -add "PVSRoot CA.cer" -s -r localMachine Root.
  6. Run the Configuration Wizard. On the Soap SSL Configuration page, select the created certificate.

Note:

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

Using the Citrix Provisioning API

After installing the latest Citrix Provisioning server:

  1. Run the configuration wizard.
  2. Open the Services window on the provisioning server and verify that the Citrix Provisioning API is installed and configured to run as an administrator:

Tip:

The Citrix Provisioning API service uses an SSL connection which requires you to configure an X.509 certificate on the provisioning server.

Console site

  1. Open a PowerShell window on your provisioning server:

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

b. Get-Command-Module.

The following image illustrates command options:

Console site

c. Ping the Citrix Provisioning API service: Get-PvsApiServiceStatus -PvsServerAddress FQDN of PVS Server -PvsServerPort Port PVS API is configured to listen on

Tip:

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

Console site

d. Log in to the Citrix Provisioning 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 user name -Password PVS Admin password

Use Pass-in PSCredential object:

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

Console site

Console site

The following cmdlets are included with the Citrix Provisioning 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 Citrix Provisioning API.
  • Clear-PvsConnection. Logout of Citrix Provisioning API. This cmdlet adds the Auth Token to the blacklist.
  • Start-PvsProvisionXdMachines. Used for Citrix Virtual Apps and Desktops 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.

You can access examples for these PowerShell cmdlets using Get-Help CommandName – Examples:

Console site

Tip:

The rest of the PowerShell cmdlets are all part of the Database Access layer.

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

Console site

Within Citrix Provisioning, the user access control method is based on the user’s Active Directory login credentials and the administrative group configuration. As a result of this method, AD group enumeration repeatedly triggers 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 Citrix Provisioning console. This functionality resolves such issues by improving the method responsible for AD group enumeration.

Before this functionality, AD group enumeration occurred by scanning memberships associated with the user’s login in its domain and the entirety of the trusted domains. This process continues 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 administrative groups defined in the database to determine the user’s access rights.

With this functionality, AD group enumeration is enhanced to intelligently search preferred domains for a user’s login memberships. This approach is different than searching the entirety of groups over all domains. The 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 Citrix Provisioning farm. This 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 addresses the needs of most AD environments, resulting in faster Configuration Wizard and provisioning console operations.

Modifying the search approach

For some AD environments containing configurations with complex nested groups and domains with many trust associations, the default method might be unable to find the user’s expected administrative memberships. To resolve such scenarios, a use a registry setting 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 administrative group domains.
  • 1 – Search in the user’s domain and in the administrative group domain, followed by other trusted domains within a user’s domain.
  • 2 – Obsolete.
  • 3 – Search in the user’s domain followed by 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 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.