Distribute the Banyan Desktop App using your Device Manager

This capability requires Banyan Desktop App v1.11.0+. If you previously deployed Banyan Desktop App v1.5.x-1.10.x, then you must reconfigure and deploy v1.11.0+ in order to leverage the features described in this guide.

With the release of Banyan v3.11, the mdm_deploy_key parameter in mdm-config.json has been deprecated, as the OTP-based email verification exemption is a global setting and no longer requires the mdm_deploy_key to be sent out via the device manager.

Overview

Enterprises use Device Managers (such as VMware Workspace ONE, Jamf Pro, Microsoft Intune, etc.) to administer corporate laptops, phones, tablets, and other devices. IT Teams look to use their Device Managers to streamline the deployment and management of any software that needs to be installed on corporate devices.

Banyan fully integrates with Device Managers. You can use your Device Manager to distribute the Banyan Desktop App to your entire fleet of managed devices, and to streamline the user experience when registering their device. In addition, Banyan’s default Device TrustScoring algorithm can be supplemented with telemetry data gathered by the Device Manager.

Desktop App Executable and MDM-Config JSON File

The Banyan Desktop App installer is available in multiple formats (.dmg, .exe, .deb, .rpm) for the different Operating Systems you run on your devices. You can download a specific version from the Desktop App Changelog.

When you run the installer, the Banyan 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

You can customize Banyan Desktop App functionality (such as device registration, startup behavior, visible views, etc.) by placing an mdm-config.json in the Desktop App’s Global Config Directory.

If an mdm-config.json file does not exist in the Global Config Directory, the Banyan Desktop App will assume this is a default installation and use the default device registration flow as outlined in the Banyan Support Portal, exhibit default behavior, and display all views.

The following parameters can be set in the mdm-config.json to customize Banyan Desktop App functionality:

Parameter Permitted Values Purpose
mdm_invite_code string Provide the Invite Code needed to register a device to your organization. Obtain from Banyan Command Center.
mdm_present boolean Inform Banyan that the device is managed by a Device Manager; used in Device TrustScoring
mdm_vendor_name string Inform Banyan which Device Manager is managing the device; used in Device TrustScoring
mdm_vendor_udid string Inform Banyan about the ID used by the Device Manager to uniquely identify this device; used in Device TrustScoring
mdm_reporting_interval integer Set time interval (in minutes) for how often Desktop App reports device features; used in Device TrustScoring
mdm_ca_certs_preinstalled boolean Skip installation of Root and Intermediate CA certificates (because the Device Manager has already installed them)
mdm_skip_cert_suppression boolean Skip installation of scripts that suppress browser certificate prompts (because the Device Manager has already run them)
mdm_disable_auto_update boolean 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_start_at_boot boolean Always launch Desktop App on device bootup
mdm_disable_quit boolean Hide the Quit button in the Desktop App
mdm_device_ownership string 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_hide_services boolean Hide the Services tab that displays the list of Services a user can access
mdm_hide_on_start boolean Starts the Desktop App in a minimized state

The following parameters have been deprecated:

Deprecated Parameter Permitted Values Purpose
mdm_deploy_key string Provide a Deployment Key to to skip OTP email verification. Obtain from Banyan Command Center. (Deprecated in Banyan v3.11+).

Deployment Scenarios

Zero Touch Desktop App Installation and Device Registration

We currently support Zero Touch installation for all device managers, but have a detailed guide published for Intune. We will continue adding more device manager guides.

Devices enrolled via Zero Touch installation only support Banyan’s Passwordless authentication feature via Banyan Desktop App v.2.1.0+.

In some organizations, Banyan Administrators manage devices used by Local users who do not have Admin privileges on the device. Similarly, some organizations must deploy and manage devices having users with Guest accounts where the Guest’s profile is deleted when the user logs out.

For these scenarios, Banyan recommends deploying the Desktop App (MacOS and Windows) via a Device Manager via Zero Touch installation. The IT Admin packages the Banyan Desktop App to be pushed down and installed silently via their Device Manager; the end user does not need device administrator privileges for the install to complete successfully.

With Zero Touch mode, the following steps can be automated:

  • Silent installation of the Banyan Desktop App
  • Device registration
  • Setting device ownership type
  • Creating a task to launch the Desktop App on bootup
Admin Setup

You have to first perform the following steps as an Administrator on the Device:

1. Install the Desktop App

2. Place the mdm-config.json file in the device’s Global Config Directory, paying particular attention to the following flags required to enable zero touch mode:

  • mdm_invite_code - Obtained from Command Center (Settings > App Deployment > Invite Code)
  • mdm_present - Set to true
  • mdm_vendor_name - Set to your Device Manager name

You can optionally set other flags as well, based on the user experience you wish to deliver to your end-users, such as:

  • mdm_device_ownership
  • mdm_hide_services
  • mdm_hide_on_start

3. Launch the Desktop App via the command line, passing in the secret Deployment Key you obtained from Command Center (Settings > App Deployment > Zero Touch Deployment) as a command line flag.

For example, on Windows, you would run:

'C:\Program Files\Banyan\Banyan.exe' --staged-deploy-key=example_deploy_key_from_banyan_command_center

The Desktop App will run the setup flow for Zero Touch installation, register with your organization, and procure a Device Certificate for that device. You will be able to see the device details under the Devices tab.

4. Configure the device so that Banyan Desktop App is launched automatically when a new user logs into the device.

User Setup

Now, when a new user logs into the device, the Desktop App will be launched automatically and will run silently in the background. The Device Certificate will also be associated with this user.

When the user accesses a Banyan-secured service, the Device Certificate will, transparently, be used to authenticate the device and establish device trust.

You will also be able to see the user associated with the device in the Banyan Command Center.

Unregister Devices and Remove Staging Setup

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

  • unregister - Run as the end user to remove a staged registration.
  • remove-staging - Run as an admin to remove the global staged files.

Device TrustScore Integration with Workspace ONE UEM

For organizations that have Workspace ONE UEM as their Device Manager and already integrated Banyan via the Workspace ONE UEM API, the Banyan Desktop App will capture all features it normally does, and, in addition, uses the Workspace ONE UEM API to check for Device Compliance. If Workspace ONE UEM reports the device as compliant, Banyan calculates Device TrustScore based on device features captured by the Desktop App. If Workspace ONE UEM reports the device as not compliant, the Device TrustScore is set to 0.

Desktop App AutoUpdate

To minimize the operational burden on IT teams, the Banyan Desktop App has native AutoUpdate capabilities. Once the Desktop App is installed, you do not have to worry about keeping it updated. When a new version of the Desktop App is released, the user is prompted to update and can do so with a single button click.

You can disable the automatic update feature by setting the mdm_disable_auto_update flag to true.


Current Limitations

Currently, there are few known limitations when the Banyan Desktop App is deployed using a Device Manager:

  • When there are multiple users using the same device, only one user at a time can be actively running the Desktop App for it to function as expected.
  • If Admin privileges are not provided when the user registers the device, Device Certificate suppression scripts will not be installed. Then, when the user accesses a Banyan-secured service they will see the Device Certificate prompt once per browser session. However, for a completely silent installation, leverage our Zero Touch installation capability.

We are actively working on resolving these in future releases.


Last modified: Jun 17, 2021