Product documentation
Citrix Workspace app for ChromeOS
View PDF

Peripherals

April 23, 2024
Contributed by: 
N

USB device redirection

Citrix Workspace app for ChromeOS supports a wide range of USB peripherals. With this added functionality, you can create a Google policy to identify the PID/VID of the device to enable its use in Citrix Workspace. This support extends to new USB devices too.

How to configure

For information on configuring USB devices, see Knowledge Center article CTX200825.

Automatic redirection of USB devices in Kiosk mode

In kiosk mode, USB devices are redirected automatically inside a session without any manual intervention. In user and public modes, for the first time, you must manually redirect the USB device into the session from the toolbar or the Connection Center. This manual USB redirection is done to grant permission to the Chrome operating system for accessing the USB device. When a USB device is inserted, it’s redirected into the session automatically.

Important:

  • If you insert a USB device when many sessions are running, the USB redirects into the session that is in focus.
  • If there are no sessions in focus, the USB device isn’t redirected into any session.
  • If a single session is running and if it isn’t in focus when you insert the USB device, the USB device redirection might fail.

To redirect the USB device to a new session

Note:

To redirect the USB device to a new session, it’s required to remove the USB device from the previous session.

  1. Right-click the Citrix Workspace icon and select Connection Center. The Connection Center window appears.
  2. Select a session or an application.
  3. Click Devices.
  4. Navigate to the USB section.
  5. Click Release All.

Double hop

Starting with the 2301 version, Citrix Workspace app supports double-hop scenarios. This feature is an enhancement to USB redirection.

For more information, see Double hop in the Citrix Virtual Apps and Desktops documentation.

Composite USB redirection

Previously, when a composite USB device was connected to the local device, it can only be used as a single device through USB redirection. The disadvantage was that the interfaces like audio and video also got redirected through USB, despite optimized channels. The interfaces weren’t separate and due to this incapability, administrators can’t decide which components to redirect through USB and which ones to redirect through the optimized virtual channel (like audio interface) to achieve the best performance.

Starting from the 2211 release, administrators can configure if certain interfaces of the device redirect to the session through USB redirection or not. The end user can now select and redirect a specific constituent interface of a composite USB device to the Citrix Workspace app session through USB redirection.

About composite USB redirection

USB 2.1 and later supports the notion of USB composite devices where many child devices share a single connection with the same USB bus. Such devices employ a single configuration space and shared bus connection where a unique interface number 00-ff is used to identify each child device. Such devices are also not the same as a USB hub which provides a new USB bus origin for other independently addressed USB devices for connection.

Composite devices found on the client endpoint can be forwarded to the virtual host as either:

  • a single composite USB device, or
  • a set of independent child devices (split devices)

When a composite USB device is forwarded, the entire device becomes unavailable to the local device. Forwarding also blocks the local usage of the device for all applications on the local device, including the Citrix Workspace app.

Consider a USB headset device with both an audio device and the HID button for mute and volume control. If the entire device is forwarded using a generic USB channel, the device becomes unavailable for redirection over the optimized HDX audio channel. However, you can achieve a better performance when the audio is sent through an optimized HDX audio channel when compared to a generic channel.

To resolve these issues, Citrix recommends you split the composite device and forward only the child interfaces that use a generic USB channel. Such a mechanism make sure that the other child devices are available for use by applications on the local device, including the Citrix Workspace app that provides optimized HDX experiences. This method allows the required devices to be forwarded and available to the remote session.

How to enable this feature

You can enable this feature in the following ways:

  • Configuration.js
  • Global App Configuration service
  • Google Admin Policy

Configuration.js

To configure composite USB redirection using the configuration.js file, do the following:

  1. Locate the configuration.jsfile in the ChromeApp root folder.

  2. Edit the configuration.js file to configure the composite USB redirection feature.

    Notes:

    • Citrix recommends that you back up the configuration.js file before making changes.
    • Citrix recommends editing the configuration.js file only if the Citrix Workspace app for ChromeOS is repackaged for users.
    • Administrator-level credentials are required to edit the configuration.js file.
  3. Set enableCompositeDeviceSplit to true.

The following is an example of JSON data:

```
{
    "features": {
        "usb": {
            "enableCompositeDeviceSplit": true
        }
    }
}
<!--NeedCopy--> ```
  1. Save the changes.

