Distribute the Banyan Desktop App using your Device Manager

  • Updated on Jan 25, 2022

This article describes features that are only available in the Banyan Enterprise edition.

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 Description
mdm_invite_code string Registration Provide the Invite Code needed to register a device to your organization. Obtain from Banyan 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 TrustScoring Set time interval (in minutes) for how often Desktop App reports device features
mdm_present boolean TrustScoring Inform Banyan that the device is managed by a Device Manager
mdm_vendor_name string TrustScoring Inform Banyan which Device Manager is managing the device
mdm_vendor_udid string TrustScoring Inform Banyan 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

Zero Touch Installation

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

By default, devices enrolled using Zero Touch installation will not support Banyan’s passwordless authentication. To enable passwordless, please contact Banyan Support.

In many organizations, Banyan administrators want to install the Banyan app without any user involvement at all. This is particularly useful for devices used by local users who do not have admin privileges. For such scenarios, Banyan recommends deploying the Desktop App (MacOS and Windows) via a Device Manager via a process we call “Zero Touch Installation”. The IT Admin packages the Banyan Desktop App to be installed silently via the Device Manager; the end user does not to interact with the Banyan App at all for the install & registration to complete successfully.

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

  • Silent installation of the Banyan Desktop App
  • Device registration
  • Setting device ownership type
  • Starting the Banyan App on login

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
  • mdm_device_ownership - Set to "C" for corporate-owned

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

  • mdm_hide_services
  • mdm_hide_on_start
  • mdm_start_at_boot

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 as admin:

'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.

For example, on Windows, you would run as user:

'C:\Program Files\Banyan\Banyan.exe' --unregister

Then, run as admin:

'C:\Program Files\Banyan\Banyan.exe' --remove-staging

Specifying User Principal Name (UPN) in the Device Certificate

This feature needs to be explicitly enabled for your organization. Please contact Banyan Support to enable.

In the default Zero Touch flow, the Banyan 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 Banyan, their username will automatically be associated with the device.

You can optionally modify the Zero Touch flow to associate a device with a specific user instead of the STAGED USER by setting the mdm-deploy-user and mdm-deploy-email parameters in the mdm-config.json file. Now the device will always be associated with that specified user. In addition, the issued device certificate will contain a User Principal Name (UPN) username in the Subject Alternative Name field.

Zero Touch with macOS Big Sur

With Big Sur, Apple requires administrator privileges to install certificates to the System Keychain. Typically the Banyan App would silently install the root certificate but with the admin privilege requirement, administrators will now need to push the root certificate via their Device Manager.

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

1. Obtain Banyan root certificate from Settings > Advanced Settings > 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

Other Deployment Scenarios

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 Auto Update

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.