The Umbrella Deployment Documentation Developer Hub

Welcome to the Umbrella Deployment Documentation developer hub. You'll find comprehensive guides and documentation to help you start working with Umbrella Deployment Documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

AnyConnect: Cisco Umbrella Roaming Security Client Administrator Guide

Introduction

The Cisco Umbrella Roaming Security module provides always-on security on any network, anywhere, any time - both on and off your corporate VPN. The Roaming Security module enforces security at the DNS layer to block malware, phishing, and command and control callbacks over any port. Umbrella provides real-time visibility into all internet activity per hostname (and optionally AD username) both on and off your network or VPN. The client may optionally be disabled on network to defer to on network settings.

The Roaming Security module can replace your existing Umbrella roaming client if you already have AnyConnect configured. The roaming module allows for full update control, and an option to disable automatically behind a full tunnel VPN connection.

For more information about this solution, watch Cisco Product Manager Adam Winn discuss the solution here.

Important

The Roaming Security module requires a subscription to either Cisco Umbrella Roaming service or Cisco Umbrella services (Professional, Insights, Platform, or MSP).

The Roaming Security module is available in a limited roaming security only package which provides only basic DNS-layer security. Looking for the full Umbrella experience? Cisco Umbrella subscriptions provide IP Layer Enforcement, access to the intelligent proxy for URL blocks, content filtering, multiple policies, robust reporting, active directory integration, and more. The same Umbrella Roaming Security module is used regardless of the subscription.

The Roaming Security module profile (OrgInfo.json) associates each deployment with the corresponding service, and the corresponding protection features are enabled automatically.

Umbrella provides real-time visibility into all of the internet activity originating from the Roaming Security module. The level of granularity in policies and reports depends on the Umbrella subscription.

Refer to our package comparison page for detailed information about which features are included in each service level subscription.

Note: IP layer enforcement is not available for all Umbrella packages. To get the full functionality of Umbrella Roaming Security, rather than just DNS-layer security when off the network and single security policies with basic reports (by hostname), you must have the Insight or Platform Cisco​ Umbrella packages. For more information about these packages, please read this.

Table of Contents

This guide consists of three major areas, each of which are divided into subsections:

Quick Start Guide

If you're already familiar with either the Umbrella roaming client or AnyConnect, the number of steps required to perform an upgrade can be shortened considerably. Although there are several steps to consider for a full deployment, this quick start guide links you to directions that describe how to manually deploy test installations. Since the Umbrella Roaming Security module is deployed through the ASA, it's easy to deploy and simple to manage—all without third party tools or GPO settings.

Minimum AnyConnect Software Version

The Umbrella roaming security module was introduced in 4.3 MR1 and will activate; however, this initial release software version contains several significant known issues. As a result, we are unable to support observed issues on AnyConnect software versions below 4.3 MR4. Any users experiencing an issue with 4.3 MR1 through 4.3 MR3 will be prompted to upgrade to 4.3 MR4+ (4.4 MR1 preferred) as a first step.

Minimum available version: 4.3 MR1
Minimum recommended and supported version: 4.3 MR4
Suggested version: 4.4 MR1+

If you already have the Umbrella roaming client deployed to your organization:

Migrating to the Umbrella Roaming Security module from an existing roaming client (standalone) deployment requires special consideration. Follow these steps for deploying over an existing Umbrella roaming client installation.

  1. Upgrade to AnyConnect 4.3 MR4+
  2. Enable via ASA policy or install the Umbrella Roaming Security module via the pre-deploy MSI. This will automatically detect, copy registration from, and uninstall the standalone Umbrella roaming client.
  3. You're finished, that's the only step.

If the Umbrella roaming client is not installed, the following additional steps apply.

  1. Navigate to Deployments > Roaming Computers and click Roaming Client.
  2. Scroll down to the AnyConnect Umbrella Roaming Security Module section, click Module Profile and download the OrgInfo.json file.
    Depending on your system, drop the file into

    • Windows: %ProgramData%\Cisco\Cisco AnyConnect Secure Mobility Client\Umbrella\
      or
    • Mac: /opt/cisco/anyconnect/Umbrella/

    Recommended: You will need to create this folder structure in order to do this in advance.

  3. Upgrade to AnyConnect 4.3 MR4+ with the Umbrella Roaming Security module enabled.
    You're finished, this is the final step.