Note:

  • To disable the feature, set the enableCompositeDeviceSplit attribute to false.

Global App Configuration service

On the cloud setup, administrators can enable the composite USB redirection feature by setting the enableCompositeDeviceSplit attribute to True in the Global App Configuration service.

For more information, see the Global App Configuration service documentation.

Google admin policy

On the on-premises deployment, administrators can enable the composite USB redirection feature using the Google Admin Policy as follows:

  1. Sign in to the Google Admin Policy.
  2. Go to Device management > Chrome Management > User Settings.

  3. Add the following strings to the policy.txt file under the engine_settings key. Following is an example of JSON data:

    {
    "features": {
        "usb": {
            "enableCompositeDeviceSplit": true
        }
    }
}
<!--NeedCopy-->
  4. Save the changes.

Configuration

Prerequisites:

  • Allow list of USB Devices with VID:PID values and enable policy for USB device redirection on Delivery Controller. For more information, see the knowledge center article CTX200825.
  • This feature works on managed devices and not on BYOD.

To enable the auto-detection of the USB:

  1. Go to Google Admin Policy settings.
  2. Select the WebUSB API allowed devices option.
  3. Enter the Citrix Workspace app for the ChromeOS extension ID. For example, chrome-extension://haiffjcadagjlijoggckpgfnoeiflnem.

  4. Add the VID and PID of the device as follows:

    USB

    After adding the VID and PID values, the Citrix Workspace app can now automatically detect the devices in the session.

  5. Apply the Google Admin Policy. For more information on Device rules and sample JSON data, see the following section.

  6. Save the changes.

Device rules

Citrix Workspace app uses the device rules to decide, which USB devices to allow or prevent from forwarding to the remote session.

Following are the explanations of the keywords:

  • allow: This section includes the list of devices and their child interfaces that can be redirected to the session.
  • deny: This section includes the list of devices and their child interfaces that can’t be redirected to the session.

  • autoRedirect: This section includes the list of devices and their child interfaces that can be auto-redirected to the session through USB redirection.

    Note:

    • Each object represents a device with the mandatory vid and pid values of the USB device. It’s optional to have ‘split’, and ‘interfaceClass’ values.
  • vid, pid (mandatory): Represents Vendor ID (VID) and Product ID (PID) of the USB device. Enter the values in Hexadecimal format.
  • split (optional): Expects a boolean value that indicates whether the device to be split into child interfaces or not.
  • interfaceClass (optional): Represents USB interface class. The allowed values are audio, video, hid, printer, storage, and so on.

The following is an example of JSON data:

{
"settings": {
"value": {
"settings_version": "1.0",
"device_settings": {
"deviceRules": {

    "allow": [
        {"vid": "11","pid": "22",  "split":true, "interfaceClass":["audio","video"]} //split device and allow redirection of 'audio' & 'video' interfaces.
    ],

    "deny": [
        {"vid": "33","pid": "44"},  //deny redirection of this whole device with vid= 33 & pid = 44, including all of its interfaces.
        {"vid": "77","pid": "88","split":true,"interfaceClass":["audio"]}    //split device and deny the redirection of 'audio' interface only; remaining interfaces(if any) are redirected through USB.
    ],

    "autoRedirect": [
    {"vid": "55","pid": "66"}, //auto redirect the device when it's connected.
    {"vid": "55","pid": "66","split":true,"interfaceClass":["hid"]} //split device and auto redirect only the 'hid' interface when the device is connected.
    ]
                }
           }
       }
    }
}
<!--NeedCopy-->

How to use this feature

To use the composite USB redirection feature:

  1. Click the USB icon from the toolbar.

    USB

    If there are no USB devices connected, the following pop-up appears:

    USB

  2. Connect a USB device to your local machine. The following pop-up might appear:

    USB

  3. Click USB Devices to view and redirect the USB constituent. After a successful connection, the Citrix Workspace app detects the USB. For each USB constituent interface, you see a drop-down menu. The two options are:

    • In-session and local machine access (Optimized): select this option if you want to access the USB on your device and in a session.
    • In-session access (Generic): select this option if you want to access the USB only in the session. For better performance, select In-session and local machine access (Optimized) option.

    USB

  4. Select Connect for redirecting the interface.

    USB

    Upon successful redirection, the status changes to Connected.

