Troubleshoot Non-Browser Applications in Umbrella

Introduction

This document describes how to troubleshoot non-browser applications in Cisco Umbrella.

Prerequisites

Requirements

There are no specific requirements for this document.

Components Used

The information in this document is based on Cisco Umbrella.

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Overview

This article explains best practices and troubleshooting steps for configuring Non-Browser applications to function with Umbrella Secure Web Gateway. In most cases, no configuration changes are required. However, certain applications do not work well with security/inspection functions (such as SSL Decryption) and exceptions must be added to make the application function with a web proxy. This applies to Umbrella SWG as well as other web proxy solutions.

This is useful in circumstances where the website/browser version of an application works, but the desktop/mobile version of the application does not.

Compatibility Problems

Applications can be incompatible for these reasons:

Warning: Creating these exceptions can disable security inspection functions including Anti-Virus scanning, DLP scanning, Tenant Controls, File Type Control and URL inspection.  Only do this if you are happy to trust the source of these files. The business need for the application must be weighed against the security impact of disabling these features.

Microsoft 365 Applications

The Microsoft 365 Compatibility feature automatically excludes a number of Microsoft domains from SSL Decryption and policy enforcement functions. This feature can be enabled to resolve problems with the Desktop version of Microsoft apps.  For more information see Manage Global Settings.

Note: The Microsoft 365 Compatibility feature does not exclude all Microsoft domains.  Umbrella uses Microsoft's recommendations for the list of domains which must be excluded from filtering. For more information see New Office365 Endpoint Categories.

Certificate Pinning Bypass

Certificate Pinning (PKP) is a common cause of app compatibility issues.  Cisco provide a comprehensive list of named Applications that can be configured to bypass SSL Decryption to workaround. The selective decryption can be configured in Policies > Selective Decryption Lists.

In most cases, the administrator can resolve certificate pinning issues simply by excluding the application by its name. This means that these issues can be resolved without having to learn or maintain lists of domains.

Alternatively, applications can be bypassed based on destination domain/IP address. Contact the application vendor to determine the applicable list of domains/IPs or see Identify exclusions for certificate pinning.

TLS Compatibility Bypass 

Legacy or custom TLS versions are a common cause of app compatibility issues. These problems can be solved by excluding the traffic from Umbrella in Deployments > Domain Management > External Domains & IPs. In a tunnel deployment the traffic can only be excluded by adding exceptions in your VPN configuration.

Contact the application vendor to determine the applicable list of domains/IPs to exclude or see "Identify Exclusions for Incompatible TLS Versions" (later in this article).

Troubleshooting (Advanced)

The remaining instructions in this article use Wireshark (www.wireshark.org) packet captures for troubleshooting purposes. Wireshark can help to identify which domains are used by applications for help with implementing custom exclusions. Before starting, add these custom columns in Wireshark:

1. Download Wireshark from www.wireshark.org.

2. Go to Edit > Preferences > Columns.

3. Create columns of type Custom with these fields:

http.host
tls.handshake.extensions_server_name
x509sat.uTF8String

To perform a packet capture, complete these instructions or see Capture Network Traffic with Wireshark.

1. Run Wireshark as an Administrator.

2. Select the relevant network interfaces in Capture > Options.

• For PAC / Tunnel Deployments, capture on your normal LAN network interface.
• For AnyConnect Deployments, capture on your LAN network interface and the loopback interface.

3. Close down all other applications except the problem application.

4. Flush your DNS cache: ipconfig /flushdns

5. Start the Wireshark capture.

6. Quickly replicate the issue and stop the Wireshark capture.

Identify Exclusions for Certificate Pinning

Certificate pinning is enforced on the client, meaning that the exact behavior and resolution steps differs for every application. In the capture output, look for telltale signs that a TLS connection is failing:

• A TLS connection is being quickly closed or reset (RST or FIN).
• A TLS connection is being repeatedly retried.
• The certificate for the TLS connection is being issued by Cisco Umbrella and is therefore being decrypted. 

These example Wireshark filters can help to view the important details of TLS connections.

Tunnel / AnyConnec

tcp.port eq 443 && (tls.handshake.extensions_server_name || tls.handshake.certificate || tcp.flags.reset eq 1 || tcp.flags.fin eq 1)

PAC / Proxy Chaining

tcp.port eq 443 && (http.request.method eq CONNECT || tcp.flags.reset eq 1)

n this example, the DropBox desktop application is affected by certificate pinning when attempting to connect to client.dropbox.com.

Note: After adding the necessary exclusion(s), you can repeat these steps multiple times to identify all the destinations used by the application.

Identify Exclusions for Incompatible TLS Versions

Look for SSL/TLS connections that do not use the mandatory TLS1.2+ protocols supported by Umbrella SWG. This can include legacy protocols (TLS1.0 or earlier) or bespoke custom-protocols implemented by an application.

This example filter shows you initial TLS handshake packets along with DNS queries.  

Tunnel / AnyConnect

dns || (tls && tcp.seq eq 1 && tcp.ack eq 1)

PAC / Proxy Chaining

dns || http.request.method eq CONNECT

In this example, the Spotify desktop application is attempting to connect to ap-gew4.spotify.com using a non-standard or legacy "SSL" protocol which cannot be sent via SWG.

Note: After adding the necessary exclusion(s), you can repeat these steps multiple times to identify all the destinations used by the application.