If AnyConnect is deployed, but the Roaming Security module is not

  1. Navigate to Deployments > Core Identities > Roaming Computers and click Roaming Client.
  1. Scroll down to the AnyConnect Umbrella Roaming Security Module section, click Module Profile and download the OrgInfo.json file.
  1. Depending on your system, drop the file into:

    • Windows: %ProgramData%\Cisco\Cisco AnyConnect Secure Mobility Client\Umbrella\
      or
    • Mac: /opt/cisco/anyconnect/Umbrella/
      Tip: You will need to create this folder structure.
  2. Run the installer package from AnyConnect.
    This installs the profile on the AnyConnect Secure Mobility client.

System Requirements

  • Windows 7 (or later) x86 (32-bit) and x64 (64-bit) operating system

    The VPN Module requires Visual Studio 2015 32-bit runtime, which is bundled with our installation package.
    The Roaming Security Module requires a .NET framework (3.5 at the minimum)

  • Mac OS X 10.9 (or later) operating system
  • For additional system requirements and licensing dependencies, refer to the AnyConnect Secure Mobility Client Features, Licenses, and OS feature guides.

Important

The Umbrella Roaming Security module for AnyConnect can work with both the full-featured Umbrella dashboard or a dashboard that has limited capabilities when purchased as part of the Cisco Umbrella Roaming Package. The documentation for the full featured Umbrella dashboard can be found in the other sections of docs.umbrella.com.

The instructions on deploying Roaming Security module to AnyConnect clients and the instructions to gather the OrgInfo.json file to configure the module came from will vary based on which dashboard is being used.

Before You Begin

  1. Roaming Client and AnyConnect Roaming Security Module Incompatibility.
  2. Obtain an Umbrella Account.
  3. Download the Roaming Security Module Profile File from the Umbrella dashboard.

Roaming Client and AnyConnect Roaming Security Module Incompatibility

The Umbrella Roaming Security module and the Umbrella roaming client are incompatible. If you are deploying the Umbrella Roaming Security module, any existing installation of the Umbrella roaming client will be detected and removed automatically during installation of the Roaming Security module. Ensure that automated delivery of the standalone roaming client are disabled to prevent it from being placed back.
Existing roaming client installations will be automatically migrated to the Umbrella Roaming Security module unless an OrgInfo.json file is co-located with the AnyConnect installer, configured for web-deployment or pre-deployed in the Umbrella module's directory. You may also wish to manually uninstall the Umbrella roaming client prior to deploying the Umbrella Roaming Security module; however, this is not required.

Any automated push to re-install the standalone roaming client must be stopped, or an exception added for computers with the roaming module installed. The presence of both the roaming client and roaming module may lead to unintended behavior.

Obtain an Umbrella Account

The Umbrella dashboard is where you obtain the profile (OrgInfo.json) for the AnyConnect Umbrella Roaming Security module to include in your deployment. From the Umbrella dashboard, you also manage policy and activity reporting for the roaming client. If you need assistance signing into Umbrella, contact your Cisco account representative.

What AnyConnect file do I need to use to deploy?

Note, additional operating system packages may be available and required. This guide specifies Windows and MacOS packages which support the roaming module.

If you're deploying from an ASA deploy:

  • Full installation package—Windows / Head-end deployment (PKG)
  • Full installation package—Mac OS X / Head-end deployment (PKG)

If you're deploying manually for testing:

  • Full installation package—Mac OS X / Standalone installer (DMG)
  • Full installation package—Window / Standalone installer (ISO). Includes installation packages for DART, NAM, Core/VPN, Phone Home, Hostscan, ISE Posture, and WebSecurity components.

Download the AnyConnect Roaming Security Profile from the Umbrella Dashboard

The OrgInfo.json file is specific information about your Umbrella dashboard instance that lets the Roaming Security module know where to report and which policies to enforce.

To prepare for deploying the Umbrella Roaming Security module, you must obtain the OrgInfo.json file from the Umbrella dashboard.

  1. Navigate to Deployments > Core Identities > Roaming Computers and click Roaming Client.
  1. Scroll down to the section marked AnyConnect Umbrella Roaming Security​ Module and click Module Profile to download the OrgInfo.json file.

For specific installation/deployment steps and package and file specifics, see the Cisco AnyConnect Secure Mobility Client Administrator Guide.

Important

