[Guide] Zscaler Client Connector Deployment with Workspace ONE UEM for macOS

The Zscaler Client Connector can be configured and deployed with Workspace ONE UEM on Windows devices with a few simple steps. This guide is based on Workspace ONE UEM running version 22.10.0.2 (2210) and deploys Zscaler Client Connector v3.7.0.171 to a macOS computer running Ventura.

Note: Workspace ONE UEM is required for the initial installation only. Zscaler Client Connector upgrades can be managed thereafter from within the Zscaler Client Connector Portal.

High-Level Steps:

  1. Download the Zscaler Client Connector Installer PKG from Zscaler Client Connector Portal
  2. Use the Workspace ONE Admin Assistant tool to generate the installer and metadata (.plist) file
  3. Create an Internal Native App in Workspace ONE UEM and assign to managed MacOS endpoints
  4. Create a macOS Profile in Workspace ONE UEM to install and trust the Zscaler Root CA certificate used for SSL inspection in the System Keychain

Before You Begin:

A few key pieces of information will be required to create the script if SSO support is required:

  • The Zscaler cloud name used for your organization
  • The primary domain used for SAML authentication by your organization

Determine your Zscaler Cloud Name:

If your organization is provisioned on more than one cloud, your users will normally be prompted to select the cloud to which their traffic will be sent during the enrollment process. To avoid this prompt, you can pre-configure the Zscaler Client Connector to automatically connect to the intended cloud automatically by using this installation option.

To determine your cloud name, you can follow the directions in this article

Determine your Primary Authentication Domain:

This installation option allows users to skip the app enrollment page. If SSO is enabled for your organization, users are taken directly to your organization’s SSO login page. If you’ve integrated SSO with the app, users can also skip the SSO login page and are automatically enrolled with the Zscaler service and logged in. If your instance has multiple domains associated with it, use the primary domain for your instance.

Step 1: Download the Zscaler Client Connector installer PKG

When the macOS endpoint executes the script, it will download the Zscaler Client Connector directly from Zscaler using the URL. You can determine the download URL for the Zscaler Client Connector to be deployed by following the below steps:

  1. From the Zscaler Internet Access Admin UI, select Policy from the left navigation bar and click on Zscaler Client Connector Portal in the Mobile section
    image

  2. Select Administration from the top navigation bar in the Zscaler Client Connector Portal and click on Client Connector App Store from the navigation bar on the left

  3. Select the Personal Computer tab and select macOS from the list of Platforms
    image

  4. Click on the Download Link icon from the Download PKG column to download the ZCC Installer PKG file to your Downloads folder

Step 2: Generate the installer package and metadata files

  1. Launch the Workspace ONE Admin Assistant tool and drag the downloaded PKG file into the app. The tool will parse the installer PKG file and create the required .plist, .pkg and image files in ~/Documents/Workspace ONE Admin Assistant folder/

    image

Step 3: Create the Workspace ONE UEM Native Internal App

  1. In the Workspace ONE UEM admin console, select Resources > Apps > Native, click on Add and select Application File to add the app

  2. Upload the installer package file created with the Workspace ONE Admin Assistant tool (not the one you downloaded)

  3. Upload the metadata (plist) file created with the Workspace ONE Admin Assistant tool

  4. Ensure that version numbers matches

  5. Click on Images and upload the PNG icon file created by the Workspace ONE Admin Assistant tool

  6. Click on Scripts and create a Post Install Script and a Post Uninstall Script

When installing, the installer package will create an app file in /Users/Shared/. The Post Install Script will then install the actual Zscaler Client Connector software with install options.

Note: The userDomain and cloudName install options are used in this example to leverage existing desktop SSO. These install options enable Zscaler Client Connector to leverage existing SSO in your environment. Use the values from the Before You Begin section

#!/bin/sh
sudo /Users/Shared/Zscaler-osx-3.7.0.171-installer.app/Contents/MacOS/installbuilder.sh  \
    --mode unattended  --unattendedmodeui none  \
    --userDomain myauthdomain.com  --cloudName zscalerthree
Option Value Description
userDomain myauthdomain.com Your organization’s domain name identified earlier. If your instance has multiple domains associated with it, enter the primary domain for your instance
cloudName zscalerthree The name of the cloud on which your organization is provisioned identified earlier. Example, if your cloud name is zscalertwo.net, you would enter zscalertwo To learn more, see What is my cloud name for ZIA?
mode unattended Install the app in silent mode
unattendedmodeui none Control what is displayed to users when performing an unattended installation

Additional install options are available here

When uninstalling, Workspace ONE UEM will remove the installer package only. The Post Uninstall Script will uninstall the Zscaler Client Connector software itself.

#!/bin/sh
sudo sh /Applications/Zscaler/.Uninstaller.sh
  1. Select the appropriate Assignment Group to use, name the Distribution and click on Save and Publish to start the deployment

Step 4: Install and trust the Zscaler Root CA certificate in macOS system keychain

A Configuration Profile is required to deploy the Zscaler Root CA certificate to managed macOS computers for SSL inspection. If using the default Zscaler certificate, the certificate will need to be downloaded from the Zscaler Internet Access Admin UI and added to a Configuration Profile in Workspace ONE UEM by following the below directions.

Note: Steps 1 and 2 are only applicable when using the Zscaler default certificate. If the organization is using a custom Root CA certificate, use the custom certificate instead.

  1. To download the certificate, login to the Zscaler Internet Access Admin UI, select Policy from the left navigation bar and click on SSL Inspection in the Access Control section
    image

  2. Select Intermediate CA Certificates and click on the pencil icon to the right and cthen click on the Download icon to download the Zscaler Root CA certificate file in a zip archive. Unzip the downloaded Zscaler Root CA certificate archive.

  3. Create a Profile in Workspace ONE UEM by clicking on Resources > Profiles & Baselines > Profiles and then click on Add and select Add Profile

  4. Select Apple macOS > Device Profile and name your Profile. Click on Add next to Credentials, name your certificate (credential) and upload the certificate downloaded at beginning of Step 4.

  5. Assign your Profile to your managed macOS systems to complete the certificate trust process

Zscaler Client Connector will now be downloaded and installed on managed macOS computers along with the Zscaler Root CA certificate. After installation, Zscaler Client Connector will auto-launch and if SSO is enabled, will enroll and login the user without any user intervention.

1 Like