Distribute the Desktop App using your Device Manager

  • Updated on Dec 19, 2024

Overview

Organizations can use their Device Managers (such as VMware Workspace ONE, Jamf Pro, Microsoft Intune, etc.) to distribute and register the desktop app to their entire fleet of managed devices. This is the recommended way to deploy Cloud Secure Edge (CSE) during a production roll out, as it allows you to obtain information about the trust scores of managed devices without any user impact.

Zero touch deployment for macOS and Windows

We currently support zero touch installation across all device managers but have a detailed guide published for Intune and JAMF. We will continue adding device manager guides.

CSE’s zero touch installation allows admins to deploy the app on macOS and Windows without requiring user intervention. This method does not require local users to have admin privileges. The IT Admin deploys the zero touch install script silently via the Device Manager; the end user does not need to interact with the app at all for the installation and registration to complete successfully.

With zero-touch install, the following steps are automated:

  • Creating an mdm-config.json file that specifies app functionality
  • Downloading the latest app version and installing it (you can also optionally specify an exact app version)
  • Staging the app with the device certificate that contains user information
  • Starting the app as the logged-on user

When a user logs into their device after a Zero Touch Install, the desktop app can be launched automatically and can run silently in the background. The Device Certificate will also be associated with this user and will support passwordless authentication flows.

Zero touch deployment for CSE’s Chrome Extension

For steps on how to complete zero touch deployment of CSE’s Chrome Extension, see this doc.

Unstage Devices

Unregistering and uninstalling the app must be done manually from the app settings. We are working on commands to completely unregister and uninstall the app via a Device Manager.

To return devices to a clean state, pass in the following command line arguments:

  • unstage - Run as an admin to remove the global staged files, allowing the device to be manually registered.

Run the following as an admin:

Windows: Start-Process -FilePath "C:\Program Files\Banyan\resources\bin\banyanapp-admin.exe" -ArgumentList "unstage"
macOS: '/Applications/Banyan.app/Contents/Resources/bin/banyanapp-admin' unstage

Distributing the CSE (formerly Banyan) Root Certificate for Windows

This requirement will be removed in an upcoming version of the desktop app for Windows. Please contact us for more details.

To completely eliminate any prompts for the end user when deploying the desktop app on Windows via zero touch, the CSE root certificate will need to be pushed via your Device Manager.

Please complete the following steps when supporting Zero Touch with Big Sur:

1. Obtain CSE root certificate by navigating from Settings > Configuration tab > Advanced tab > Issuing CA Certificate.

2. Update the mdm-config.json to set mdm_ca_certs_preinstalled to true.

3. Leverage your Device Manager to push down the root certificate.

Distributing the Linux desktop app

The desktop app installer for Linux is available in multiple formats (.deb, .rpm). You can download a specific version from the desktop app changelog.

There is currently no way to install and register the Linux app silently via a device manager.

Customizing desktop app functionality

You can customize desktop app functionality (such as device registration, startup behaviour, visible views, etc.) by configuring mdm parameters. For Zero Touch Installs, these parameters can be set in the script. For Linux, the mdm-config.json should be created and placed in the Global Config Directory via your Device Manager.

When you run the installer, the desktop app executable is placed in the Installation Directory on the device file system, while config files are placed in the Global Config Directory. The location of these directories depends on your Operating System:

Operating System Installation Directory Executable Name Global Config Directory
macOS /Applications/Banyan.app Banyan /etc/banyanapp
Windows %PROGRAMFILES%\Banyan Banyan.exe C:\ProgramData\Banyan
Linux /opt/Banyan banyanapp /etc/banyanapp

The following parameters can be set to customize desktop app functionality:

Parameter Permitted Values Purpose Description
mdm_invite_code string Registration Provide the Invite Code needed to register a device to your organization. Obtain from Command Center.
mdm_device_ownership string Registration Set device ownership type to one of the following: “C” for corporate-owned, “E” for employee-owned, “S” for corporate-shared, and “O” for other
mdm_ca_certs_preinstalled boolean Registration Skip installation of Root and Intermediate CA certificates (because the Device Manager has already installed them)
mdm_skip_cert_suppression boolean Registration Skip installation of scripts that suppress browser certificate prompts (because the Device Manager has already run them)
mdm_deploy_user string Zero Touch Install Provide the name of the user this device should be registered to
mdm_deploy_email string Zero Touch Install Provide the email address of the user this device should be registered to
mdm_reporting_interval integer Trust Scoring Set time interval (in minutes) for how often desktop app reports device features
mdm_present boolean Trust Scoring Inform CSE that the device is managed by a Device Manager
mdm_vendor_name string Trust Scoring Inform CSE which Device Manager is managing the device
mdm_vendor_udid string Trust Scoring Inform CSE about the ID used by the Device Manager to uniquely identify this device
mdm_disable_auto_update boolean App Behavior Do not prompt the end user to upgrade their desktop app when a new version is released (because the Device Manager will push the new version)
mdm_login_token_prompt_time integer App Behavior Denotes the amount of time (in minutes) until the user receives a login token pre-expiration notification
mdm_start_at_boot boolean App Behavior Always launch desktop app on device bootup
mdm_disable_quit boolean App Behavior Hide the Quit button in the Desktop App
mdm_hide_services boolean App Behavior Hide the Services tab that displays the list of Services a user can access
mdm_hide_on_start boolean App Behavior Starts the Desktop App in a minimized state
mdm__overwrite_k8_config boolean App Behavior Replaces kube config file when set to true; updates kube config file by default (without this parameter) or when set to false

Configuring the mdm_start_at_boot parameter

When the mdm_start_at_boot parameter is included in the mdm-config.json configuration file, the CSE app checks this parameter every time the app starts. This happens whenever an end user (i) opens the app, (ii) registers the app for the first time, or (iii) restarts the app.

This check is done during the app’s ready phase. If mdm_start_at_boot is set to true, the app will use Electron’s setLoginItemSettings API to ensure that the app starts automatically when the computer boots up.

On macOS devices, the setLoginItemSettings API creates an entry in the Login Items and Extensions section of System Settings, allowing the app to start when the computer boots up.

On Windows devices, this adds a Registry entry under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run, which tells the system to launch the app when the computer boots up.

The mdm_start_at_boot parameter is not applicable for Linux; so, if set, it has no effect.

Other Deployment Scenarios

Staged user and zero touch installation

In the default Zero Touch flow, the device should be registered to a specified user by setting the mdm-deploy-user and mdm-deploy-email parameters in the mdm-config.json file. The issued device certificate will contain a User Principal Name (UPN) username in the Subject Alternative Name field.

As a fallback, if user information is not specified or obtained during zero-touch flow the app will initially be registered to a STAGED USER, indicating it has been silently enrolled via zero touch installation. When a user logs into the device and accesses a service protected by Cloud Secure Edge, their username will automatically be associated with the device.

Device trust integration with Workspace ONE UEM

For organizations that have Workspace ONE UEM as their Device Manager and have already integrated CSE via the Workspace ONE UEM API, the desktop app will capture all the features that it normally captures. In addition, the app will use the Workspace ONE UEM API to check for Device Compliance. If Workspace ONE UEM reports the device as compliant, CSE will calculate Device Trust Level based on device features captured by the desktop app. If Workspace ONE UEM reports the device as non-compliant, the Device Trust Level is set to Always Deny.