When you deploy the OrgInfo.json file for the first time, it is copied to the data subdirectory (/umbrella/data), where several other registration files are also created. Therefore, if you need to deploy a replacement OrgInfo.json file, the data subdirectory must be deleted. Alternatively, you can uninstall the Umbrella Roaming Security module (which deletes the data subdirectory) and reinstall with the new OrgInfo.json file.

The OrgInfo.json is specific information about your Umbrella dashboard instance that lets the Roaming Security module know where to report to and which policies to enforce. If you use another OrgInfo.json file from a different dashboard to install the Roaming Security module, the client computer will appear in that dashboard instead.

Get the Roaming Security Module Up and Running

When you deploy AnyConnect, you can include optional modules that enable extra features and set up client profiles that configure the VPN and optional features.

Roaming Security is now one of these optional modules.

Web Security Module Compatibility

If you are deploying the Umbrella Roaming Security module with the Web Security module, you must configure the exclude static and host exceptions referenced in Required Host Exception for Web Security and Roaming Security Compatibility and Required Static Exception for Web Security and Umbrella Roaming Security Modules Compatibility.

For Windows 7 SP1 users, we recommend that you install Microsoft .NET framework 4.0 before installation or initial use. At startup, the Umbrella service checks if .NET framework 4.0 (or newer) is installed. If it is not detected, the Umbrella Roaming Security module is not activated, and a message is displayed. To go and then install the .NET Framework, you must reboot to activate the Umbrella Roaming Security module.

Enable the Module

In order to use an AnyConnect module such as the Umbrella Roaming Module, it first must be enabled. This may be done via pre-deploy (SSCM, RMM, etc) via the umbrella roaming module MSI installer version matching your deployment or via the ASA policy with ASDM (adding the module "Umbrella" to your profile) or via the CLI:

webvpn
       anyconnect modules value umbrella

Configure the OrgInfo.json File

The OrgInfo.json file contains specific information about your Cisco Umbrella service subscription that lets the Security Roaming module know where to report and which policies to enforce. You can deploy the OrgInfo.json file and enable the Umbrella Roaming Security module from the ASA or ISE using CLI or GUI. The steps below describe how to enable from the ASA first and then how to enable from ISE:

ASA CLI

  1. Upload the OrgInfo.json that you obtained from the Umbrella​ dashboard to the ASA file system.
  2. Issue the following commands, adjusting the group-policy name as appropriate for your configuration.

Tip

The file name on the ASA is case sensitive. If the file you've uploaded is named "OrgInfo.json", it must be specified with a capital O and capital I.

Just looking for the defaults? Use the value of "DfltGrpPolicy" below for <Group_Policy_Name>

webvpn
    anyconnect profiles orginfo disk0:/OrgInfo.json

group-policy <Group_Policy_Name> attribute
    webvpn
        anyconnect profiles value orginfo type umbrella

group-policy <Group_Policy_Name> attributes
    webvpn
        anyconnect modules value umbrella

ASDM GUI

Note: ASDM 7.6.2 is required to configure the Umbrella Roaming Security module via GUI, and that version is not yet released. CLI configuration is the only option until ASDM 7.6.2 is released.

  1. Navigate to Configuration > Remote Access VPN > Network (Client) Access > AnyConnect Client Profile.
  2. Choose Add.
  3. Give the profile a name.
  4. Choose the Umbrella Security Roaming Client type from the Profile Usage drop-down list. The OrgInfo.json file populates in the Profile Location field.
  5. Click Upload and browse to the location of the OrgInfo.json file that you downloaded from the dashboard.
  6. Associate it with the DfltGrpPolicy at the Group Policy drop-down list or the policy of your choice. Refer to Enable Additional AnyConnect Modules to specify the new module name in the group-policy.

ISE

Follow these steps to enable from ISE:

  1. Upload the OrgInfo.json from the Umbrella dashboard.
  2. Rename the file OrgInfo.xml.
  3. Follow steps in Configure ISE to Deploy AnyConnect.

Cloud Update

The Umbrella Roaming Security module can provide automatic updates for all installed AnyConnect modules from the Umbrella Cloud infrastructure. With Cloud Update, the software upgrades are obtained automatically from the Umbrella Cloud infrastructure, and the update track is dependent upon that and not any administrator action.

