APIs

There are four APIs available with Citrix Provisioning. Each API has its own Programmer’s Guide. There is also a guide on how to manage the transition between the deprecated PowerShell API and the object-oriented PowerShell API.

Active Directory group enumeration method

The Citrix Provisioning Console contains the Citrix Virtual Apps and Desktops Setup Wizard. It provides integration tasks between Citrix Provisioning, Citrix Virtual Apps and Desktops and Windows Active Directory. The Wizard, accessible from the Provisioning Console, 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 could not 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 that 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 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>.
  3. Run the following commands:

    a. Create a certificate to act as your root certificate authority: makecert -n “CN= P VSRoot CA” -r -sv P VSRoot CA.pvk P VSRoot CA.cer b. Create and install the service certificate: makecert -sk P VSAP I -iv P VSRoot CA.pvk -n “CN= FQDN of the PVS Server” -ic P VSRoot CA.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: cert mgr -add “PVSRoot CA.cer” -s -r localMachine Root

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

Note:

When you run the 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. Login 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 username> -Password <PVS Admin password>

**Use Pass-in P SCredent ial 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 DatabaseAccess 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 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, rather 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 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 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.

APIs