Cisco Secure Client + Umbrella, Part 1: Ingredients

Cisco is spinning down the legacy OpenDNS Umbrella Roaming Client 3.x app in April 2024 and requiring organizations to switch over to Cisco Secure Client 5.x with an Umbrella Module instead. In some ways, the transition is relatively straightforward, and in other ways, it's a labyrinthian nightmare. For every convenience (running the 5.x installer cleans up/deletes the old app) there are a handful of perplexing challenges. Let's start by taking a look at what you need to install the new app to begin with.

Let's review Cisco's documentation for this. From the Cisco portal, you'll want to download your installer, delivered as a DMG. You'll also need to download an OrgInfo.json file, labeled in the Cisco portal as a "Module Profile".

OrgInfo.json

First, let's look at that OrgInfo.json file. Open it up and you'll see something like this:

{
    "organizationId" : "12345678",
    "fingerprint" : "1234567890abcdefghijklmnop",
    "userId" : "87654321"
}

This file is not only unique per organization but per Cisco user account. Bear this in mind if you have multiple users sourcing these files for deployment, as they may have the same organizationId value but different fingerprint and userId values.

DMG installer

As you sift through the available installers, look for an item named "AnyConnect Pre-Deployment Package (Mac OS)", or similar. The actual file will be named "cisco-secure-client-macos-5.0.00556-predeploy-k9.dmg", but with updated version numbers embedded in the name.

ACTransforms.xml

Inside the DMG will be a Profiles directory, and this XML file hangs out inside of it. The file looks like this by default:

<!-- Optional AnyConnect installer settings are provided below. Uncomment the setting(s) to perform optional action(s) at install time.  -->
<Transforms>
    <!-- <DisableVPN>true</DisableVPN> -->
    <!-- <DisableCustomerExperienceFeedback>true</DisableCustomerExperienceFeedback> -->
</Transforms>

You can see each line is commented out, with the comments beginning with <!-- and ending with -->. If you wanted to un-comment either of the two Transforms, you'd remove both bookends. In practice, the most common use case would be to uncomment the DisableVPN setting if you plan on deploying Cisco Secure Client solely for the Umbrella module and do not want the VPN components installed.

If you plan on modifying this file, you'll need to convert the DMG from read-only to read/write first:

hdiutil convert path/to/the/cisco.dmg -format UDRW -o /path/to/output/your/newReadWriteDMG.dmg

Choices.xml

This is the last file you'll need to customize a barebones installation of Cisco Secure Client with the Umbrella module, and the only component you'll need to make from scratch. In simple terms, this file is going to detail which optional checkboxes in the installer you plan to run when you deploy the app via your MDM of choice. The Choices.xml file you generate from the installer PKG will contain an array of dictionaries. The dictionaries will come in sets of three per module and will look something like this:

<dict>
  <key>attributeSetting</key>
  <true/>
  <key>choiceAttribute</key>
  <string>visible</string>
  <key>choiceIdentifier</key>
  <string>choice_secure_umbrella</string>
</dict>

<dict>
  <key>attributeSetting</key>
  <false/>
  <key>choiceAttribute</key>
  <string>enabled</string>
  <key>choiceIdentifier</key>
  <string>choice_secure_umbrella</string>
</dict>

<dict>
  <key>attributeSetting</key>
  <integer>1</integer>
  <key>choiceAttribute</key>
  <string>selected</string>
  <key>choiceIdentifier</key>
  <string>choice_secure_umbrella</string>
</dict>

We have 3 separate dictionaries, each with three key pairs, each sharing the same choiceIdentifier. The choiceIdentifier tells us which Cisco module we're controlling - in this example, we're looking at the secure_umbrella module.

1. attributeSetting - 0 means unchecked, 1 means checked. This is the most important value and what we'll be using to control which modules get installed.
2. choiceAttribute - there will be multiple options here, some include visible, enabled, or selected. Oddly enough, for this exercise, we're going to leave it alone.
3. choiceIdentifier - this lets you know which checkbox you're editing

In short, you'll go through your Choices.xml file and check or uncheck modules by setting the attributeSetting to 1 or 0 to ensure you install all the parts you want, and none you don't. This is incredibly important because of the sheer number of optional modules Cisco Secure Client includes. Most notably, there's now a Duo Device Health application bundled inside the installer that actually requires pre-existing certificates or more complex installation arguments if you don't disable it here.

To generate this file, you can use this command:

installer ‑showChoicesXML ‑pkg /path/to/CSC_Installer.pkg ‑target / > ~/Desktop/csc_choices.xml

Direct the command to the installation package for Cisco Secure client, not the DMG. This will then place a file called "csc_choices.xml" on your desktop for you to modify as you see fit.

Next time, we'll look at how these components fit together to create an installation smart software or policy item. There's an interesting balance here of elements you can generate programmatically using variables inside your installer vs ones you should just prepare and upload each time.