By default, automatic updates from Cloud Update are disabled. To enable Cloud Updating for Umbrella Roaming Security and the rest of AnyConnect, log into the Umbrella dashboard. Under the Settings icon (the gear icon) check 'Automatically update AnyConnect, including VPN'
By default, this option is not selected.

Consider the following regarding Cloud Update:

  • Only the software modules that are currently installed are updated.
  • Customizations, localizations, and any other deployment types are not supported.
  • The updates occur only when logged into a desktop and will not occur if a VPN is established.
  • With updates disabled, the latest software features and updates will not be available.
  • Disabling Cloud Update has no effect on other update mechanisms or settings, e.g. web-deploy, deferred updates, etc.
  • Cloud Update will ignore devices having a newer, unreleased versions of AnyConnect (interim releases and patched versions.)

Cisco Certificate Import

It's important to your end user's​ experience that you install the Cisco certificate on computers that will use the Roaming Security module when off-network and off-VPN. Although this is not required as it only affects block pages when reaching HTTPS domains, it is good to have. When HTTPS enabled domains are blocked by your policy, the Umbrella Roaming Security module presents a block page to you which is also served over HTTPS. This block page is encrypted with a certificate signed by the Cisco Root CA. In order to avoid certificate errors when accessing the block page, you must install the Cisco Root CA in your users' browsers.

Steps to perform this vary based on operating system and browser type and are outlined here.

Cloud Web Security (CWS) Module Compatibility

In order to use the Cloud Web Security module along with the Umbrella Roaming Security module, two settings changes are required to be made to prevent CWS from overriding the Umbrella Roaming module. These changes are a static exception and a host exception as follows:

1. Required Static Exception for Web Security and Umbrella Roaming Security Modules Compatibility
To ensure interoperability between the Umbrella Roaming Security and Web Security modules, you must configure the following exceptions in the Web Security profile provisioned to AnyConnect:

67.215.64.0/19

204.194.232.0/21

208.67.216.0/21

208.69.32.0/21

185.60.84.0/22

146.112.61.0/24

146.112.128.0/18

146.112.192.0/18

2. Required Host Exception for Web Security and Roaming Security Compatibility

You must configure *.opendns.com as a host exception if you are deploying the Umbrella Roaming Security module with the Web Security module. Failure to do so results in the Umbrella Roaming Security DNS protection being completely bypassed.

IP Layer Enforcement as part of the Umbrella Roaming Security Module

