Deploying Viscosity on macOS using Jamf Now
Jamf is a popular deployment suite of device management software that can be used for managing macOS software deployment in an enterprise environment. It allows macOS administrators to manage installing and uninstalling software on end-user machines. This includes handing mass installation of software.
This article details how to deploy and manage Viscosity installations using Jamf Now. Please note that this differs from Jamf Pro. Items covered include creating a Viscosity package suitable for deployment, how to optionally include pre-configured connections and settings, and how to optionally bundle in Viscosity license data.
This guide assumes that you already have a operational Jamf Now setup. If this is not the case, or you'd like to create a new setup for testing, please refer to the Jamf Now documentation detailing how to create a new Jamf Now setup before proceeding.
To get started you will need the following requirements:
- A copy of the latest version of Viscosity (version 1.8.1 or higher)
- A working Jamf Now setup on the Plus plan
- An Apple issued Developer ID Installer certificate
- A copy of our viscosity_managed_installer_1.2.tgz template installer package
- Packages, a free installer editor for macOS
To deploy packages, Jamf Now requires that you're on the "Plus" plan, rather than the "Standard" plan. It's possible to upgrade to the Plus plan from the Account section.
In addition, Jamf Now requires that packages being deployed be code-signed using an Apple issued Developer ID Installer certificate. For information on how to obtain one please see the Signing the Installer section at Bundling Viscosity with VPN Connections & Preferences (Mac). Alternatively, Jamf Pro does not require that packages be signed.
VPN Connection Requirements
Viscosity supports a wide range of VPN configuration types and authentication methods. Some of these setups may require user-specific authentication files, or require additional software, both of which can complicate deployment using Jamf Now. If you don't intend on including any pre-configured VPN connections alongside Viscosity please skip ahead to the next section.
Please refer to the below items to see if any apply to your OpenVPN setup:
- User-Specific Certificate/Key Files: If your OpenVPN setup requires that each user's connection be configured with a unique certificate/key, then it's not recommended to use Jamf Now for VPN connection deployment. Instead, consider using the instructions here to deploy the Viscosity application and settings/license data using Jamf Now, and then have the user download their VPN connection separately (for example from a web portal) or use Viscosity's Import From Server feature. Your organisation could also upgrade to Jamf Pro, which is capable of per-user file/settings deployment.
An alternative is to change your OpenVPN setup to no longer rely on unique per-user certificate/key files. For example, you could instead use a shared certificate/key file for all users, along with a username and password. However from a security standpoint we strongly recommend against relying solely a username and password for authentication.
We recommend username/password authentication be combined with an additional method such as a One Time Password (OTP), two-factor authentication prompt (for example Google Authenticator, Duo Security, or Authy code), or token device (U2F device, PKCS#11 token, etc.). Please see our Knowledge Base for some server setup examples.
- PKCS#11 Tokens and Smartcards: If your VPN connection uses a PKCS#11 device for authentication, it's highly likely it requires a PKCS#11 driver is installed (for example OpenSC). If this is not already installed as part of the computer's base image, then it's necessary to also have Jamf Now install it. Packaging the driver is beyond the scope of this guide, however typically you'll want to repackage the PKCS#11 driver installer, as well as the Viscosity installer created as part of this guide, together as a metapackage.
- TAP Connections: The vast majority of OpenVPN connections are TUN (Layer 3) based. However in the event you are using a TAP (Layer 2) based OpenVPN setup in a managed environment, it's worth pre-approving Viscosity's TAP driver. For more information please refer to Apple's User-Approved Kernel Extension Loading article.
Creating a Package
Before Viscosity can be added to Jamf Now, a installer package must be created. These steps are detailed below:
- Download and extract the managed template installer package linked in the requirements section above.
- Create a bundled version of Viscosity by following the instructions in the Bundling Viscosity with VPN Connections & Preferences (Mac) guide. However instead of using the template installer package linked in that guide, use the managed template installer package downloaded in the previous step.
If you wish to have Viscosity updates managed by Jamf Now as well, Viscosity's "Automatically check for updates" option should be turned off before bundling in settings.
- Jamf Now requires that installer packages are signed using an Apple issued Developer ID Installer certificate. If you did not already sign the installer as part of the instructions linked above, please follow the Signing the Installer instructions to sign the installer now.
You should now have a signed installer ready for deployment.
To deploy Viscosity to your managed machines you will first need to upload it to your Jamf Now account. This can be done like so:
- Log into your Jamf Now account.
- Click on "Apps" in the side menu, and then click the "Add an App" button.
- Select the "Upload Your App" option, click Browse, and select your bundled Viscosity installer package. Your bundled installer should begin uploading.
- Once the upload has finished, enter "Viscosity" as the App Name and click done.
- Viscosity should now appear in your list of available apps:
Now that your bundled version of Viscosity has been added, it can be deployed to machines like so:
- Click on "Blueprints" in the side menu (if you wish to deploy to a single device, select "Devices" instead).
- Click on the Blueprint you wish to add Viscosity too.
- Click on the "Apps" sub-menu, and click the "Add an App" button.
- Select Viscosity and click "Add App".
- Viscosity will start to be silently deployed to machines using this Blueprint. Viscosity will be available in the Applications folder on those machines once deployment is complete.
Starting Viscosity at Login
If your package includes the Start Viscosity at Login setting using the instructions in the bundling article, the managed installer package will automatically install a Launch Agent to start Viscosity at login for all users.
This differs from Viscosity's standard "Start Viscosity at Login" option, which normally installs Viscosity as a Login Item for just a single user. This means that on a managed install the "Start Viscosity at Login" option in Viscosity's Preferences window will have no effect: Viscosity will always start at login. If this behaviour isn't desired, the "StartAtLogin" setting should be removed.
To update an existing installation of Viscosity, simply create a new package using the same steps as above, add it to Jamf Now, and deploy it. The Viscosity application will be replaced with the new one, and bundled settings/connections updated. Connections update behaviour depends on the connection deployment folder used (normal, overwrite, or append).
To uninstall Viscosity, first remove the Viscosity application from the Applications directory. Then run the "postuninstall.sh" script found under the Scripts directory template installer package to remove any bundled data and Viscosity's helper.
Please note that connections and preferences (including stored license data) will likely be still remain in each user's profile directory that has run Viscosity. These files can be removed manually.