Distribute the Banyan Desktop App using your Device Manager
- Updated on Jan 25, 2022
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 totrue
mdm_vendor_name
- Set to your Device Manager namemdm_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.