Global App Configuration Service

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:

  1. It gives users the possibility to use their company e-mail address to configure the Workspace App (Discovery Records APIs)
  2. 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 PLATFORMMINIMUM VERSION SUPPORTED
WindowsCurrent Release – 2106, LTSR – 2203.1
Mac2203.1
iOS2104
HTML52111
Chrome OS2203
Android2104

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

  1. 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).
  2. 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
  3. 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
  4. 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

  1. 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.
  2. 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
  3. 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
  4. 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
  5. 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:

  1. 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.
  2. 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.
  3. 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.

Reauthentication period for Workspace app

In the latest update, Citrix released a new feature called “Reauthentication period for Workspace app”. This enables the Citrix admin to set the reauthentication time for a user. This is one of the most frequently asked questions when I implement Citrix Virtual Apps and Desktops services with Citrix Gateway Services. People authenticate using the defined Identity Provider (IdP) (look here for choosing the correct IdP) and keep signed in, without the need to reauthenticate when they go home and continue to work there.

Yes, they authenticated when they started the Citrix Workspace app, and yes they authenticated when signing into their laptop at home. But for most IT managers it feels strange that when they sign on at the office where conditional access doesn’t require MFA, the user can go home and continue working without authentication with MFA. They think it’s a security risk, which I understand, but everything depends on the security of the mobile device.

Before Citrix released the feature “Reauthentication period for Workspace app” (which currently is in Tech Preview), the only option to control the authentication token is to set it with a GPO or Registry Key. The authentication tokens were designed so a user doesn’t need to reenter their credentials when the system or session restarted. The token is stored encrypted on the device, but it was not possible to set a maximum duration. As of Citrix Workspace app v2106, you are able to disable or enable storing the authentication token on the local device using the Global App Configuration Service

Configuring the Reauthentication period

The default setting requires users to sign in every 24 hours (1 day). You could specify a longer time up to 365 days (I won’t know why you would choose such a long time, but it’s possible). If you specify a longer period than 24 hours, the user always needs to reauthenticate after four days of inactivity.

To change the default reauthentication period, sign in to the Citrix Cloud console, go to the workspace configuration, and select preferences. Scroll down to workspace sessions, where it’s possible to change the current reauthentication period.

Supported Workspace app clients

The following versions of the Citrix Workspace app support this feature:

  • Workspace app 2106 for Windows or later
  • Workspace app 2106 for Mac or later
  • Workspace app for 21.6.5 iOS or later
  • Workspace app for 21.6.0 Android or later

Supported authentication methods

Staying signed in to the Workspace app is supported for the following authentication methods:

  • Active Directory
  • Active Directory plus token
  • Azure Active Directory
  • Citrix Gateway
  • Okta

I personally would like to set the reauthentication time to a shorter time than 1 day, let’s say 12 hours, this makes it more secure and the user will notice that he needs to sign in again when continuing work after going home. For more information regarding the reauthentication period, see the Citrix docs.