This document is in early preview. If you have any questions or concerns please reach out to your Customer Success Representative.
This article goes over some information that may be useful during the configuration of your Zero-Touch script to understand what options you should choose to fit your environment's needs. In addition, we highlight some situations to be aware of to keep your deployment as smooth as possible!
- Ensure you are familiar with your deployment instructions found here by reading through your MDM guide. Each MDM may vary in deployment options. If you have any questions which are not answered in our documentation, please reach out to your account representative.
- Additional configuration information can be found on our Gitlab Repo.
Zero-Touch Break Down
In this section, we will review some common parameters and some of Banyan's general recommendations for deploying the Zero-Touch Script to quickly and easily deploy Banyan to your Fleet.
Please note: If you need configuration instructions, access to the scripts, or other information regarding specific MDMs. Please refer to the Prerequisites or Further Reading sections of this article.
The deployment information section of the script contains 3 Parameters. Those are INVITE_CODE, DEPLOYMENT_KEY, and APP_VERSION.
The INVITE_CODE is configurable in the admin console of Banyan. However, this code is expected to be communicated to users in your organization. This code does not inherently grant any level of access as user credentials or a Deployment Key is still needed to register the app with your Organization. The Invite Code will also be stored in plain text within the mdm-config.json within the Global Configuration Directory on user devices.
Some Admins may choose to obfuscate this code, however, it is important to know that if you decide to change the Invite Code. You will need to update your Zero-Touch scripts accordingly to prevent failed deployments of the Banyan App.
The DEPLOYMENT_KEY, in contrast to the INVITE_CODE, is meant to be kept secret. This is the key required by your Banyan Organization to deploy and register a device without user credentials. This secret key is not stored on the user device and is only used as a variable when this script is run in the background by your MDM. Please do not hand this Deployment Key out to your users. If you feel this key is out in the wild. You can revoke the old key and get a new one from the App Deployment settings in your Banyan Console.
The final variable in this section is the APP_VERSION. This parameter is how admins choose which version of the app is deployed to users. If you would like to always deploy the latest version, you may set this to be blank like so:
However, if there is a specific version you would like to set, you may use the version in the following format as seen here:
You can always find the latest list of App Versions in our Component Changelog.
Device Registration and Banyan App Configuration
The Device Registration and Configuration section of the app contains parameters that the app will use to configure itself during the Zero-Touch process.
DEVICE_OWNSERHIP allows admins to pre-configure the Device Ownership selection to user devices. This is especially useful for managing access via Banyan Roles between fleets of devices owned by the company and BOYD fleets. You may use “C” for corporate-owned, “E” for employee-owned, “S” for corporate-shared, and “O” for others.
CA_CERTS_PREINSTALLED is a parameter used to tell the Banyan App to skip installing the CA certificate when the app is first run. Historically, the app used to install this certificate into the system store of the device which prompted users for Administrator credentials or access depending on the OS. In modern versions of the app (3.0.0+) we fall back to install these certificates into the user certificate store if admin credentials are required in an attempt to reduce user interaction while using the app for the first time.
However, there may be a use case for installing this certificate into a system store for situations such as multi-user systems or third-party tools. You may push the Banyan CA certificate for your Banyan ORG via MDM. If you choose to do so you will want to set the CA_CERTS_PREINSTALLED parameter to true.
The next pre-configured parameter in the Zero-Touch script is SKIP_CERT_SUPPRESSION. This parameter is used to skip the prompt suppression flags on commands ran when the app is launched by a user for the first time. These prompts are for the user to install the Managed-Device certificate into the user certificate store on the device. In most cases outside of testing, you will want to leave this as false to prevent extra user interaction to get started with Banyan.
VENDOR_NAME is used to define the name of your MDM to better organize and report on your fleet of devices. This should be set to the name of the MDM you are deploying with much like in the following example:
This vendor name will appear in device reports that you pull from the Banyan Console to help admins better understand the source of the deployment in multi-MDM environments.
HIDE_SERVICES is used for use cases where Banyan users will not need to authenticate into the app to access on-prem of IaaS-based services such as Hosted Websites, Infrastructure Services, and Service Tunnels. Most Banyan use cases will want to leave this as false, but for SaaS-only implementations of Banyan, this can be useful to prevent users from getting lost in the app's service UI while trying to log into the IDP and gain access to SaaS Apps.
The next parameter on our script is DISABLE_QUIT. This parameter can be very useful for admins who do not want the Banyan app to be able to be quit on user devices. If a user does end the process the app will immediately be re-opened when this parameter is set to true. This can be especially useful for those more critical users whose admins will want to ensure they have the latest reporting from the device.
START_AT_BOOT when configured to true, will start the app during the device's start process when the user logs in. This is commonly enabled as it prevents the user from having to open the app each day which can support a better posture for continuously capturing device factors from your users. If you do not enable this parameter, you may run into users getting expired trust scores after the trust score timeout period. This can cause issues come audit time as users who may not access Banyan services on a regular basis will need to be informed to launch the Banyan app to update their trustscore.
The HIDE_ON_START parameter is used to prevent the Banyan App's UI element from popping up on the user's screen when the Banyan Application is launched. This works well with the START_AT_BOOT parameter to prevent extra clutter from appearing on your user's devices during start-up. For SaaS-only implementations of Banyan this can significantly improve the user experience so Banyan acts in a way where the user will never know it's there unless they run into an issue with their factors.
DISABLE_AUTO_UPDATE in version 3.3.0 and later versions of the app on Windows. The Banyan App will automatically upgrade when the app gets shut down. This can be helpful for admins who do not want to control versioning themselves. For MACOS, this functionality will be expanded at a later date, but at current, the user will get a notification to update if this parameter is set to true.
Last but certainly not least is MDM_PRESENT. When this parameter is set to true, the app will tell the Banyan Command Center that it is managed by an MDM during registration. This is particularly useful when configuring access controls within Banyan to only allow devices that are managed by your MDM. This will also be reflected in your device reporting as a flag for if the device is managed or unmanaged by an MDM.
User Information for Device Certificate
This section of the Zero-Touch script is where you will set up parameters the app may use to gather information about users on the device!
The MULTI_USER parameter is used to tell the Zero-Touch install script if the target device is shared between multiple users. If this flag is set to true, the script will not try to gather user information from the MDM or Active Directory. This user information will be retrieved the first time each user uses the Banyan App.
On Windows, the user information locations are built into the script and retrieved from the registry information for its joining to Active Directory. On MACOS you will have 3 additional parameters. We cover those in the Considerations section of this article below, as MDM-specific configurations will come into play.
The next set of parameters we will outline here is those which are available to use but are not in the deployment script by default. You may always add these parameters and their values into the script like showing in the following example for mdm_reporting interval:
When adding parameters to the MACOS script, please ensure you follow the JSON syntax by adding a trailing comma to any parameters preceding another line as shown in the image above.
The first parameter we will cover which is not set by default in the Zero-Touch script is the mdm_reporting_interval. This parameter sets in minutes between 15 and 60, if not set this defaults to 60. This is the amount of time it takes for the app to report its trust score. For example, if you set this to 15. Every 15 minutes the app will report its trustscore to the Banyan Components.
mdm_login_token_prompt_time is the second parameter on our list which is not pre-configured in the Zero-Touch script. This notes the amount of time in minutes in which the app will give the user a notification their app is about to expire. By default, this is 120 minutes at which time the user will get a notification in the Banyan app that their session will expire soon.
Finally, the mdm_vendor_udid is used for Device Manager integrations with Banyan. The UDID in this case is used to match the device the script was deployed to, to the ID of the device in the MDM too ensure it is registered. Currently, we only support this integration with Airwatch, which you can find further set-up instructions on our documentation site.
Using User Info to Deploy a Device Certificate on MACOS
Unlike the Windows version of the Zero-Touch scripts, by default, the Zero Touch script has the user information set to null. This gathers user information deployed by your MDM which is stored on the device. Each MDM may have different locations or file names for where this information. In some circumstances, this information may not be deployed by your MDM correctly or at all. If you are concerned if this information is deployed to your user's devices or how to configure it. You will need to refer to your MDM documentation for Zero-Touch.
To enable this feature on MACOS you will want to add the USERINFO_PATH, USERINFO_USER_VAR, and USERINFO_EMAIL_VAR values to your deployment script. The USERINFO_PATH variable will be the location of the file in which the MDM stores the user information. The USERINFO_USER_VAR and USERINFO_EMAIL_VAR will need to match the scheme configured by your MDM.
The example below is for JAMF Pro from the JAMF documentation for Zero-Touch. Note the variable names "deploy_email" and "deploy_user". These will match the USERINFO_USER_VAR and USERINFO_EMAIL_VAR respectfully and should be configured to those names.
This will look like the following in your script configuration:
Many MDMs will have variations of this configuration. If you are having trouble figuring out what parameters to use here. Reach out to your Customer Success Engineer for additional support!
When to Deploy
The Zero-Touch script should be deployed to a device that does not have a registered Banyan client. Doing so may update the registration to new parameters but can cause instability in the app which may result in issues at the time of deployment or further down the line.
To avoid this the app comes packaged with a full delete script which can be found under the AppInstallDirectory > Resources > Conf which can be used to clean up old Banyan installs with the exception of the certificate. However, deploying this script has its own pitfalls as well. Thus manual deregistration of the Banyan app is the best route to follow here for small numbers of users.
If you find the need to redeploy at scale. Please contact your Customer Success Engineer to get additional assistance as recommendations will need to be tailored to each situation.
- Zero-Touch Install Scripts
- Distribute Desktop App
- Jamf Pro
- Workspace ONE UEM - Device Identity & Enhanced Trust Scoring
- Device Identity Using Pre-Installed Device Certs