Notes:

  • To add a USB device manually, click Add Device. The Chrome picker dialog appears that lists the USB devices. You can select the device from the list.

  • If a USB device connection is denied, the following error message appears:

    “Your administrator has blocked the newly inserted device. Contact your organization’s administrator for assistance.

How to transfer the USB interface between the sessions

When you click the USB icon from the toolbar, a list of USB devices that are connected to your sessions appears. If the USB device is already in use in a different session you can see that the USB constituent shows Connected to another session status.

To redirect to the current session, select Connect which is placed opposite to the USB constituent. The status changes accordingly.

Composite USB automatic redirection settings

Previously, there was no option related to USB automatic redirection settings to set the end user preferences. As administrators control these policies, the end user has to manually redirect required USB devices on every session launch.

Starting with the 2301 version, the end user can select a preference for auto-redirection for any USB device within a Virtual Desktop session. Citrix Workspace app now provides app-level settings, where the end user can control the USB auto-redirection. The end user can set preferences and can save the settings across session launches.

There are two options: one at the session launch and the other while the session is ongoing.

Auto redirection

Note:

  • This feature supports on-premises and cloud deployments and is available only for managed Chrome users.

Configure Composite USB Redirection through DDC policies

Previously, administrators used Google Admin policies to configure the client-side USB redirection.

Starting with the 2306 release, you can configure USB redirection through the DDC policies as well. Configurations through DDC policies allow administrators to have a unified and centralized way of defining policies and behavior. These policies are applicable for on-premises and cloud deployments on managed devices and users. This feature is supported on VDA versions 2212 and later.

Configuration

You can configure this feature in one of the following ways:

  • Configuration.js
  • Google Admin Policy

Note:

  • The policy enableDDCUSBPolicy is set to true by default.

Configuration.js

To disable this feature using the configuration.js file, do the following:

  1. Locate the configuration.js file in the ChromeApp root folder.

  2. Edit the file.

    Notes:

    • Citrix recommends that you back up the configuration.js file before making changes.
    • Citrix recommends editing the configuration.js file only if the Citrix Workspace app for ChromeOS is repackaged for users.
    • Administrator-level credentials are required to edit the configuration.js file.

  3. Set the value of enableDDCUSBPolicy to false. Following is an example of JSON data:

    
"features" : {
"usb" : {
   "enableDDCUSBPolicy": false
    }
}
<!--NeedCopy-->
  4. Save the changes.

Google admin policy

For managed devices and users, administrators can disable this feature using the Google Admin Policy as follows:

  1. Sign in to the Google Admin Policy.

  2. Go to Device management > Chrome Management > User Settings.

  3. Add the following strings to the policy.txt file under the engine_settings key. Following is an example of JSON data:

        "features" : {
    "usb" : {
       "enableDDCUSBPolicy": false
    }
}
<!--NeedCopy-->

  4. Save the changes.

DDC Policy

The following screenshot displays the DDC policies that are related to USB redirection. This feature is supported on VDA versions 2212 and later.

DDC

For more information on the DDC policies that are related to USB redirection, see the following articles in the Citrix Virtual Apps and Desktops documentation:

Auto redirection of USB devices

To redirect USB devices automatically, you must follow the USB device rules. You can configure USB device rules through:

Enhancements to Composite USB device UI

Starting with the 2306 release, when the configuration of a Composite USB device is set to “split”: true, the USB Devices UI displays the components based on interface numbers instead of interface classes.

For more information, see the Composite USB redirection article.

User interface

The following is an example:

Interface numbers

Enhancements to Composite USB redirection through DDC policies

Starting with the 2307 version, you can determine if a particular composite USB interface or class can redirect to VDA by default or not. If you have a composite USB connected to the ChromeOS device, then the configuration enableDefaultAllowPolicy helps you decide whether, by default, you can allow USB redirection through DDC policies. VDA versions 2212 and later support this feature.

How to use

When you set the attribute enableDefaultAllowPolicy to true, and if you redirect a particular interface class or interface number to the VDA, then you must add a policy rule to deny the other interface classes or numbers from being redirected. You can configure this feature through the DDC policy Client USB device redirection rules (Version 2).

For more information, see USB device redirection rules (Version 2). In addition, you can configure the denied part through the Google Admin Policy, but only for the interface class level.

