• Overview
• Setup
  • A. Enable Workspace ONE UEM API Access
    • A1. In the Workspace ONE UEM Console, create a Role for the Banyan API
    • A2. In the Workspace ONE UEM Console, create an Admin account
    • A3. In the Workspace ONE UEM Console, create an API key
    • A4. In the Banyan Command Center, save the Workspace ONE UEM credentials
    • A5. Specify MDM parameters in the Desktop App mdm-config.json file
  • B. Trust Device Certificates issued by your Enterprise Certificate Authority
    • B1. Gather the full certificate chain of the Root CA used to sign device certificates
    • B2. In the Workspace ONE UEM Console, get the format used for the CN field
    • B3. In the Banyan Command Center, update the Device Certificate Configuration
• Additional Notes
  • MDM Fail Open/Closed
  • Trust Scoring Integration

This article covers how to integrate with Workspace ONE UEM for Device Identity (using pre-installed certificates) and for Enhanced Trust Scoring via APIs. For detailed instructions on how to distribute the Banyan desktop app to your entire fleet of managed devices, visit our article on distributing the desktop app.

Overview

Workspace ONE UEM configures and manages endpoints (desktop and mobile) in your enterprise. Banyan integrates with your organization’s Workspace ONE UEM account to ensure only approved devices can access Banyan-secured services.

There are two main parts to configuring the Workspace ONE UEM-Banyan integration. Part-A enables API access to gather data for Enhanced Trust Scoring. Part-B enables Device Identity using pre-installed device certs. You may complete either or both of these steps.

• A. Enable Workspace ONE UEM API access so Banyan can gather device information from Workspace ONE UEM.

• B. Trust Device Certificates issued by your Enterprise Certificate Authority so Banyan can use device certificates on your Workspace ONE UEM-managed devices.

With these configurations in place, you can use Workspace ONE UEM to deploy Banyan-trust device certs and configure Enhanced Trust Scoring.

Setup

A. Enable Workspace ONE UEM API Access

Workspace ONE UEM API access is used by Banyan to gather device information.

A1. In the Workspace ONE UEM Console, create a Role for the Banyan API

• Navigate from Accounts > Administrators > Roles.
• Create a new Role.
• Grant access to the device APIs: REST - Devices - REST APIs for device management.

A2. In the Workspace ONE UEM Console, create an Admin account

• Navigate from Accounts > Administrators > List View.
• Select Add, and choose Add Admin.
• Add this admin to the Role you created previously (in Step A1).
• In the API tab, ensure Basic Auth is selected.

A3. In the Workspace ONE UEM Console, create an API key

• Navigate from Groups & Settings > All Settings > System > Advanced > API > REST API.
• Select Add to generate a new API key (also known as an Workspace ONE UEM Tenant Code).

A4. In the Banyan Command Center, save the Workspace ONE UEM credentials

• Navigate from Settings > Banyan Client > Device Manager.
• Set Device Manager Name to Workspace ONE UEM.
• Enter the API Host URL, Workspace ONE UEM Username and Password, and API Key.
• Select a Fail Mode according to your business needs* (see MDM Fail Open/Closed for more information).
• Select Update API Config to save the Workspace ONE UEM credentials.

A5. Specify MDM parameters in the Desktop App mdm-config.json file

If you are using Workspace ONE UEM to distribute the Banyan desktop app, you need to set a few additional parameters in the mdm-config.json file so that Banyan’s Trust Scoring engine can correlate data from devices running the desktop app with the data in Workspace ONE UEM:

• Set mdm_present to true to inform Banyan that the device is managed by a Device Manager; this is for use in Device Trust Scoring.

Note: If the mdm_present value is set to true, you must set the mdm_vendor_udid parameter as well.

• Set mdm_vendor_name to airwatch to inform Banyan that the device is managed by Workspace ONE UEM; this is for use in Device Trust Scoring.
• Set mdm_vendor_udid to the device’s specific Workspace ONE UEM UDID to associate the device with its Workspace ONE UEM compliance factors; this is for use in Device Trust Scoring. Check a device’s Workspace ONE UEM UDID by logging into your Workspace ONE UEM Console, locating a specific device, and reviewing the Device Details summary.

See the note on Trust Integration for more information on how Banyan’s Trust Scoring engine uses device detail information from Workspace One UEM.

---

B. Trust Device Certificates issued by your Enterprise Certificate Authority

Your organization may already use Workspace ONE UEM to deploy device certificates on all managed devices using an Enterprise Certificate Authority, such as Symantec. Banyan can seamlessly integrate with certificates issued by those CAs and deployed via Workspace ONE UEM.

B1. Gather the full certificate chain of the Root CA used to sign device certificates

B2. In the Workspace ONE UEM Console, get the format used for the CN field

B3. In the Banyan Command Center, update the Device Certificate Configuration

• Enter the Cert - Root CA and Cert - Common Name.
• Select Update Device Cert.

---

Additional Notes

MDM Fail Open/Closed

When entering the Workspace ONE UEM credentials in the Banyan Command Center, you are given the option to select a Fail Mode when Workspace ONE UEM is offline:

• If set to FAIL CLOSED, Banyan redirects the end-user to an HTML error page.
• If set to FAIL OPEN, Banyan issues the end-user a user-claims-only token. The end-user can access any Service where the Policy doesn’t mandate a trusted device or TrustScore requirements.

Trust Scoring Integration

Banyan uses the Workspace ONE UEM Devices API (/api/mdm/devices?searchby=Serialnumber&id=%s) to query device data to use in its Trust Scoring engine, and looks for the Compliance attribute associated with a given device.

If the Compliance attribute for a device is Non-Compliant, the device’s Trust Level is dropped to Always Deny.

If the Compliance attribute for a device is a value other than Non-Compliant (such as Compliant, Pending Compliance Check, Not Available, Unknown, etc.), the device’s Trust Level is impacted based on whether the Banyan app is installed or not:

• Scenario 1. Banyan app is installed, and its mdm-config.json is set for Banyan’s Trust Scoring engine to correlate data using the Workspace ONE UEM API, as in Setup A-5 above. If the Banyan app is installed and the Compliance attribute for a device is a value other than Non-Compliant, the device’s Trust Level is not impacted. In this scenario, Banyan also uses smart caching rules to account for connectivity issues with the API. If the Workspace ONE UEM Devices API returns a 50x error, Banyan’s Trust Scoring engine will look in its internal Device Database for the last compliance status recorded and use that in the device’s TrustScore computation.

• Scenario 2. Banyan app is not installed; instead, the device can be identified by the certificate issued by an Enterprise CA, as in Setup B above. If the Banyan app is not installed, and if (and only if) the Compliance attribute for a device is Compliant, the device’s Trust Level will be set to the maximum value, High.

---

Can’t find what you’re looking for?

We’re happy to help. Contact our team.