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.
- Object-oriented PowerShell interface: PowerShell with Object Programmer’s Guide
- Deprecated PowerShell interface: PowerShell (Deprecated) Programmer’s Guide
- Managing the transition between the deprecated PowerShell interface and the object-oriented PowerShell interface: Transition to PowerShell with Objects from PowerShell (Deprecated) Programmer’s Guide
- SOAP Server interface: SOAP Server Programmer’s Guide
- MCLI interface: MCLI Programmer’s Guide
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 console, creates the VMs and any necessary objects in Citrix Provisioning, Citrix Virtual Apps and Desktops and Windows Active Directory.
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. It can be used to automate the functionality provided by the Streamed VM Setup Wizard and the Citrix Virtual Apps and Desktops Setup Wizard.
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:
- Download and install the Windows SDK for your provisioning server operating system.
- 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.
- Create a certificate to act as your root certificate authority: makecert -n “CN= PVSRoot CA” -r -sv PVSRoot CA.pvk PVSRoot CA.cer.
- 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.
- 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.
- Run the Configuration Wizard. On the Soap SSL Configuration page, select the created certificate.
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:
- Run the configuration wizard.
- Open the Services window on the provisioning server and verify that the Citrix Provisioning API is installed and configured to run as an administrator:
The Citrix Provisioning API service uses an SSL connection which requires you to configure an X.509 certificate on the provisioning server.
- Open a PowerShell window on your provisioning server:
a. Import-Module C:Program Files\Citrix\Provisioning Services\Citrix.ProvisioningServices.dll.
The following image illustrates command options:
c. Ping the Citrix Provisioning API service: Get-PvsApiServiceStatus -PvsServerAddress FQDN of PVS Server -PvsServerPort Port PVS API is configured to listen on
The provisioning server port number is the one used for SOAP server communication.
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 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 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:
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:
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 should address the needs of most AD environments, resulting in faster Configuration Wizard and provisioning console operations.
Modifying the search approach
For some AD environments, 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:
- In the registry setting, locate HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\ProvisioningServices.
- Create a DWORD named “DomainSelectOption.”
- 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.