Managing the endpoint and giving your users the same experience across multiple devices is a task that most companies give headaches. The Endpoints that are managed using an Endpoint manager are the least of their concerns, but all the user’s private devices are another discussion. You can’t manage them so it’s hard to configure the installed applications without having access to the device. When looking at the Citrix Workspace App (CWA) you can now control the settings on the endpoint(s) and give the users always the same experience on all the devices they use. Citrix gives companies (and their Citrix administrators) access to the Global App Configuration Services (GACS). GACS has multiple benefits, The two most important ones are:
- It gives users the possibility to use their company e-mail address to configure the Workspace App (Discovery Records APIs)
- You can configure the settings for the CWA on the user’s endpoint as mentioned before (Setting Records APIs).
I will help you make use of both the benefits; you can easily follow the guides below to set up a basic configuration and get you up to speed with using GACS.
Requirements
To make use of the Global App Configuration Services we need to look at the requirements:
Citrix Cloud Account
To get started with GACS you need a Citrix Cloud account with an active Citrix Workspace entitlement. This means that you need Citrix Cloud licenses, it doesn’t work when you only create a Citrix Cloud account sadly.
Domain Claims
The second requirement is that you need to claim your domain and if using an on-premises environment also claim your gateway URL. To claim your domain (and when needed your gateway URL) follow this guide.
Workspace App version support
Your users need to have a specific version of the Workspace App, see the below list:
| CITRIX WORKSPACE APP PLATFORM | MINIMUM VERSION SUPPORTED |
|---|---|
| Windows | Current Release – 2106, LTSR – 2203.1 |
| Mac | 2203.1 |
| iOS | 2104 |
| HTML5 | 2111 |
| Chrome OS | 2203 |
| Android | 2104 |
When your company meets the requirements, we can start configuring Global App Configuration Services:
Setting up Domain name configuration (Discovery Records APIs)
The first thing that you need to set up and give your users a better adoption of your (new) Citrix environment is to make it possible to use their company’s e-mail address to configure the CWA.
Let’s get started, go to the DiscoveryController
- First we need to use the getAllDiscoveryApiUsingGET
- Click on the “Invoke API” Button.
- Set the values in the Header Parameters as follows:
- Accept = set to “application/json”
- Authorization:
- Click the “Generate here” link
- Client ID = API ID
- Client Secret = API Secret
- Citrix-CustomerId = Is the customer ID that you can find within Citrix cloud > Identity and Access Management > API Access.
- Citrix-TransactionId = leave empty for now.
- Click the “Execute” button
- Make sure you receive the following response HTTP/1.1 200
- Download the JSON and save it somewhere (you may need it as reference).
- Now we go to the postDiscoveryApiUsingPOST
- Click on the “Invoke API” Button.
- Set the Header Parameters the same as in step 1
- Set the Path Parameters value:
- App = Workspace
- Set the Body Parameters:
- Fill in the ServiceURLs : https://<customname>.cloud.com:443
- Fill in the claimed domain name = <domain>.<root>
- Click the “Execute” button
- Now we go to the getDiscoveryApiUsingGET
- Click on the “Invoke API” Button.
- Set the Header Parameters the same as in step 1
- Set the Path Parameters value:
- App = Workspace
- Domain = <domain>.<root>
- Click the “Execute” button
- Now we go to the putDiscoveryApiUsingPUT
- Click on the “Invoke API” Button.
- Set the Header Parameters the same as in step 1
- Set the Path Parameters value:
- App = Workspace
- Domain = <domain>.<root>
- Set the Body Parameters:
- Fill in the ServiceURLs : https://<customname>.cloud.com:443 (Make sure you type https, otherwise you receive an error message: Errorcode 3FF)
- Fill in the claimed domain name = <domain>.<root> (same as step 2&3)
- Click the “Execute” button
Now you can use your mail address to setup you Citrix Workspace App and you don’t have to give users the complex Citrix Workspace URL.
Now that we have made it easier for the end-user to configure the Workspace App, let’s start with the configuration of the Workspace app so this gives the user always the same experience.
Configure the Citrix Workspace App (Setting Records APIs)
The second part is the hardest part, as you need to create a JSON file that sets all the required settings, you can find an overview of all the available settings here. Below you see an example that’s also mentioned within the documentation.
"android": [
{
"category": "Audio",
"userOverride": true,
"assignedTo": [
"AllUsersNoAuthentication"
],
"settings": [
{
"name": "Audio Streaming",
"value": "Play and record"
}
]
}
],
Let’s get started, go to the SettingsController
- To start, use the example Citrix created in their documentation, and add/remove the settings you wish to control. Make sure you verify the JSON before you try to use it in the Settings Records APIs.
- Now we need to use the getAllSettingsApiUsingGET (If this is the first time you start with the Settings Record APIs, you can skip this step. You will receive a 404 error if there is no config.)
- Click on the “Invoke API” Button.
- Set the values in the Header Parameters as follows:
- Accept = set to “application/json”
- Authorization:
- Click the “Generate here” link
- Client ID = API ID
- Client Secret = API Secret
- Citrix-CustomerId = Is the customer ID that you can find within Citrix cloud > Identity and Access Management > API Access.
- Citrix-TransactionId = leave empty for now.
- Click the “Execute” button
- Now we go to the postSettingsApiUsingPOST
- Click on the “Invoke API” Button.
- Set the Header Parameters the same as in step 2
- Set the Path Parameters value:
- App = Workspace
- Set the Body Parameters:
- Use the JSON file you created in step 1.
- Click the “Execute” button
- Now we go to the getSettingsApiUsingGET
- Click on the “Invoke API” Button.
- Set the Header Parameters the same as in step 2
- Set the Path Parameters value:
- App = Workspace
- URL = Based 64 URL Encoded
To get a Base 64 URL Encoding, I used the following site: https://www.base64url.com/ There I used the ServiceURL and that generated the Base 64 URL Encoding.
- Click the “Execute” button
- Now we go to the putSettingsApiUsingPUT
- Click on the “Invoke API” Button.
- Set the Header Parameters the same as mentioned in step 2
- Set the Path Parameters the same as in step 4
- Set the Body Parameters:
- Use the JSON file you created in step 1 and used in stap 2.
- Click the “Execute” button
- You receive a Warning that you will change the production environment.
Click Continue
Verify the settings using the Citrix Workspace App
Now that we have configured our required settings, let’s test it. I use the following setting for android, which sets the Audio Streaming but doesn’t allow the user to change (UserOverride: false) it as you can see below:
"android": [
{
"category": "Audio",
"userOverride": false,
"assignedTo": [
"AllUsersNoAuthentication"
],
"settings": [
{
"name": "Audio Streaming",
"value": "Play and record"
}
]
}
],
In the Screenshots from my Android Phone, you can see that the Workspace App is configured as mentioned.
Changes are active approximately 10 minutes after an Admin change anything, according to the Citrix documentation:
How does the service work?
From the client-side, the developer applies the following Citrix Workspace app settings that an admin provides:
- The settings are delivered to the workspace app clients through the Content Delivery Network (CDN) URL. Admin adds settings for each URL and the client decides which setting to load as default serviceURL.
- After an admin updates the settings on the Global Apps configuration service the CDN URLs are updated. It takes 10 mins approximately to purge the cache.
- The Citrix Workspace app client team calls the CDN URL at regular frequency to fetch and update the latest settings on the Citrix Workspace app.
Conclusion
The Global App Configuration Services makes it possible to make it easier for your users to access your Citrix Environment, it also makes it possible to configure the Citrix Workspace app without access to the endpoint. As shown it’s not easy to setup and it toke me some time to figure it out. Hope this helps you get started with this nice feature.
