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:
- Close Citrix Studio.
- Mount the new Citrix Virtual Apps and Desktops ISO.
- In the mounted ISO, navigate to \x64\DesktopStudio.
- Right-click PVS PowerShell SDK x64 to expose a contextual menu.
- Select Repair.
- 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 run 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:
- 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 run 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 Authoritieslocation 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.
Note:
When you run PowerShell commands, use the FQDN of the PVS Server for
PvsServerAddressand 54324 (default) forPvsServerPort.
Citrix Provisioning API
To use the Provisioning API with the Citrix Virtual Apps and Desktops Service, you must provide credentials to authenticate to Citrix Cloud.
Use the Provisioning API with Citrix Virtual Apps and Desktops Service
When using the Citrix Virtual Apps and Desktop Service, the Provisioning API service running on each provisioning server requires credentials to authenticate to Citrix Cloud. After you provide these credentials, any process running with the specified user name uses the secure client credentials to authenticate to Citrix Cloud.
To provide these credentials:
- Log in to the Citrix Cloud portal IAM page as an admin user.
- Create a secure client from the Citrix Cloud IAM page. From this page, also record your customer ID.
- Download the secure client to a CSV file on the PVS server.
Important: The CSV file contains a secret that can be used to authenticate to Citrix Cloud as the user who created the secure client. Save and protect this file.
- On each server that runs Provisioning API calls:
- Run a PowerShell window using the Provisioning Services user name.
- Download the CSV file.
-
Run this command:
Set-XDCredentials -CustomerId "<customerIDFromPortal>" -SecureClientFile "<CSVPath>" -ProfileType CloudAPI –StoreAs "default" <!--NeedCopy--> - Delete the downloaded copy of the CSV file.
Use 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.
Tip:
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 and import the command module:
-
Import-Module "C:\Program Files\Citrix\Provisioning Services\Citrix.ProvisioningServices.dll". -
Get-Command-Module Citrix.ProvisioningServices. - 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.
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
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 block list.
- 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:
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:
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.