For more information, see Enhancements to Composite USB device UI.

Here’s an example configuration through the DDC policy Client USB device redirection rules (Version 2), where you allow the interface number 03 to redirect.

```
"DENY: vid=1188 pid=A301 split=01 intf=00,01,02"
<!--NeedCopy--> ```

Here’s an example configuration through the Google Admin Policy rule, where you allow the HID interface to redirect and deny the audio interface class.

```
"deny": [
    {"vid":"05e9", "pid":"0428", "split":true, "interfaceClass":["audio"]
    }
]
<!--NeedCopy--> ```

Configuration

You can configure this feature in one of the following ways:

  • Configuration.js
  • Google Admin Policy

Note:

  • By default, the policy enableDefaultAllowPolicy is set to true.
Configuration.js

To disable this feature using the configuration.js file, do the following:

  1. Locate the configuration.js file in the ChromeApp root folder.

  2. Edit the file.

    Notes:

    • Citrix recommends that you back up the configuration.js file before making changes.
    • Citrix recommends editing the configuration.js file only if the Citrix Workspace app for ChromeOS is repackaged for users.
    • Administrator-level credentials are required to edit the configuration.js file.

  3. Set the value of enableDefaultAllowPolicy to false.

    The following is an example of JSON data:

    "features" : {
   "usb" : {
   "enableDefaultAllowPolicy": false
    }
}
<!--NeedCopy-->
  4. Save the changes.
Google admin policy

For managed devices and users, administrators can disable this feature using the Google Admin Policy as follows:

  1. Sign in to the Google Admin Policy.
  2. Go to Device management> Chrome Management > User Settings.

  3. Add the following strings to the policy.txt file under the engine_settings key.

    The following is an example of JSON data:

    'features' : {
    'usb' : {  
    'enableDefaultAllowPolicy': {"type": "false"}
    }
  }
<!--NeedCopy-->
  4. Save the changes.

Serial COM port redirection

By default, Citrix Workspace app for ChromeOS maps COM5 as a preferred serial COM port for redirection.

How to configure

To configure serial COM port redirection, enable the feature by applying Citrix Virtual Apps and Desktops and Citrix DaaS port redirection policy settings. For more information on port redirection, see Port redirection policy settings.

Note:

By default, Citrix Workspace app for ChromeOS maps COM5 as a preferred serial COM port for redirection.

After enabling serial COM port redirection policy settings on the VDA, configure Citrix Workspace app for ChromeOS using one of the following methods:

  • Google Admin Policy
  • configuration.js file
  • Changing the default mapping by issuing a command in an active ICA session.

Using Google Admin Policy to configure COM port redirection

Use this method to redirect the serial COM port by editing the policy file.

Tip:

Citrix recommends that you configure the COM port using the policy file only when Citrix Workspace app for ChromeOS is repackaged.

Edit the Google Admin Policy by including the following:

    {
      "settings": {
               "Value": {
                "settings_version": "1.0",
                "store_settings": {
                "rf_web": {
                "url": "<http://YourStoreWebURL>"
                 }
                 },
                 "engine_settings":{
                 "features" : {
                 "com" : {
       "portname" : "<COM4>", where COM4 indicates the port number that is set by the administrator.                                                   }
                                      }
                                      }
                                      }
                                      }
                                     }

 <!--NeedCopy-->

List of serial COM port name options and their descriptions:

  • “portname”: Port number for the COM (serial) virtual channel. By default, the value is COM5.

Using the configuration.js file to configure COM port redirection

Use this method to redirect the serial COM port by editing the configuration.js file. Locate the portname field in the configuration.js file and edit the value by changing the port number.

For example:

"com" :{

"portname" : "COM4"

}
<!--NeedCopy-->

Note:

Citrix recommends using the configuration.js file method to configure serial port redirection only when Citrix Workspace app for ChromeOS is repackaged and republished from StoreFront.

Issuing a command in an ICA session to configure COM port redirection

Use this method to redirect the serial COM port. Run the following command in an active ICA session:

    net use COM4 : \\Client\COM5
<!--NeedCopy-->

Tip:

In the example above, COM4 is the preferred serial port used for redirection.

Peripherals
April 23, 2024
Contributed by: 
N
April 23, 2024
Contributed by: 
N

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.