Driving the Citrix Cloud REST API with PowerShell

In this session, CTP Guy Leech walks through how to authenticate to Citrix Cloud via OAuth, and how to query and update CVAD configuration via the Citrix Cloud REST APIs using PowerShell, without the need for any Citrix PowerShell modules. Removing prerequisites in this way makes the resulting scripts extremely portable.

Video with live demos available at https://youtu.be/SxujGv7qct0

You'll be able to apply these techniques to other REST APIs from Citrix and across the industry.

This session was presented live, remotely, at the 2nd December 2021 meeting of the UK Citrix User Group

Transcript

1. Driving the Citrix Cloud REST API with PowerShell Guy Leech @guyrleech Freelance Consultant-cum-Developer Date 1
2. Who is this Guy Leech person anyway? • 25+ years of hands-on working with Citrix & other EUC products • C/C++ developer prior to that • 1st ever code written in 1980 (BASIC on Commodore PET, age 13) • Vendor awards from Microsoft, Citrix, VMware and Parallels • Wannabe comedian • @guyrleech
3. Citrix Cloud CVAD REST API • Automate deployment, changes, etc using code to CVAD running in Citrix Cloud • If you can do it in the web console, you can do it via REST (and more) • REST API usage workflow • Authenticate • Get API client & store securely (once) • Generate bearer token (OAuth 2.0) • Do stuff • Get/Set/New/Remove • Not available on-premises • Use PowerShell cmdlets with CVAD ISO or Studio (not Remote PoSH SDK)
4. Getting the Bearer Token • Create API Client in Identity & Access Management in cloud.com portal • Save csv file or client id and secret (securely!) • POST https://trust.citrixworkspacesapi.net/<customerid>/tokens/clients • Body contains ClientId & ClientSecret in JSON • JSON response contains 'token' • Add to headers for subsequent calls • Authorization = "CwsAuth Bearer <token>" • Citrix-CustomerId = <customerid> • Pass –SessionVariable and pass returned variable via –WebSession (cookies)
5. Performing Operations aka Doing Stuff • RTFM • Form your URL • Form your body • Is a body required – generally not needed for queries • Hashtable | ConvertTo-Json • Invoke-RestMethod • Assign result to variable (if expecting output as per documentation) • Wrap in try/catch and catch exception – report & remediate – retry ? • Repeat previous steps as required • Watch for bearer token expiring (default 1 hour) • Respect rate limits (10 per second per customer)
6. Using REST instead of Citrix Remote PowerShell SDK • No pre-requisites such as the PowerShell SDK • Platform & coding language independent • Need to know the API calls, headers and parameters • Documentation is comprehensive • Calls may change but should be backwardly compatible • Keep the base URL in a variable so only needs changing in one place • No versioning like with Azure REST API calls • Easy to reuse code/knowledge for other REST APIs • Authentication is often different • Can use with PowerShell 7.x • Invoke-RestMethod has –ResponseHeadersVariable to return response headers
7. API Client Scope and Permissions • API clients in Citrix Cloud are always tied to one administrator and one customer • API client details are not visible to other administrators • To access more than one customer create API clients within each customer • API client gets same permissions as user creating it • Q. What happens when the person who set up your automation leaves?
8. Potentially Useful Stuff • https://www.citrix.com/blogs/2021/10/18/announcing-remote-powershell-sdk-record-limits/ • https://developer.cloud.com/citrixworkspace/virtual-apps-and-desktops/cvad-rest-apis/docs/overview • https://github.com/guyrleech/Citrix/blob/master/CVAD%20REST.ps1 • Call rates are limited to 10 launches per second per customerId • Via web search engines* *Unlikely to be Bing🙂