IP Layer Enforcement is an optional feature for some customers (depending on which package you've purchased). There are requirements to use this feature that are above and beyond those outlined in this specific setup guide. All of the information about this feature for the Roaming Security module for AnyConnect can be found here.

Understanding UI Changes on the Endpoint

You or your users will see state changes on the AnyConnect endpoint which are new after the installation of Umbrella Roaming Security.

Within the AnyConnect user interface, the Roaming Security tile gives the current status:

Note: If you see no state displayed, the Roaming Security Module is installed, but the OrgInfo file is not deployed.

State
Icon Color
Description
Condition

Reserved

Orange

Checking Connection Status.
No active network connections. The Roaming Module waits for an active network connection.

This operating state occurs during the following conditions:

When the module is first activated.

When a network interface change (such as detection of a new network adapter, IP changes on an existing adapter, or a new VPN tunnel being established or torn down) occurs.

Open

Yellow

You are not currently protected by Umbrella.
There is at least one active network connection; however, the roaming client cannot connect to 208.67.222.222 over port 53/UDP on any active connection. The user is not protected by Umbrella or reporting to Umbrella. The system’s DNS settings will revert to their original settings—DHCP or Static.

This operating state occurs during the following conditions:

No UDP port 443 or UDP port 53 connectivity to Umbrella resolvers (208.67.222.222).

No Umbrella DNS VA is configured on the local network.

The VPN tunnel may temporarily be in a state of tear down or establishment.

Protected

Green

You are protected by Umbrella. A network connection is active, and the Roaming Module is able to connect to port 208.67.222.222 over port 53/UDP, but not 443 UDP. The user is protected and reporting to Umbrella, but the connection is not encrypted.

This state may occur when the module is first activated or when there is a network interface change.

Encrypted

Green

You are protected by Umbrella.
The Umbrella roaming client has established a connection to 208.67.222.222 over port 443/UDP. The user is protected and reporting to Umbrella, and the DNS queries are encrypted. Internal Domains are forwarded to DHCP-delegated or statically-set DNS servers and are therefore not encrypted.

This operating state occurs during the following conditions:

UDP port 443 connectivity to Umbrella resolvers (209.67.222.222).

TCP port 443 and TCP port 53 connectivity to Umbrella resolvers (208.67.222.222).

Protected Network

Green

You are on a network protected by Umbrella. The computer is behind a Protected Network, and the organization has “Disable Behind Protected Networks” enabled in their dashboard. The Umbrella roaming client has reverted the DNS settings back to what was set via DHCP or statically set. The connection is not Encrypted.

This operating state occurs during the following conditions:

The current endpoint network egress IP address is registered with the same Umbrella account as the endpoint.

Resolvers used are the Umbrella cloud resolvers (208.67.222.222, 208.67.220.220).

Policy configured via Umbrella dashboard ("Disable Behind Protected Networks") dictates that the Umbrella module should be disabled when on a protected network.

Note: This state is not possible for all Umbrella Roaming package customers because there is no network-level protection.

Behind Virtual Appliance

Green

You are protected by an Umbrella Virtual Appliance.
The computer is connected to a Network which has Virtual Appliances configured for DNS servers. The Roaming Module disables itself and reverts the DNS settings back to what was set via DHCP or statically set. The connection is not Encrypted.

This operating state occurs when the endpoint configured DNS address (via DHCP or statically) is the Umbrella VA address.

VPN Trusted Network State

Gray

Disabled while you are on a trusted network. Local Umbrella module DNS protection is not active because the current endpoint network is configured as an AnyConnect VPN trusted network.

This operating state occurs during the following conditions:

AnyConnect VPN module is reporting the Trusted Network Detection state as trusted.

AnyConnect VPN tunnel is either not connected or established in full tunnel mode.

The policy configured via the Umbrella dashboard dictates that the Umbrella module should be disabled when on an AnyConnect VPN trusted network.

Note: This setting is true for all roaming package customers and cannot be changed by the administrator.

Disabled due to VPN State

Gray

Disabled while your VPN is active. Local Umbrella module DNS protection is not active because the endpoint currently has an active AnyConnect VPN tunnel established.

This operating state occurs during the following conditions:

AnyConnect VPN module is reporting the Trusted Network Detection state as not trusted.

AnyConnect VPN tunnel is established in full tunnel mode.

Policy configured with the Umbrella dashboard dictates that the Umbrella module should be disabled when an AnyConnect VPN tunnel is established.

Note: This setting is true for all roaming package customers and cannot be changed by the administrator.

No OrgInfo.json State

Red

You are not currently protected by Umbrella.
Profile is missing. Local Umbrella module DNS protection is not active because the endpoint currently has an active AnyConnect VPN tunnel established.

This operating state occurs when the OrgInfo.json file was not deployed to the proper directory:

Windows: %ProgramData%\Cisco\Cisco AnyConnect Secure Mobility Client\Umbrella

Mac: opt/cisco/anyconnect/umbrella

Agent Unavailable State

Red

You are not currently protected by Umbrella.
Service unavailable. Local Umbrella module DNS protection is not active because the Umbrella agent is not running.

This operating state occurs when the Umbrella agent service is not currently running (either due to a crash or manual service stop).

Missing .NET Dependency State (Windows only)

Red

You are not currently protected by Umbrella. Microsoft 4.0 NET framework is not installed. Local Umbrella module DNS protection is not active because the Umbrella agent is not running. The .NET runtime framework is missing.

This operating state occurs when the Umbrella agent service is not running due to a missing .NET 4.0 runtime.

Interpret Diagnostics

For any general AnyConnect or Roaming Security module issues, refer to the Cisco AnyConnect Secure Mobility Client Administrator Guide. We will also ask you to run a DART report for diagnostic purposes.

The Roaming Security module has a unique diagnostic tool for troubleshooting as well. The executable can be found:

Windows:
%Program Files (x86)%\Cisco\Cisco AnyConnect Secure Mobility Client\UmbrellaDiagnostic.exe

Mac OS X:
/opt/cisco/anyconnect/bin/UmbrellaDiagnostic.app/

Running the executable will provide instructions on how to submit the feedback from this diagnostic to support.

Next, we'll configure your Cisco Umbrella Security Policies and review the reports.


AnyConnect: Cisco Umbrella Roaming Security Client Administrator Guide > Adding IP Layer Enforcement