Guides
ProductDeveloperPartnerPersonal
Guides
ProductDeveloperPartnerPersonal

macOS Mobile Device Management

The Managed Preferences feature enables you to manage Umbrella roaming clients on macOS devices through Mobile Device Management (MDM). You can use Managed Preferences to deploy the Umbrella Roaming Client to an organization, change the Roaming Client to another organization, and add a user identity. When you add a user identity through a Managed Preference, the user identity is available for use in an Umbrella policy and the identity maps to traffic that appears in Umbrella reports.

If you install the Roaming Client without the OrgInfo.plist, the Roaming Client enters the Waiting state. The Roaming Client waits to register the information from an OrgInfo.plist or com.cisco.umbrella.dnscrypt.plist from Managed Preferences. If both OrgInfo.plist and com.cisco.umbrella.dnscrypt.plist from Managed Preferences are present, Managed Preferences takes priority.

To ensure that the roaming client registers with a new Umbrella organization, push a new Managed Preference plist. If you previously installed the roaming client with an OrgInfo.plist, and if a Managed Preference is present, you can use a Managed Preference.

Table of Contents

Prerequisites

  • macOS device
  • Umbrella Roaming Client 2.2.26 or later—Required to register to an organization
  • Cisco Secure Client 5.0, AnyConnect Umbrella Roaming Security Module 4.10.06, or Umbrella Roaming Client 3.0.22 or later—Required to add a user identity
  • Mobile Device Management (MDM) system

Register to an Organization

  1. Download the Umbrella Roaming Client installer for macOS from Umbrella.
  2. Copy the contents of OrgInfo.plist from the installer package into a new file named com.cisco.umbrella.dnscrypt.plist.
  3. (Optional) Remove the OrgInfo.plist file from the installer package. If OrgInfo.plist is present in the .pkg, the client initially registers with the organization defined in the OrgInfo.plist file.
  4. Deploy the .pkg file to the macOS devices.
  5. Using MDM, push com.cisco.umbrella.dnscrypt.plist to /Library/Managed Preferences.
  6. Verify that the client enters encrypted mode.
  7. If your production instance is using a higher version than your test instance, run the following command to prevent automatic updates:
    sudo touch /Library/Application\ Support/OpenDNS\ Roaming\Client/skip_upgrades.flag
  8. Verify that the client is using the correct policy.

In the following dig command, orgid is 2. The orgid field matches the organization in the com.cisco.umbrella.dnscrypt.plist file. The sample request is sent through 127.0.0.1 which indicates that dnscrypt is in use.

sh-3.2# dig -t txt debug.opendns.com
; <<>> DiG 9.10.6 <<>> -t txt debug.opendns.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 26537
;; flags: qr rd ra; QUERY: 1, ANSWER: 18, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION: ;debug.opendns.com.
IN TXT
;; ANSWER SECTION:
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com. 1C0000000007000000003DFF000000000000000"
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com. 4ef2a24bf57bb1a93c2875319f057dc23ac6de5b"
debug.opendns.com. 0 debug.opendns.com. 0 debug.opendns.com. 0 debug.opendns.com. 0
IN TXT IN TXT IN TXT IN TXT
;; Query time: 9 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Nov 18 13:32:25 PST 2019 ;; MSG SIZE rcvd: 973

Change Organizations

  1. Replace the existing /Library/Managed Preferences/com.cisco.umbrella.dnscrypt.plist file with a new plist from the new organization.
  2. Verify that the following lines appear in the console.
default 13:35:05.042427-0800 dns-updater [INFO] A new configuration has been detected.
default 13:35:05.042639-0800 dns-updater [INFO] Attempting to remove /Library/ Application Support/OpenDNS Roaming Client/Updater.plist and /Library/Application Support/ OpenDNS Roaming Client/RoamingProfile.plist
default 13:35:05.043443-0800 dns-updater [DEBUG] Restoring default configuration
  1. Wait for the client to register and sync under the new organization, and for the client to enter encrypted mode.
  2. Perform the following dig command, paying attention to the value of orgid. When the orgid matches the new target org, the client is successfully registered under the new org.
sh-3.2# dig -t txt debug.opendns.com
; <<>> DiG 9.10.6 <<>> -t txt debug.opendns.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 23026
;; flags: qr rd ra; QUERY: 1, ANSWER: 18, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION: ;debug.opendns.com.
IN TXT
;; ANSWER SECTION:
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com. 1800000000000000000039FD000170000000000"
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com.
debug.opendns.com. 4ef2a24bf57bb1a93c2875319f057dc23ac6de5b"
debug.opendns.com. 0 debug.opendns.com. 0 debug.opendns.com. 0 debug.opendns.com. 0
IN TXT IN TXT IN TXT IN TXT
;; Query time: 8 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Nov 18 13:38:42 PST 2019 ;; MSG SIZE rcvd: 980
0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT
"server m45.pao"
"device 01010CADAB487021" "remoteip 10.128.156.34" "flags 400B6 0 184040
"originid 329664062" "orgid 856682" "orgflags A6" "actype 0"
"bundle 177932"
"source 171.68.244.70:59103" "dnscrypt enabled (716D496B684B3766)" "name opendnscache"
"version 2.75-1199"
"commit
"bits 64"
"release type release"
"deploy type production"
"compile time Nov 6 2019 13:34:46"
0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT 0 IN TXT

Add a User Identity

Through MDM, you can use Managed Preferences to push user information from a macOS device to Umbrella.

Add a user identity in Managed Preferences.

  1. Provision user identities to Umbrella from a supported identity source, for example: Active Directory (AD), Azure AD, or Okta. For more information, see Identity Integrations.
  2. Create a com.cisco.umbrella.client.plist file similar to the following example. Provide a specific username or variable supported by the MDM.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>UPN</key>
    <string>[email protected]</string>
  </dict>
</plist>
  1. Use MDM to push com.cisco.umbrella.client.plist to /Library/ManagedPreferences.
  2. To verify that Umbrella detects the user identity information from the macOS device, send a query for a domain. If Umbrella’s DNS resolvers receive and process the request from the device, the Umbrella Activity Search report includes the information about the request for the user identity. For more information, see Identity Support for the Roaming Client.

Remote Logging and Diagnostics < macOS Mobile Device Management

Updated 12 months ago