Deploying VMware Workspace ONE Tunnel: Workspace ONE Operational Tutorial

Overview

Note: This tutorial was created using Windows 10, but the basic principles and tasks outlined also apply to your deployment of Windows 11.

VMware provides this operational tutorial to help you with your VMware Workspace ONE® environment. In this tutorial, explore how to configure and deploy the VMware Workspace ONE Tunnel app across iOS, Android, macOS, and Windows platforms to enable Per-App Tunnel on a managed device. Procedures include enable per-app tunneling on managed devices and SDK-enabled applications, configuration of Tunnel policies, deployment of the client and profiles to devices, and general lifecycle maintenance.

Audience

This operational tutorial is intended for IT professionals, network and security administrators, and Workspace ONE administrators of existing production environments. Both current and new administrators can benefit from using this tutorial. Familiarity with networking in a virtual environment, knowledge of Tunnel Service on VMware Unified Access Gateway™ or VMware Secure Access™, and VMware Workspace ONE® UEM is assumed.

Getting Started with Workspace ONE Tunnel

Workspace ONE Tunnel enables secure access for mobile workers and devices. Users have a simple experience and need not enable or interact with Tunnel, and IT organizations may take a least-privilege approach to enterprise access, ensuring only defines apps and domains have access to the network.

Tunnel provides industry-best security and builds on TLS 1.2+ libraries, implements SSL Pinning to ensure no MITM attacks, and includes client certificates on the allowlist to ensure identity integrity. Combined with explicit definitions of managed applications and integration with Workspace ONE compliance engine, Tunnel can help customers attain Zero Trust goals for their workforce.

Prerequisites

Before you can perform the steps in this tutorial, you must install and configure the following components:

  • Tunnel Service configured in VMware Unified Access Gateway or VMware Secure Access (latest release recommended)
  • Workspace ONE UEM 2302 and later
  • A device for the platform you plan to use (Windows, macOS, Android, or iOS)

Ensure the following settings are enabled in the Workspace ONE UEM Console:

  • Organization Group created and set as Customer Type
  • UEM REST API enabled and setting override
  • Device Root Certificate issued
  • VMware Tunnel configured

Confirm that Tunnel Service is Configured

The remainder of this section assumes that Tunnel Service is properly configured and running on the Unified Access Gateway or on the VMware Secure Access. For more details, see Configuring the VMware Tunnel Edge Service: Workspace ONE Operational Tutorial.

  1. In the Workspace ONE UEM console, navigate to Groups & Settings > Configurations.
  2. Scroll through the list of configurations if necessary and select Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. Select Test Connection and confirm that both the Console to AWCM and Tunnel to API tests report Success and the Tunnel server reports service status UP.

    A screenshot of a computer

Description automatically generated 

This status confirms that the Tunnel Service is up and running on the server-side, and properly communicating with Workspace ONE UEM.

Tunnel Mode (Per-App vs Full Device Tunnel)

VMware Tunnel provides two modes for tunneling traffic: Per-Application or Full Device. Each mode is configured as part of the Device Traffic Rules and assigned to a device based on the Profile configuration. A device cannot perform Per-App and Device Tunnel at the same time.

Per-App Tunnel

Per-App Tunnel restricts tunnel traffic only to authorized applications and destinations (domain) specified by the UEM administrator when configuring the Device Traffic Rules.

Full Device Tunnel

On Full Device Tunnel configuration, traffic is restricted based on the authorized destinations (domains or IPs), regardless of the application. Full Device mode on Windows requires Workspace ONE Desktop Tunnel 2.1.8+ for all MDM use cases. For standalone enrollment use cases the Workspace ONE Desktop Tunnel version 3.1 is required and will support Per-App and Full Device tunnel mode. Consolidating the MDM and standalone workflows in a unified Windows Tunnel client is on our roadmap.

Supported Platforms

Workspace ONE Tunnel app is available for managed and unmanaged devices providing Per-App and Full Device Tunnel across multiple platforms. Only TCP and UCP traffic will be routed to the Workspace ONE Tunnel App; ICMP-based traffic used by ping utilities is not supported. The Workspace ONE Tunnel app on Windows and macOS platforms now supports Standalone enrollment without Workspace ONE Intelligent Hub or any device management.

Tunnel Mode (Per-App and Full Device) is available based on the device platform and how it is managed as described in the following table.

Feature availability based on Management Mode and Device Platform

Management

Tunnel Mode

Win10

macOS

iOS

Android

UEM Managed

Per-App

Full Device

Registered Mode (unmanaged)

Per-App

N/A1

*

*

Full Device

N/A1

N/A2

N/A2

App Level (MAM/Standalone)

Per-App

*

*

Full Device

* Requires use of the Tunnel module (aka Tunnel SDK) available on Workspace ONE SDK.

Standalone method does not require Intelligent Hub; enrollment is done through the Workspace ONE Tunnel App.

N/A1 – Management mode not supported on the specific platform.

N/A2 – Not applicable for the specific Tunnel mode.

For more information, see Supported Platforms for VMware Workspace ONE Tunnel.

For more information on Standalone requirements, see Configuring VMware Tunnel Client for Standalone enrollment.

Per-App Tunnel Support for MAM Mode Workflow

Many organizations do not need to manage devices for their mobile fleets for various reasons, including possible privacy or legal issues. However, they might need to distribute mobile applications to access internal resources, so Workspace ONE UEM offers the flexibility of using a standalone catalog through Intelligent Hub that works independently of the MDM feature.

Applications that leverage the Workspace ONE SDK, such as Workspace ONE Web, can be configured to access internal web applications through Per-App Tunnel. The Workspace ONE Tunnel app is not required for this scenario. Also, organizations that develop mobile internal apps can be integrated with Workspace ONE SDK to enable access from unmanaged devices. Workspace ONE SDK is available on iOS and Android platforms.

In a MAM mode scenario, users do not have to enroll the device as UEM Managed and the Workspace ONE Tunnel app is not required, but rather they can:

  1. Use SDK-Enabled apps like Boxer or Web that will manage the registration of the device and be identified as App Level registration on UEM.
  2. Use the Intelligent Hub app in registered mode to access the Intelligent Hub catalog part of Workspace ONE UEM. This catalog distributes all application types; public, purchased, internal, and Web.  Although end-user devices are not enrolled in MDM, you can access a device record in the Workspace ONE UEM console.

In both cases, the device record is for auditing purposes and the status of these devices in the UEM console displays as App Level (#1) or Hub Registered (#2).

Configuration Requirements for MAM

To enable Tunnel for SDK-based apps, navigate to Groups and Settings > Apps > Settings and Policies > Security Policies in the Workspace ONE UEM Console.

  1. Select Enabled to enable the AirWatch App Tunnel.
  2. Select VMware Tunnel for the App Tunnel Mode.

After that, define the Device Traffic Rules for the iOS and Android SDK-enabled applications which will be covered later as part of this tutorial.

As a reminder, when using the MAM workflow and registered mode using the Workspace ONE Intelligent Hub, the SDK-enabled apps must be deployed through the Intelligent Hub catalog, and the Workspace ONE Tunnel app is not required.

The Workspace ONE Tunnel app can be deployed as a standalone app and perform enrollment without Workspace ONE Intelligent Hub or any device management. In this scenario, Workspace ONE UEM will only contain the device record.

Understanding Device Traffic Rules

This section discusses the two types of network traffic rules–server traffic rules and device traffic rules.

What are Device Traffic Rules?

Network traffic rules allow you to set granular control over how the VMware Tunnel Service directs traffic from devices.

Workspace ONE UEM defines two types of network traffic rules in support of Workspace ONE Tunnel:

  • Server Traffic Rules
  • Device Traffic Rules

You can create device traffic rules to control how devices handle traffic on the device Per-Application or Full Device.

Server Traffic Rules

The Server Traffic Rules enable you to manage how application traffic is routed throughout your network after traversing the Tunnel Service on Unified Access Gateway infrastructure. Specifically, if you require the use of proxies in your network or for external access, these proxies can be defined and configured as part of Server Traffic Rules.

Configuration of Service Traffic Rules will not be covered in this tutorial. For additional information, see Configure Server Traffic Rules in VMware Docs.

Device Traffic Rules

The Device Traffic Rules define how traffic from specified applications (Per Application) or devices (Full Device) is routed by the Workspace ONE Tunnel application. The device traffic rules serve as a locally enforced Access Control List, defining which apps and destinations should be blocked, tunneled, proxied, or bypass the tunnel completely.

Under Manage Traffic Assignments, administrators can create multiple Device Traffic Rule sets to segment traffic to internal resources, such as rules for employees' devices that are less restricted than access to contractor devices.

  • Each traffic assignment (Device Traffic Rule Set) contains multiple rules.
  • A profile can only have a single traffic assignment (Device Traffic Rule Set).
  • A device can only apply a single VPN profile at any one time.

Manage Traffic Assignments requires Workspace ONE UEM 2011, otherwise, a single Device Traffic Rule set can be created.

A screenshot of a computer

Description automatically generated

For each device traffic rule, you must set a Tunnel Mode to determine if traffic will be tunneled Per-Application or Full Device, then defined rules are ranked in order of execution. Multiple device traffic rules can be created and assigned to a profile that uses smart groups to determine the device assignment of the rules.

As an example, in device traffic rules set for Per-Application tunnel mode, every time a specified application is opened, the Tunnel client evaluates the Device Traffic Rule assigned to it before making any routing decisions. If no set rules match the situation, the Tunnel applies the default action. The default action behavior can vary per platform:

  • On the iOS platform, the default action set for all managed applications with tunnel profile associated except for Safari and applies to domains not mentioned in a rule. If no rules are specified, the default action applies to all domains and all managed applications associated with VPN Profile.
  • On the macOS platform, the default action set for all macOS applications specified on the DTR rules applies to domains not mentioned in a rule. At least one rule must be defined and when it doesn’t match any rule the default action applies to all domains and all macOS applications mentioned above in the Rank.
  • On the Windows 10+ platform, the default action set for all Windows applications specified on the DTR rules applies to domains not mentioned in a rule. At least one rule must be defined and when it doesn't match any rule the default action applies to all domains and all Windows applications mentioned above in the Rank.
  • On the Android platform, the default action set for all Android managed applications with tunnel profile associated and applies to domains not mentioned in a rule. If no rules are specified, the default action applies to all domains and all managed applications associated with VPN Profile.

More information about the specifics of device traffic rules per platform will be covered as part of this tutorial in the following chapters.

The device traffic rules help to separate personal and corporate traffic. Think of a scenario where the end-user can check their personal email, visit social media, and so on, without having their personal traffic inspected. We provide privacy where a traditional VPN cannot.

Per-Application Traffic Rules

When configuring the Device Traffic Rules and setting Tunnel Mode to Per Application, the administrator is required to configure the rules per application and domain. These rules will be used by the Workspace ONE Tunnel application to restrict the tunnel traffic only to authorized applications and domains.

A screenshot of a computer

Description automatically generated

Note the following:

  1. Tunnel Mode for the Device Traffic Rules Set.
  2. Per-Application Rules.
  3. Default Action Rule that will be performed when the client traffic doesn't match rules 1 and 2.

Full Device Traffic Rules

When the Tunnel Mode is set to Full Device, traffic is restricted based on the domains specified in the rules. Note: You cannot configure applications as part of this rule.

Full Device mode requires Workspace ONE UEM 2102+, Workspace ONE Desktop Tunnel 2.1+, and it is available only on Windows 10+.

A screenshot of a computer

Description automatically generated

Note the following:

  1. Tunnel Mode for the Device Traffic Rules Set.
  2. Full Device Rules.
  3. Default Action Rule that will be performed when the client traffic doesn't match rules 1 and 2.

Device Traffic Rules Wildcard Guidelines and use of asterisk (*)

When defining the Device Traffic Rules destination, the administrator can enter a list of domains to allow, block, or bypass traffic.

The wildcard is supported for the hostnames and multiple entries must be separated by comma (,).

Supported Wildcard and use of asterisk (*)

You can use wildcard characters for your hostnames. Wildcards must follow the format:

  • *.<domain>.*
  • *<domain>.*
    • Includes primary domain and subdomains - for example, www.example.com, example.com, store.example.com
  • *.* — You cannot use this wildcard for Safari domain rules (iOS and macOS specific)
  • — You cannot use this wildcard for Safari domain rules (iOS and macOS specific)

IP and Port Ranges Format Support on Device Traffic Rules

Use of IPs and port ranges are only supported for Device Traffic Rules on Windows 10+ devices. The following list contains supported formats for the IPv4 & Port range when applying the Device Traffic Rules (DTR).

  1. Single IP
    1. 10.10.0.1 or 10.10.10.1/32
  2. IP range or subnet
    1. 10.10.10.1/24
    2. 10.10.0.0/16
  3. Single Port
    1. *.example.com:80, 10.10.10.1:80,10.10.11.1/32:80
    2. *.example.com:[443], 10.10.11.1/24:[443]
  4. Port Range
    1. *.example.com:[80-443], 10.10.10.1:[80-443],10.10.11.1/32:[80-443]
    2. 10.10.11.1/24:[80-443]
  5. List of Ports
    1. *.example.com:[80,443], 10.10.10.1:[80,443],10.10.11.1/32:[80,443]
    2. 10.10.11.1/24:[80,443]
  6. List of Ports and Ranges
    1. *.example.com:[80,443, 8080-8085], 10.10.10.1:[80,443,8080-8085],10.10.11.1/32:[80,443,8080-8085]
    2. 10.10.11.1/24:[80,443,8080-8085]

Publishing Device Traffic Rules

When making changes to the Device Traffic Rules those need to be sent to the device to take effect, this process requires synchronization between device and UEM, and can be applied to existing managed devices or only new enrolled devices. This chapter describes the difference between Save and Save and Publish device traffic rules set, in addition to how the changes will be sent to the device.

Save and Publish Device Traffic Rules Flow

When the administrator changes the Device Traffic Rules and clicks Save and Publish, an updated version of the VPN profile mapped to the Device Traffic Rules will be created and queued for all the assigned devices. That process will reissue the client certificate as part of the profile to the device with a new thumbprint.

The Tunnel client app might not be able to establish a connection with Tunnel Service until the new VPN profile gets installed on the device. Forcing a sync on the device can speed up the profile installation but in environments with a large number of devices, this process can take additional time.

The Save and Publish option is only available on the default Device Traffic Rules set.

Save Device Traffic Rules Flow

When the administrator changes the Device Traffic Rules set and clicks Save, the Device Traffic Rules get mapped to the profile, but the updated Device Traffic Rules are not replaced for the devices where the VPN profile is already installed. Device Traffic Rules are only updated for the newly enrolled devices or for the devices that have the VPN profile reinstalled.

Save is the only option available for a non-default Device Traffic Rules set - this means that after you change the device traffic rule set and hit save, you must push a new version of the VPN profile to current devices where the profile was already deployed.

Identify the VPN Profile Status (Installed, Not Installed, Pending Install, and Assigned)

As mentioned previously, publishing a device traffic rule or changes on the VPN Profile will create a new profile version and queue it to all assigned devices. The tunnel client might not be able to establish a connection with the Tunnel Service until the new profile comes down to the device. The administrator can monitor the deployment status of the new VPN profile with the following steps:

Locate the VPN profile under the Resources / Profiles & Base Lines / Profiles and click the View link to identify the total number of profiles not installed, installed and assigned. Click the Not Installed hyperlink to push the profile manually.

Locate the device under the Devices / List View, select the Profile page and point to the Profile Status. Selecting the profile allows you to send a command to remove or install the profile on the respective device.

A screenshot of a computer

Description automatically generated

New Device Traffic Rules Sync Process

A new process to sync Device Traffic Rules (DTR) will be implemented on the Workspace ONE Tunnel App to minimize the push of the Tunnel profile to the device every time the DTR changes. This new process, as of today, is only available for Android and requires Workspace ONE UEM 2209+ and Workspace ONE Tunnel version 2209.

The new process requires you to enable the Workspace ONE Tunnel client to request the DTR from a Tunnel API endpoint (hosted on UEM) automatically on every launch or every 4 hours (default). The new Tunnel API endpoint is identified as  http://ws1-api-server/DevicesGateway/devices/{deviceuuid}/tunnel/{tunnelconfiguuid}/configuration?device-traffic-rule-set-uuid={dtr-set-uuid} (TunnelConfigurationSyncEndpointUrl) and is invoked by the Workspace ONE Tunnel client to obtain the new DTR.

  • By default, the client syncs DTR every 4 hours.
  • This value can be changed via the client_sync_interval key in Custom Settings on the Tunnel Configuration Page. The value is specified in minutes.

Workspace ONE Tunnel client would reach the TunnelConfigurationSyncEndpointUrl on every launch, so modifying the client_sync_interval is not recommended unless you have a critical use case. The following table provides the sync interval recommendation based on the number of devices enrolled.

Number of devices in the environment

Sync Interval

1 – 50,000

15 minutes

50,000 – 100,000

30 minutes

100,000 – 200,000

60 minutes

200,000 – 500,000

120 minutes

500,000 – 1,000,000

240 minutes

To verify if the tunnel client can sync with the endpoint, open the Diagnostics UI.

Tunnel Client Codes in the UI:

  • 200 - DTR was modified in UEM and successfully synced.
  • 304 - sync triggered but no changes in DTR.
  • 204 - sync triggered but admin has possibly deactivated FF and has not republished the profile to remove sync settings.

To ensure that the client received the settings, the Diagnostics UI displays the Sync Interval and Sync URL as well.

A screenshot of a computer

Description automatically generated

Trusted Network Detection

Trusted Network Detection is a mechanism in the Workspace ONE Tunnel app that determines whether to establish a connection with the Tunnel Service to tunnel access to corporate applications. If the device is connected to the corporate network and trusted network detection is configured, the Workspace ONE Tunnel app does not tunnel traffic to the corporate applications.

When setting up a Trusted Network Detection in UEM Tunnel Configuration, routing is dependent on DNS and will ignore HOSTS file entries.

Currently, Trust Network Detection is supported on Windows 10+ and Android platforms.

Trusted Network Detection on Windows Devices

For Windows 10+ devices, Trusted Network Detection is configured as part of the Per-App VPN payload, and can be configured leveraging DNS suffix or internal URL (probe URL).  

Trusted Network Detection based on DNS Suffix

When using DNS suffix, Workspace ONE Tunnel compares the DNS suffix defined on the device against the list of trusted networks configured on the Trusted Network Detection field to determine if the device is on the trusted network or not.

Administrators can add a list of domains separated by a comma into the Trusted Network Detection field (see the following screenshot) and that will leverage DNS suffix. Workspace ONE Tunnel fails to connect when the device is on a trusted network.

A screenshot of a computer

Description automatically generated

Trusted Network Detection Based on Probe URL

When using Probe URL (recommend method), Workspace ONE Tunnel will make HTTP calls against the list of private URLs defined in the custom configuration probe URLs to determine if the device is on the trusted network or not.

Administrators can add a list of domains separated by a comma into the Custom Configuration XML field (see the following screenshot) using the TrustedNetworkProbeUrl XML tag. Workspace ONE Tunnel fails to connect when the device is on a trusted network.

A screenshot of a computer

Description automatically generated

Trusted Network Detection on Android

For Android devices, Trusted Network Detection is configured on the Workspace ONE Tunnel app through App Config, using the TrustedNetworkProbeUrl key, and the value is a list of URLs separated by a comma that can optionally have http/https scheme and an assigned port.

Format examples:

  • <internal-site>
  • <internal-site>:<port>
  • http://<internal-site>
  • http://<internal-site>:80
  • https://<internal-site>
  • https://<internal-site>:443

Workspace ONE Tunnel app for Android determines if the device is on the internal network based on the device's ability to reach the private URLs defined as part of the TrustedNetworkProbeUrl.

A screenshot of a computer

Description automatically generated

Next Steps

The procedures in this tutorial consist of the following:

  • Device Traffic Rule configuration
  • Deployment of Per-App VPN Profile
  • Deployment of Workspace ONE Tunnel Client
  • Testing configurations on the chosen device

The procedures are almost the same for each platform. To ensure you understand any existing particularity and stay focused on the platform of your choice, the following steps in this tutorial are organized per platform.

Deploying Workspace ONE Tunnel for iOS

Per-App Tunneling helps users to access critical information using applications on their devices from their devices. Mobile flows help users perform business-critical tasks from a single app — streamlining the user experience.

Leveraging Per-App Tunnel allows you to control which applications are on a device and what internal resources the applications have access to by automatically activating or deactivating Per-App VPN access, based on which applications are active. By enabling remote access, you no longer need to provide a device-wide VPN on your devices, which can allow unintended or unauthorized apps or processes to access your VPN. In this tutorial, you configure and deploy VMware Workspace ONE Tunnel to enable the Per-App Tunnel component on managed devices.

These exercises involve the following components:

  • Workspace ONE Tunnel – The app used on the device to securely connect to the Unified Access Gateway to provide Per-App Tunnel functionality, also referred to as Tunnel Client.
  • Unified Access Gateway – The virtual appliance where the VMware Tunnel edge service is installed, and to which the tunnel client connects.
  • Per-App Tunnel – Component of VMware Tunnel edge service for connecting to a secure tunnel channel on a per-application basis, which is controlled and configured by the VPN profile payload and Device Traffic Rules.
  • Per-App VPN Profile and Device Traffic Rules – The Workspace ONE UEM configuration is pushed to the device that contains the Per-App Tunnel configurations. Every time a specified application is opened, the Workspace ONE Tunnel client evaluates the Device Traffic Rules assigned to it before making any routing decisions and establishes a Per-App tunnel connection with the Unified Access Gateway based on the Per-App VPN Profile configuration.

High-Level Architecture

A picture containing text, diagram, font, screenshot

Description automatically generated

The device contains the applications required by the end-user to perform their daily job. Some applications require access to internal resources to function. Those applications, based on Per-App VPN configuration, use Workspace ONE Tunnel which communicates with the Tunnel Service on Unified Access Gateway hosted on the DMZ, to validate if the device requesting access is in compliance or not before authorizing access through the internal resource.

Prerequisites

Before you can configure the Per-App Tunnel component for iOS, you must have the following components installed and configured:

  • Workspace ONE UEM version 2011 and later
  • iOS 10.3+ device enrolled in Workspace ONE UEM
  • VPN Tunnel must be configured before you can add it as an application
  • Workspace ONE Tunnel application for iOS
    • Deploy Workspace ONE Tunnel using volume purchased licenses from Apple Business Manager or Apple School Manager.
    • Workspace ONE Administrators must upload the Location token from Apple Business Manager to sync licenses to Workspace ONE UEM for managed distribution.

Configuring Device Traffic Rules for iOS

First, because Apple's Mail, Calendar, and Contacts applications may contain both corporate and personal data, administrators must take an extra step to define corporate-owned domains which should be marked for Per-App Tunnel. 

Device traffic rules provide a centralized location to configure which domain traffic uses per-app tunneling. When a Workspace ONE administrator configures devices for Safari on iOS, Workspace ONE automatically merges these parameters into the VPN payload sent to iOS devices. These parameters allow the VMware Tunnel edge service to apply the appropriate device traffic rules for those specific domains.    

Second, Safari is another app that may be used for personal use on a corporate device. As such, Safari cannot be configured to tunnel all traffic. Device traffic rules for Safari must specify the domain and top-level domain component (for example, vmware.com) although an asterisk (*) may be used to wildcard subdomains (for example, *.vmware.com).

Note: Domain values used in this section are examples only. Your values will differ.

In the Workspace ONE UEM console:

  1. Navigate to Groups & Settings > Configurations.
  2. Select Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. From the Device Traffic Rules tile, click Edit.
  4. Click Add or the Default assignment to manage the device traffic rules.
    Administrators can create multiple Device Traffic Rules that will be assigned to the Per-APP VPN profile and will deploy to the devices based on the smart group assigned to the Profile. The first device traffic rule assignment created will be set as default.

    A screenshot of a computer

Description automatically generated 
  5. Observe the default device traffic rule.
    A screenshot of a computer

Description automatically generated
     
    1. Update the Assignment Name with the name of your choice.
    2. Observe (or modify) the default action which applies to all iOS applications selected to use Per-App VPN except Safari:
      1. Tunnel – All apps, except Safari, on the device configured for Per-App Tunnel send network traffic through the tunnel. For example, set the Default Action to Tunnel to ensure all configured apps without a defined traffic rule use the Workspace ONE Tunnel for internal communications.
      2. Block – Blocks all apps, except Safari, on the device configured for Per-App Tunnel from sending network traffic. For example, set the Default Action to Block to ensure that all configured apps without a defined traffic rule cannot send any network traffic regardless of destination.
      3. Bypass – All apps, except Safari, on the device configured for Per-App Tunnel bypass the tunnel and connect to the Internet directly. For example, set the Default Action to Bypass to ensure all configured apps without a defined traffic rule bypass the Workspace ONE Tunnel to access their destination directly.
      4. Proxy – Redirect traffic to the specified HTTPS proxy for the listed domains. The proxy must be HTTPS and must follow the correct format: https://example.com:port.
    3. Click ADD RULE.
  6. Build the device traffic rule.
    A screenshot of a computer

Description automatically generated 
    1. Click the drop-down for the Applications list. Alternatively, select All Applications to apply the rule to all iOS applications listed in the drop-down, which are the ones that you assigned the Per-App VPN profile.
    2. Select one or more iOS apps for which this rule applies.
    3. Enter one or more destinations to control via Workspace ONE Tunnel.
    4. Select the Action to apply for the selected apps when they attempt to access the specified destinations.

For more information on the formats (wildcards, IP, ports) allowed into the Destination field, see the Device Traffic Rules Destination formats supported chapter.

Tip:  iOS apps are automatically added to the Applications selection list after you enable an application for Per-App Tunnel when creating assignments in Resources.

Note: Wildcards must follow one of these formats:

  • *.<domain>.*
  • *<domain>.*
  • *.* — You cannot use this wildcard for Safari rules.
  • * — You cannot use this wildcard for Safari rules.
  1. Add additional rules and publish.

    A screenshot of a computer

Description automatically generated 
    1. Click Add Rule and repeat step 6 for any additional required rules.
    2. Drag the rules to adjust your Device Traffic Rules priority.
    3. After the Device Traffic Rules are configured as necessary, click Save and Publish.

Distributing Workspace ONE Tunnel for iOS

Workspace ONE Tunnel is an iOS application available for free on the App Store. It is also available for managed distribution volume licensing through Apple Business Manager and Apple School Manager. In both cases, the Workspace ONE Tunnel app can be deployed over-the-air through Workspace ONE UEM as a:

         Public App - this method pushes the application to the device from App Store and is recommended when your organization doesn't use Apple VPP program.

         Purchased App - Workspace ONE Tunnel app is free, however, it is also available for managed distribution volume licensing through Apple Business Manager and Apple School Manager. Use device-based licensing to distribute Workspace ONE Tunnel to corporate-managed iOS devices. If your organization has access to Apple Business Manager and you want to manage the license distribution, use this method.

This section demonstrates how to obtain Workspace ONE Tunnel and assign it to devices as Public or Purchased App.

Note: The VPN tunnel profile should already be configured as part of the Prerequisites.

Distribute Workspace ONE Tunnel as Public App (Apple Store)

  1. Add Workspace ONE Tunnel as public app.

    A screenshot of a computer

Description automatically generated 
    1. In the Workspace ONE UEM console, navigate to Resources > Native > Public > Add Application.
  2. Search for Workspace ONE Tunnel on the Apple store.

    A screenshot of a computer

Description automatically generated 
    1. Select Apple iOS as Platform.
    2. Select Search App Store for Source.
    3. Enter Workspace ONE Tunnel.
    4. Click Next.
  3. From the search result, click select for Tunnel – Workspace ONE.

    A close up of text

Description automatically generated 
  4. Save and add the assignment.

    A screenshot of a computer

Description automatically generated 
    1. Select Business (System) for the Categories; this is not required; however it will show the Tunnel app under the specific category in the Intelligence Hub Catalog.
    2. Click Save & Assign.
  5. Define the Assignment.

    A screenshot of a computer

Description automatically generated

    A screenshot of a computer

Description automatically generated 
    1. Enter All Devices for Name.
    2. Select All Devices for Assignment Groups or a specific group of devices that you want to target for the tunnel deployment.
    3. Select Auto for App Delivery Method.
    4. Click Restrictions.
    5. Turn ON the Make App MDM Managed if User Installed.
    6. Click Create.
  6. Click Save, and then click Publish.

Distribute Workspace ONE Tunnel as Purchased App (Apple Business Manager)

  1. Get Workspace ONE Tunnel licenses.

    A screenshot of a computer

Description automatically generated 
    1. In Apple Business Manager (or Apple School Manager), click Apps and Books.
    2. Search for workspace tunnel in the search text box.
    3. Select Tunnel - Workspace ONE for iOS.
    4. Select the location for which you have uploaded the sToken into Workspace ONE UEM.
    5. Enter the quantity of licenses you want to purchase.
    6. Click Get. The button changes to Purchasing and when the purchase is complete changes back to Get.
  2. Sync assets in Workspace ONE UEM.

    A screenshot of a computer

Description automatically generated 
    1. In the Workspace ONE UEM console, click Resources.
    2. Expand Apps and click Native.
    3. Select Purchased.
    4. Click Sync Assets.
    5. Click OK on the dialog box.
    6. Wait a few moments and click Refresh to update the app list.
    7. Click the Workspace ONE Tunnel app for iOS in the app list.
  3. Enable device assignment.
    1. Click Enable Device Assignment.
    2. Click OK to confirm device-based licensing.
    3. Click Save & Assign.
  4. Click Add Assignment.
  5. Edit Assignment.

    A screenshot of a computer

Description automatically generated 
    1. Click Add Assignment.
    2. Select an Assignment Group (or alternatively, create a new smart group containing the targeted devices).
    3. Enter a number of licenses to allocate. Allocate up to the total number of unallocated licenses.
    4. Select Auto.
    5. Click Save.
  6. Save Assignment.
    1. If more assignments are necessary, click Add Assignment and repeat the steps in Edit Assignment.
    2. Click Save and Publish, then click Publish when all assignments have been added.

Creating Per-App VPN Profile for iOS

For iOS 7+ devices and Android Enterprise devices, you can force selected applications to connect through your corporate VPN. Your VPN provider must support this feature, and you must publish the applications as managed applications.

In this exercise, you configure the iOS profile which configures the tunnel client on the device to allow only designated applications to access content on internal servers.

  1. To add a new profile, click Add and then click Profile.
  2. Select Apple iOS.
  3. Select Device Profile.
  4. Configure General profile settings.

    A screenshot of a computer

Description automatically generated 
    1. Enter the name, such as Per-App VPN in this example screenshot.
    2. Select the name of your device's smart group, and select that group. For example, select All Devices (your@group.shown.here) as the assigned Smart Group.
    3. Click VPN then click Configure.
  5. Configure the VPN payload.

    A screenshot of a computer

Description automatically generated 
    1. Select Workspace ONE Tunnel from the Connection Type drop-down menu.
    2. Select Default as the Device Traffic Rules that will be assigned to this profile.
    3. Ensure the Enable VMware Tunnel is selected.
    4. Add any Mail, Contacts, and Calendar Domains. Do not configure Safari Domains - these are configured in the VMware Tunnel Configuration later in this guide.
    5. Click Save & Publish then click Publish.

Note: Safari Domains should be configured in the Device Traffic Rules for Workspace ONE Tunnel.

Configuring Workspace ONE Web for Per-App Tunnel

Workspace ONE Web is part of the secure productivity app suite from VMware. Administrators can deploy Workspace ONE Web when data loss and copy/paste restrictions are critical to the business use case. In this exercise, you distribute and configure Workspace ONE Web for Per-App Tunnel on iOS.

This section demonstrates how to obtain Workspace ONE Web and assign it to devices as Purchased App using the integration of Workspace ONE UEM and Apple Business Manager.

Workspace ONE Web is available for free on App Store. To deploy as a Public App managed by Workspace ONE UEM, follow the same steps described in the previous chapter to deploy Workspace ONE Tunnel.

  1. Get Workspace ONE Web licenses. In Apple Business Manager (or Apple School Manager):

    A screenshot of a computer

Description automatically generated 
    1. Click Apps and Books.
    2. Search for Workspace ONE Web in the search text box.
    3. Select Web - Workspace ONE for iOS.
    4. Choose the location for which you have uploaded the sToken into Workspace ONE UEM.
    5. Enter the quantity of licenses you want to purchase.
    6. Click Get. The button changes to Purchasing and when the purchase is complete, it changes back to Get.
  2. Sync assets in Workspace ONE UEM.

    A screenshot of a computer

Description automatically generated 
    1. In the Workspace ONE UEM console, click Resources.
    2. Expand Applications and click Native.
    3. Click Purchased.
    4. Click Sync Assets.
    5. Click OK on the dialog box.
    6. Wait a few moments and click Refresh to update the app list.
    7. Click the Web - Workspace ONE app for iOS in the app list.
  3. Enable device assignment.

    A screenshot of a computer

Description automatically generated 
    1. Click Enable Device Assignment.
    2. Click OK to confirm device-based licensing.
    3. Click Save & Assign.
  4. Click Add Assignment.
  5. Edit assignment.

    A screenshot of a computer

Description automatically generated 
    1. Click Add Assignment.
    2. Select an Assignment Group (or alternatively, create a new smart group containing the targeted devices).
    3. Enter a number of licenses to allocate. Allocate up to the total number of unallocated licenses.
    4. Select Auto for Assignment Type.
    5. Select Enabled for Remove on Unenroll.
    6. Select Enabled for Prevent Application Backup.
    7. Select Enabled for Make App MDM Managed if User Installed.
    8. Select Enabled and then select the Per-App VPN profile created in Creating Per-App VPN Profile for iOS.
    9. Click Save.
  6. Save assignment.
    1. If more assignments are necessary, click Add Assignment and repeat the steps in Edit Assignment.
    2. Click Save and Publish, then click Publish when all assignments have been added.

Testing Safari Domains with Per-App Tunnel

Now that the VPN profile includes a domain in the Safari Domains list, you can confirm that these settings have updated on the device and test the settings in the native Safari application.

  1. Tap Settings.
  2. Open VPN settings.

    A screenshot of a computer

Description automatically generated 
    1. Tap General and scroll down to the VPN section.
    2. Tap VPN.
  3. Tap VPN Configuration from your Per-App VPN profile.
  4. Verify included Per-App VPN apps.

    A screenshot of a computer

Description automatically generated 
    1. All managed applications from the Workspace ONE UEM Console that are enabled to use Per-App VPN and have an associated Device Traffic Rule appear in this list. Note that Safari is displayed to show that domains are configured for tunneling in Safari.
  5. Next, tap the Safari icon. The VPN icon should not be displayed in the toolbar.
  6. Browse to the internal URL.

    A blue and green squares with a blue box

Description automatically generated with medium confidence 
    1. Enter the URL for a website that is accessible only through VPN.
    2. Confirm that the VPN indicator is displayed when iOS launches the VPN and connects.
    3. Confirm that the internal page loads.

Testing Per-App Tunnel on iOS

Now that the enrolled device has received the settings configured in the Workspace ONE UEM Console, you are ready to begin testing the Per-App Tunnel functionality. The applications assigned in the previous exercises should push down during enrollment. The VMware Tunnel and Workspace ONE Web applications should be installed on your device.

In this exercise, launch Workspace ONE Web and access the internal website. Then verify that, although the VPN connection is active, other applications on the device cannot access the tunnel or internal resources.

  1. Launch Workspace ONE Web.
    1. Press the Home button on your device to return to the Launchpad. Swipe right to see the downloaded applications, if needed.
    2. Tap the Workspace ONE Web icon to launch the application. If prompted, select OK to allow the Web to send your device push notifications.
  2. Create and confirm password.
    1. If prompted, create a passcode for Workspace ONE Web.
    2. Click Next.
    3. Confirm the passcode by entering it again.
    4. Click Confirm.
  3. Tap I understand to accept the Privacy prompt.
  4. Tap I agree to accept the Data sharing prompt.
  5. Access the internal website with Workspace ONE Web.

    A screenshot of a computer

Description automatically generated 
    1. When the application launches, enter the URL for your intranet website.
    2. Confirm that the VPN icon appears, indicating the connection is active. The application now connects to Workspace ONE UEM and retrieves the settings for your Organization Group.
    3. Confirm that the website loads.

Note: Depending on the Workspace ONE Web and SDK settings configured at your particular organization group level, the address bar may not be editable. This configuration is called Kiosk Mode. To work around this, there are two options which can be configured at  Groups & Settings > Configurations > Workspace ONE Web:

  • Click the Bookmarks tab, click Override (if necessary), click Add Bookmark, enter a name and URL for the testing URL, and click Save.
  • Scroll the settings to Kiosk Mode and click Disabled. Click Save.

These changes affect the Default settings for Workspace ONE Web in this Organization Group and all inherited organization groups unless otherwise configured.

Troubleshooting the Workspace ONE Tunnel on iOS

This section contains some basic steps to troubleshooting Per-App Tunnel on iOS.

  1. On an enrolled iOS device, tap Tunnel.

    A screenshot of a computer

Description automatically generated 
  2. Tap Continue.
  3. Tap I understand to accept the Privacy prompt.
  4. Tap I agree to accept the Data sharing prompt.
  5. Validate device connectivity.

    A screenshot of a computer

Description automatically generated 
    1. Ensure the device and Internet connectivity are OK (showing a green check mark symbol).
    2. Tap the logging icon.
  6.  Activate the Enable debug toggle.

    A screenshot of a computer

Description automatically generated 

Tip: With Enable Debug turned on, Workspace ONE administrators can view logging information for the iOS device as follows:

  1. Plug the iOS device into a device running macOS.
  2. Ensure the iOS device trusts the connection to macOS.
  3. Connect to Console, by either:
    1. Open Apple Configurator 2 and double-click the test iOS device. Click Console to view the output from the device.
    2. Open Console.app and select the iOS device from the left side.
  4. Search for tunnel or iOSAppProxyProvider.

Deploying Workspace ONE Tunnel for macOS

Per-App Tunneling helps users to access critical information using applications on their devices from their devices. Mobile flows help users perform business-critical tasks from a single app — streamlining the user experience.

Leveraging Per-App Tunnel allows you to control which applications are on a device and what internal resources the applications have access to by automatically activating or deactivating Per-App VPN access, based on which applications are active. By enabling remote access, you no longer need to provide a device-wide VPN on your devices, which can allow unintended or unauthorized apps or processes to access your VPN. In this tutorial, you configure and deploy VMware Workspace ONE Tunnel to enable the Per-App Tunnel component on managed devices.

These exercises involve the following components:

  • Workspace ONE Tunnel – The app used on the device to securely connect to the Unified Access Gateway to provide Per-App Tunnel functionality, also referred to as Tunnel Client.
  • Unified Access Gateway – The virtual appliance where the VMware Tunnel edge service is installed, and to which the tunnel client connects.
  • Per-App Tunnel – Component of VMware Tunnel edge service for connecting to a secure tunnel channel on a per-application basis, which is controlled and configured by the VPN profile payload and Device Traffic Rules.
  • Per-App VPN Profile and Device Traffic Rules – The Workspace ONE UEM configuration is pushed to the device that contains the Per-App Tunnel configurations. Every time a specified application is opened, the Workspace ONE Tunnel client evaluates the Device Traffic Rules assigned to it before making any routing decisions and establishes a Per-App tunnel connection with the Unified Access Gateway based on the Per-App VPN Profile configuration.

High-Level Architecture

A diagram of a network

Description automatically generated

The device contains the applications required by the end-user to perform their daily job. Some applications require access to internal resources to function. Those applications, based on Per-App VPN configuration, use Workspace ONE Tunnel which communicates with the Tunnel Service on Unified Access Gateway hosted on the DMZ, to validate if the device requesting access is in compliance or not before authorizing access through the internal resource.

Prerequisites

Before you can perform the steps in this exercise, you must have the following components installed and configured:

  • Workspace ONE UEM version 2302 and later
  • macOS Mojave and later enrolled in Workspace ONE UEM
  • The latest version of macOS Tunnel from Apple macOS App Store
    • Deploy Workspace ONE Tunnel using volume purchased licenses from Apple Business Manager or Apple School Manager.
    • Workspace ONE Administrators must upload the Location token from Apple Business Manager to sync licenses to Workspace ONE UEM for managed distribution.

Configuring Device Traffic Rules for macOS

First, because the Apple Mail, Calendar, and Contacts applications might contain both corporate and personal data, administrators must take an extra step to define corporate-owned domains, which should be marked for Per-App VPN. The Mail, Calendar, and Contacts apps do not automatically adhere to device traffic rules. Administrators must specify which domains are corporate-owned by enabling the Mail, Contacts, and Calendar domains parameters in the VPN profile payload. Enabling these parameters in the VPN payload allows VMware Tunnel edge service to apply the appropriate device traffic rules for those specific domains.

Second, Safari is another app that might be used for personal use on a corporate device. As such, Safari cannot be configured to tunnel all traffic. Device traffic rules for Safari must specify the domain and top-level domain component (for example, vmware.com), although an asterisk (*) may be used to wildcard subdomains (for example, *.vmware.com).

Note: Domain values used in this section are examples only. Your values will differ.

  1. Access configurations.
    1. In the Workspace ONE UEM console, click Groups & Settings.
    2. Click Configurations.
  2. Scroll through the list of configurations and select Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. Edit Device Traffic Rule sets.
    1. From within the Device Traffic Rules information block on the Tunnel Configuration page, click Edit.
  4. Add or modify device traffic rule set.

    A screenshot of a computer

Description automatically generated

    Introduced in Workspace ONE UEM 2011, Device Traffic Rule Sets expand the functionality of device traffic rules allowing for granular assignment of rule sets to different groups of users and devices. Device Traffic Rule Sets are assigned when creating the per-app VPN profile in a later step.

    To get started with Device Traffic Rule Sets, perform the following in the Manage Traffic Assignments screen:
    1. If no other Device Traffic Rule Sets exist (or a new rule set is required), click Add to create a new Device Traffic Rule Set.
    2. If modifications to an existing rule set are required, click the Device Traffic Rule Set name.
  5. Enter a name for the Device Traffic Rule Set (or if necessary, modify the name of an existing rule set).
  6. Click Manage Applications.

    A screenshot of a computer

Description automatically generated 
  7. Click Add to add a new application for device traffic rules.
  8. Define the application.

    A screenshot of a computer

Description automatically generated 
    1. Select macOS for Platform.
    2. Enter the friendly name of the application, for example, Firefox Browser. The friendly name is displayed in the Device Traffic Rule.
    3. Enter the application's package id, which is the Identifier value displayed by running the command:
      codesign -dv --entitlements - /path/to.app
    4. Enter the application's designated requirement, which is displayed to the right of the  => sign of the following command: codesign -d -r- /path/to.app
    5. For macOS 10.15 (Catalina) and later, enter a path if creating a device traffic rule for a binary or command-line utility bundled within an application. For example, the executable vmware-remotemks must be allowlisted with path details along with the VMware Horizon Client application.
    6. Click Save.

Using Firefox as an example, a Workspace ONE administrator would see the commands and values as follows:

techzone@testmac ~ % codesign -dv --entitlements - /Applications/Firefox.app
Executable=/Applications/Firefox.app/Contents/MacOS/firefox
Identifier=org.mozilla.firefox
Format=app bundle with Mach-O thin (x86_64)
CodeDirectory v=20500 size=415 flags=0x10000(runtime) hashes=4+5 location=embedded
Signature size=9018
Timestamp=Oct 1, 2019 at 9:08:41 PM
Info.plist entries=26
TeamIdentifier=43AQ936H96
Runtime Version=10.11.0
<<< trimmed for length >>>
techzone@testmac ~ % codesign -d -r- /Applications/Firefox.app
Executable=/Applications/Firefox.app/Contents/MacOS/firefox
designated => anchor apple generic and certificate leaf[field.1.2.840.113635.100.6.1.9] /* exists */ or anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "43AQ936H96"

As highlighted in the terminal output, the necessary information is as follows:

Package ID: org.mozilla.firefox

Designated Requirement: anchor apple generic and certificate leaf[field.1.2.840.113635.100.6.1.9] /* exists */ or anchor apple generic and certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "43AQ936H96"

Caution: Some apps spawn helper applications to assist with background tasks. One particular example of this is Google Chrome, which performs network functions outside the Google Chrome.app process in a Google Chrome Helper process. In this case, the helper application must be added to the Device Traffic Rule, otherwise, specific settings must be changed client-side.  

In the case of Google Chrome, perform the following:

  • In the URL field, type chrome://flags
  • Search for network in the Search Flags text box.
  • Set Runs network service in-process to Enabled and relaunch Google Chrome before proceeding with testing.
  1. Add new application for device traffic rules.

    A screenshot of a computer

Description automatically generated 
    1. If more applications are needed for the rule set, click Add and repeat starting at Define the Application.
    2. If all the required applications have been defined, click the [X] to close the Manage Applications window.
  2. Add device traffic rule.

    A screenshot of a computer

Description automatically generated 
    1. Observe (and optionally modify) the default action which applies to all macOS applications except Safari:
      1. Tunnel – All apps, except Safari, on the device configured for Per-App Tunnel send network traffic through the tunnel. For example, set the Default Action to Tunnel to ensure all configured apps without a defined traffic rule use the Workspace ONE Tunnel for internal communications.
      2. Block – Blocks all apps except Safari, on the device configured for Per-App Tunnel from sending network traffic. For example, set the Default Action to Block to ensure that all configured apps without a defined traffic rule cannot send any network traffic regardless of destination.
      3. Bypass – All apps, except Safari, on the device configured for Per-App Tunnel bypass the tunnel and connect to the Internet directly. For example, set the Default Action to Bypass to ensure all configured apps without a defined traffic rule bypass the Workspace ONE Tunnel to access their destination directly.
      4. Proxy - Redirect traffic to the specified HTTPS proxy for the listed domains. The proxy must be HTTPS and must follow the correct format: https://example.com:port.
    2. Click Add Rule.
  3. Build device traffic rule.

    A screenshot of a computer

Description automatically generated 
    1. In the newly created device traffic rule, click the down arrow to display the Application list.
    2. Select one or more triggering applications to control with this rule. In case you select All Applications, the rule will be applied only to Safari and macOS applications selected in additional rules defined as part of the Device Traffic Rules.
    3. Enter one or more comma-separated fully qualified domain names as destinations to which Workspace ONE Tunnel should apply the Device Traffic Rule. A single asterisk (*) can be used as a wildcard for subdomains.
    4. Select the Appropriate Action for Workspace ONE Tunnel to perform on traffic from the selected apps:
      1. Tunnel – Sends app network traffic for specified domains through the tunnel to your internal network.
      2. Block – Blocks all traffic sent to specified domains.
      3. Bypass – Bypasses the Workspace ONE Tunnel so the application accesses specified domains directly.
      4. Proxy – Redirect traffic to the specified HTTPS proxy for the listed domains. The proxy must be HTTPS and must follow the correct format: https://example.com:port.
    5. If necessary, adjust the Device Traffic Rules rank in the list. Lower-numbered rank is the highest priority.
    6. If necessary, click Add Rule and repeat steps in Build Device Traffic Rule until you have added all the necessary Device Traffic Rules for your organization.
    7. Click Save and Publish to send the updated DTR's to all devices to which the DTR is assigned.

For more information on the formats (wildcards, IP, ports) allowed into the Destination field, see the Device Traffic Rules Guidelines and use of asterisk chapter.

Distributing Workspace ONE Tunnel for macOS

Workspace ONE Tunnel is a macOS application available for free on the Mac App Store. It is also available for managed distribution volume licensing through Apple Business Manager and Apple School Manager. Use device-based licensing to distribute Workspace ONE Tunnel to managed macOS devices. This section demonstrates how to purchase Workspace ONE Tunnel and assign it to devices.

Note: The VPN tunnel should already be configured as part of the Prerequisites.

  1. Get Workspace ONE Tunnel licenses.

    Screens screenshot of a computer

Description automatically generated 
    1. In Apple Business Manager (or Apple School Manager), click Apps and Books.
    2. Search for workspace tunnel in the search text box.
    3. Select Tunnel - Workspace ONE for macOS.
    4. Choose the location for which you have uploaded the sToken into Workspace ONE UEM.
    5. Enter the quantity of licenses you want to purchase.
    6. Click Get. The button changes to Purchasing and when the purchase is complete changes back to Get.
  2. Sync assets in Workspace ONE UEM.

    A screenshot of a computer

Description automatically generated 
    1. In the Workspace ONE UEM console, click Resources.
    2. Expand Applications and click Native.
    3. Click Purchased.
    4. Click Sync Assets.
    5. Click OK on the dialog box.
    6. Wait a few moments and click Refresh to update the app list.
    7. Click the Workspace ONE Tunnel app in the app list.
  3. Enable device assignment.

    A screenshot of a computer

Description automatically generated 
    1. Click Enable Device Assignment and click OK for the Are you sure? prompt.
    2. Click Save & Assign.
  4. Click Add Assignment.
  5. Edit assignment.

    A screenshot of a login

Description automatically generated 
    1. Enter a name for the Distribution
    2. Select an Assignment Group (or alternatively, create a new smart group containing the targeted devices).
    3. Enter a number of licenses to allocate. Allocate up to the total number of unallocated licenses.
    4. Select Auto for Assignment Type.
    5. Click Create.
  6. Save assignment.
    1. If more assignments are necessary, click Add Assignment and repeat the steps in Edit Assignment.
    2. Click Save and then Publish when all assignments have been added.

Creating Per-App VPN Profile for macOS

Before device traffic rules take effect on macOS, Workspace ONE administrators must deploy a VPN profile payload that configures macOS to leverage Workspace ONE Tunnel. In this exercise, you create the macOS profile which configures the tunnel client on the device to allow only designated applications to access content on internal servers.

  1. To add a new profile, click Add and then click Profile.

    A screenshot of a computer

Description automatically generated 
  2. Select macOS.
  3. Select User Profile.
  4. Configure General profile settings.

    A screenshot of a computer

Description automatically generated 
    1. Enter a name for the profile, for example, Per-App VPN.
    2. Select Auto as the assignment type.
    3. Select one or more Smart Groups to assign the VPN profile (or create a new smart group).
    4. Click the VPN payload then click Configure.
  5. Configure VPN payload.

    A screenshot of a computer

Description automatically generated 
    1. Enter a name for the Per-App VPN Connection, for example, VMware Per-App VPN.
    2. Select Workspace ONE Tunnel as the Connection Type.
    3. Choose the Device Traffic Rule Set (as configured in Configuring Device Traffic Rules for macOS) to be assigned via this Profile Payload.
    4. If required, select the check boxes for Enable Mail Domains, Enable Contacts Domains, and Enable Calendar Domains.
    5. For each check box, enter a domain that should be tunneled.
    6. If multiple domains are required, click Add to enter an additional domain. Repeat as necessary.
    7. Click Save and Publish.
  6. Click Publish.

Testing Per-App Tunnel on macOS

With the settings configured in the Workspace ONE UEM Console, administrators can test the Per-App Tunnel functionality on an enrolled device. The Workspace ONE Tunnel assigned in the previous exercises should install automatically during enrollment. As part of testing, the applications defined in the Device Traffic Rules should be deployed as described in Deploying Third-Party macOS Applications: VMware Workspace ONE Operational Tutorial.

As a reminder, the prerequisites for testing Per-App Tunnel on macOS include the following:

  • Tunnel Edge Service configured on Unified Access Gateway
  • Device Traffic Rules configured in Workspace ONE UEM
  • Workspace ONE Tunnel and additional apps defined in Define Traffic Rules deployed to an enrolled device running macOS
  • A valid endpoint that is not accessible to the apps on the device except via per-app Tunnel

Validate Per-App Tunnel based on Device Rules

  1. Open an app specified in a Device Traffic Rule and ensure the application attempts to connect to the mapped domain name(s).
  2. Open an app that is not specified in a Device Traffic Rule, such as Safari (which will not adhere to the default Device Traffic Rule due to the wildcard mapping). Ensure the same mapped domain name does not work.

    A screenshot of a computer

Description automatically generated 

In the section of this tutorial where device traffic rules were created for macOS, Firefox was the allowed application. In the screenshot, note that Firefox is launched and attempted connection to an approved (wildcard) destination (#1). Also, observe that Safari (which was not granted access to the tunnel) cannot connect to the endpoint.

Extending Tunnel Configuration for Kerberos SSO Extension in macOS

With macOS Catalina, Apple introduced a new single sign-on (SSO) extension framework and included a built-in Kerberos SSO extension. The Kerberos SSO extension syncs passwords between a user's account in Active Directory and the local macOS account. It also brings Kerberos SSO functionality directly into the OS via MDM-manageable payloads. This tutorial aims to help experienced Workspace ONE administrators to configure the Kerberos SSO extension for macOS Catalina, and enable off-network access for the extension through per-app tunneling.

IMPORTANT: This document is provided as a courtesy to aid anyone wishing to test the functionality. This document was created around the time macOS Catalina was released. Kerberos Ticketing worked as expected at that time, but the Kerberos SSO Extension had a known bug that prevented AD password sync and change over per-app tunnel. Since then, the Kerberos SSO Extension has continued to work for network-connected devices. 

However, Kerberos SSO over per-app tunneling has been in varying states of functioning depending on major, minor, and development builds of the OS. We encourage customers interested in this functionality to test and file feedback with Apple (using Apple's Feedback Assistant) and also with VMware.

Software Prerequisites

Configuration Prerequisites

Before using this section of the tutorial, Workspace ONE administrators must ensure the following software version prerequisites are met:

  • Workspace ONE UEM version 2302+
  • macOS Catalina 10.15.0+  

Optionally, if configuring the SSO Extension to use Per-App Tunnel, administrators should meet these additional prerequisites:

  • Unified Access Gateway 3.8+
  • VMware Tunnel app for macOS version 4.1+

Before using this section of the tutorial, Workspace ONE administrators must complete the following types of configurations within their environment:

  • Microsoft Active Directory
  • Internal Websites or applications configured for Kerberos Authentication
    • Microsoft IIS should be configured for Windows Authentication with Negotiate as the primary enabled provider. When connecting to the IIS-hosted site from a web browser configured in the Device Traffic Rule, the browser should prompt for Username/Password prior to completion of this section as macOS should have no Kerberos awareness.

 

Validate No Pre-existing Kerberos Tickets

  1. Press CMD+SpaceBar (+Space) and enter terminal into the Finder window.
  2. Select Terminal to open Terminal.app.
  3. Enter klist and press Return on the keyboard.
  4. Ensure that there are no Kerberos Tickets and the command returns No credentials cache file found.

    A screenshot of a computer

Description automatically generated 

Validate Kerberos Application or Website Fails

  1. Launch an application which should be Kerberos-enabled. If using a website, browse to the Kerberos-enabled website.

    A screenshot of a computer

Description automatically generated 
  2. Note that authentication either fails (as there are no Kerberos tickets) or reverts to a non-Kerberos authentication type (such as certificate authentication or username/password).

Define the Kerberos Extension in Device Traffic Rules

To connect the SSO Kerberos Extension over Per-App Tunnel, you must add the appropriate device traffic rules to the Tunnel configuration to support this. This section covers how to add the appropriate device traffic rules.

  1. Access configurations.
    1. In the Workspace ONE UEM console, click Groups and Settings.
    2. Click Configurations.
  2. Scroll through the list of configurations and select Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. Edit Device Traffic Rule sets.
    1. From within the Device Traffic Rules information block on the Tunnel Configuration page, click Edit.
  4. Add or modify device traffic rule set.

    A screenshot of a computer

Description automatically generated

    Introduced in Workspace ONE UEM 2011, Device Traffic Rule Sets expand the functionality of device traffic rules allowing for granular assignment of rule sets to different groups of users and devices. Device Traffic Rule Sets are assigned when creating the per-app VPN profile in a later step.

    To get started with Device Traffic Rule Sets, perform the following in the Manage Traffic Assignments screen:
    1. If no other Device Traffic Rule Sets exist (or a new rule set is required), click Add to create a new Device Traffic Rule Set.
    2. If modifications to an existing rule set are required, click the Device Traffic Rule Set name.
  5. Enter a name for the Device Traffic Rule Set (or if necessary, modify the name of an existing rule set).

    A screenshot of a computer

Description automatically generated 
  6. Click Manage Applications.
  7. Click Add to add a new application for device traffic rules.
  8. Define the application.

    A screenshot of a computer

Description automatically generated 
    1. Select macOS for Platform.
    2. Enter the friendly name of the application, for example, Kerberos SSO Extension. The friendly name is displayed in the Device Traffic Rule.
    3. Enter the application's package id (com.apple.AppSSOKerberos.KerberosExtension), which is the Identifier value displayed by running the command:

      codesign -dv --entitlements - /System/Library/PrivateFrameworks/AppSSOKerberos.framework/PlugIns/KerberosExtension.appex/Contents/MacOS/KerberosExtension
    4. Enter the application's Designated Requirement (identifier "com.apple.AppSSOKerberos.KerberosExtension" and anchor apple), which is displayed to the right of the  => sign of the following command:

      codesign -d -r - /System/Library/PrivateFrameworks/AppSSOKerberos.framework/PlugIns/KerberosExtension.appex/Contents/MacOS/KerberosExtension
    5. Enter the following path:

      /System/Library/PrivateFrameworks/AppSSOKerberos.framework/PlugIns/KerberosExtension.appex/Contents/MacOS/KerberosExtension
    6. Click Save.
  9. Define additional applications (macOS BigSur and later).

    For macOS Big Sur and later, follow the same process defined in Add macOS Application to Rule Builder and Define the Application, configure these additional applications. These additional configurations allow the full functionality of the Kerberos SSO Extension with regards to Active Directory password sync and change.

    AppSSOAgent:
    1. Platform:  macOS
    2. Friendly Name:  Kerberos SSO AppSSOAgent
    3. Package ID:  com.apple.AppSSOAgent
    4. Designated Requirement:  identifier "com.apple.AppSSOAgent" and anchor apple
    5. Path:  /System/Library/PrivateFrameworks/AppSSO.framework/Support/AppSSOAgent.app/Contents/MacOS/AppSSOAgent

KerberosMenuExtra:

  1. Platform:  macOS
  2. Friendly Name:  Kerberos SSO KerberosMenuExtra
  3. Package ID:  com.apple.KerberosMenuExtra
  4. Designated Requirement:  identifier "com.apple.KerberosMenuExtra" and anchor apple
  5. <No Path Required>
  1. Add device traffic rule.

    A screenshot of a computer

Description automatically generated 
    1. Click Add Rule.
    2. Click the down arrow in the Application column of the new device traffic rule.
    3. Select the three Kerberos SSO Extension apps you defined in the previous steps:
      1. com.apple.AppSSOKerberos.KerberosExtension
      2. com.apple.AppSSOAgent
      3. com.apple.KerberosMenuExtra
    4. Select Tunnel as the action.
    5. Configure destination domain names (include wildcards if needed) that match your domain controllers.
    6. Click Save and Publish.

Configure Kerberos Profile Payload

Next, create the Kerberos profile and configure the SSO extension payload.

  1. Click Add and click Profile.
  2. Select macOS.
  3. Select User Profile.
    Note: The SSO Extension payload is available in both the User and Device context as of Workspace ONE UEM 2011 and later. The choice to use User Profile versus Device Profile will primarily be driven by the certificate used in the payload. In most cases, the certificate/credential should be used from the login keychain, and the Workspace ONE UEM administrator should use a User profile. Otherwise, choose Device Profile to use a certificate/credential from the system keychain.
  4. Configure General Profile details.

    A screenshot of a computer

Description automatically generated 
    1. Enter a name for the profile, for example, Kerberos SSO Extension.
    2. Select Auto as the Assignment Type.
    3. Select one or more Smart Groups to assign the SSO Extension profile (or create a new smart group).
  5. Configure SSO extension payload.

    A screenshot of a computer

Description automatically generated 
    1. Search for the SSO payload.
    2. Click SSO Extension.
    3. Click Configure.
  6. Modify and save SSO extension payload.

    A screenshot of a computer

Description automatically generated 
    1. Select Kerberos for Extension Type.
    2. Enter the Active Directory Realm (in capital letters) where the user logs in. For example, AAPP.XXXX.COM.
    3. Enter the Active Directory hosts and domains that can be authenticated through the extension. For example, aapp.xxxx.com.
    4. Select whether the extension should use active directory and DNS to discover its AD site.
    5. Select whether the extension should save passwords to the keychain.
    6. Select whether the user should be required to use biometrics or a password to use the keychain.
    7. Select the Certificate Credential that should be used for authenticating in the SSO Extension.
    8. Enter a list of application Bundle IDs allowed to use the Kerberos Ticket Granting Ticket.   If more than one app is allowed, click Add to add additional bundle IDs.
    9. Select whether to allow users to initiate directory password changes from the extension.
    10. Select whether to keep the local macOS user account password synchronized with the Active Directory account password.
    11. Select whether passwords must meet Active Directory's definition of complex.
    12. Optionally, scroll down to configure additional parameters with regards to password settings.
    13. Click Save and Publish.
  7. Click Publish to publish the SSO extension profile.

Validate Kerberos Tickets

Finally, log in to Kerberos and confirm that the Kerberos credentials are obtained over Per-App VPN by the Kerberos SSO Extension.

  1. Log in to Kerberos extension.

    A screenshot of a computer

Description automatically generated 
    1. Click the extension (key icon) in the menu bar.
    2. Click Sign In.
    3. Enter a user's username and password.
    4. Click Sign In.
  2. Click Yes to accept automatic sign-in.
  3. Rerun klist command.

    A screenshot of a computer

Description automatically generated 
    1. In Terminal.app, enter klist and press return.
    2. Observe the Kerberos Credential obtained over Per-App VPN by the built-in macOS Catalina Kerberos SSO Extension.
  4. Validate Kerberos-enabled application or website.

    A computer screen shot of a computer

Description automatically generated 
    1. Launch an application which is Kerberos-enabled. If using a website, browse to the Kerberos-enabled website.
    2. Note the application or website is authenticated without any intervention from the user (no certificate chooser or username/password prompt).

Note: Some applications may require additional configuration to enable Kerberos Authentication. Google Chrome and Firefox also require additional configuration to enable Kerberos Authentication.

For Firefox:

  1. Open Firefox and enter about:config in the address bar.
  2. Search for negotiate and then double-click network.negotiate-auth.trust-uris.
  3. Enter a comma-separated list of domain names that should be enabled for Kerberos Authentication and click Ok.
  4. Open a new tab and re-try the Kerberos-enabled website.

For Google Chrome:

  1. Create a Custom Settings payload in a User Profile for the device, targeting com.google.Chrome as the PayloadType.
  2. Include the following keys in your settings:

 <key>AuthServerWhitelist</key>

 <string>*.domain.name</string>

 <key>AuthNegotiateDelegateWhitelist</key>

 <string>*.domain.name</string>

Caution: Some apps spawn helper applications to assist with background tasks. In these cases, the helper apps may be making DNS calls or performing other network tasks requiring the Per-App Tunnel but may not be part of a device traffic rule. One particular example of this is Google Chrome, which performs network functions outside the Google Chrome.app process. In this case, the helper application must be added to the device traffic rule, otherwise, specific settings are required to be changed client-side within the application. 

As an example, to validate Kerberos-enabled websites in Google Chrome using Per-App Tunnel, perform the following:

  1. In the URL field, enter chrome://flags
  2. Search for network in the Search flags text box.
  3. Set Runs network service in-process to Enabled and relaunch Google Chrome before proceeding with testing.

This small change allows Google Chrome to leverage the Per-App Tunnel for connectivity required to query DNS and obtain Kerberos tickets. At the time of writing, the ForceNetworkInProcess key was not available in Chrome for macOS and must be enabled by the individual user.

Troubleshooting Workspace ONE Tunnel on macOS

If a Per-App Tunnel problem occurs on macOS, there are a number of places to troubleshoot. This section of the tutorial covers where to troubleshoot on macOS at a high level. Depending on the problem, there might be steps that should be performed on the Unified Access Gateway. However, troubleshooting the Unified Access Gateway is outside the scope of this tutorial. Workspace ONE UEM administrators should contact VMware Support for assistance when troubleshooting Per-App Tunnel, Workspace ONE Tunnel, or the Unified Access Gateway.

This section covers a high-level set of initial troubleshooting steps.

To begin, open Workspace ONE Tunnel. Click Launchpad and click VMware Tunnel.

A screenshot of a computer

Description automatically generated

Ensure Tunnel is Configured

  1. Ensure that the Device Configured status shows Configured. This indicates that Workspace ONE Tunnel has received configuration data from Workspace ONE UEM. If the status is not configured, try one of the following:

    A screenshot of a computer

Description automatically generated 
    1. Check the Device Traffic Rules and Save and Publish the rules again.
    2. Check the last seen value for the device in the Workspace ONE UEM console. Is the device communicating with Workspace ONE UEM?
    3. Validate that other MDM commands are being sent to the device. Create an assignment (smart) group containing the single device and attempt to send it a new profile payload.
  2. Ensure that the Internet status shows Connected. If Tunnel cannot connect to the Internet, it probably cannot connect to the Unified Access Gateway.
    1. Validate that the device has a working Ethernet or Wi-Fi connection (IP address, subnet mask, gateway, and DNS addresses are present).
    2. Validate DNS resolution: Open Terminal and enter nslookup uag.fully.qualified.domain to ensure that an IP address is resolved.
    3. Validate Connectivity to UAG: Within Terminal, enter nc -vz uag.fully.qualified.domain uagport (such as nc -vz uag.company.com 443).
  3. Ensure that the Enterprise Network status shows Connected. If Workspace ONE Tunnel is disconnected from the Enterprise network, apps cannot use Per-App Tunnel. This might indicate an issue with Workspace ONE Tunnel connecting to the Unified Access Gateway or an issue with Device Traffic Rules.

The remainder of this section details how to troubleshoot Tunnel connectivity.

Validate Per-App VPN Profile

  1. Click System Preferences.

    A screenshot of a computer

Description automatically generated 
  2. Double-click Profiles.
  3. Scroll through the left panel.
  4. Click the Per-App VPN profile that was created.
  5. Ensure that the VPN App Layer Service details are correct, especially the VPN Remote Address and the OnDemand Enabled value.
    1. If the profile is missing or misconfigured, check the profile configuration and re-push the profile to the device from within the UEM Console Device Details view (on the Profiles tab).

Validate Advanced Tunnel Information

  1. Open the Workspace ONE Tunnel client and click the VMware Tunnel menu.

    A screenshot of a computer

Description automatically generated 
  2. Click Whitelisted Applications.
  3. Verify that the list of allowlisted applications matches the settings configured in the Device Traffic Rules.
  4. From the VMware Tunnel menu (#1), click Diagnostics.
  5. Click Enable Debug to get verbose information.
  6. Review Diagnostics information.
  7. Click Disable Debug when troubleshooting is complete.

Review Tunnel-Related Unified Logging

  1. Press CMD+SpaceBar (+Space) and enter console into the Finder window.

    A screenshot of a computer

Description automatically generated 
  2. Select the Console application.
  3. Enter process:macOSAppProxyProvider into the search bar and press Return on the keyboard.
  4. Without clearing the contents of the search bar, add an additional filter parameter by adding process:VMware Tunnel into the search bar and press Return on the keyboard.
  5. Click the Action menu and confirm that Include Info Messages and Include Debug Messages are selected.
  6. Review the logging produced within the Console application.

Tip: If the console filters do not provide any meaningful data, you can optionally attempt to view information and debug messages from entire subsystems. Some filters that may help include:

  • process:macOSAppProxyProvider
  • any:com.vmware.macos-tunnel

Also, if troubleshooting Kerberos over the Per-App Tunnel, you can include the following console filters:

  • subsystem:com.apple.appsso
  • subsystem:com.apple.appssokerberosextension

The following Terminal command might provide meaningful output:   log stream --debug --predicate '(subsystem == "com.apple.Heimdal") OR (subsystem == "com.apple.AppSSO") OR (subsystem == "org.h5l.gss") OR (subsystem == "com.apple.network") OR (process == "VMware Tunnel") '

General VPN Network Extension Troubleshooting

Per Apple's Developer Website (requires login), you can use the following commands to gather additional data from the VPN (Network Extension):

  • sudo defaults write /Library/Preferences/com.apple.networkextension.control.plist  LogToFile -boolean true 
  • sudo defaults write /Library/Preferences/com.apple.networkextension.control.plist  LogLevel -int 7

Reproduce the issue and then enter this command in Terminal.app:

  • /System/Library/Frameworks/SystemConfiguration.framework/Resources/get-mobility-info

You should find additional information in the resulting get-mobility-info output file.

You can later deactivate the logging by issuing the following commands:

  • sudo defaults delete /Library/Preferences/com.apple.networkextension.control.plist  LogToFile 
  • sudo defaults delete /Library/Preferences/com.apple.networkextension.control.plist  LogLevel

Deploying Workspace ONE Tunnel for Windows Desktop

Per-App Tunneling helps users to access critical information using applications on their devices from their devices. Mobile flows help users perform business-critical tasks from a single app — streamlining the user experience.

Leveraging Per-App Tunnel allows you to control which applications are on a device and what internal resources the applications have access to by automatically activating or deactivating Per-App VPN access, based on which applications are active. By enabling remote access, you no longer need to provide a device-wide VPN on your devices, which can allow unintended or unauthorized apps or processes to access your VPN. In this tutorial, you configure and deploy VMware Workspace ONE Tunnel to enable the Per-App Tunnel component on managed devices.

These exercises involve the following components:

  • Workspace ONE Tunnel – The app used on the device to securely connect to the Unified Access Gateway to provide Per-App Tunnel functionality, also referred to as Tunnel Client.
  • Unified Access Gateway – The virtual appliance where the VMware Tunnel edge service is installed, and to which the tunnel client connects.
  • Per-App Tunnel – Component of VMware Tunnel edge service for connecting to a secure tunnel channel on a per-application basis, which is controlled and configured by the VPN profile payload and Device Traffic Rules.
  • Per-App VPN Profile and Device Traffic Rules – The Workspace ONE UEM configuration is pushed to the device that contains the Per-App Tunnel configurations. Every time a specified application is opened, the Workspace ONE Tunnel client evaluates the Device Traffic Rules assigned to it before making any routing decisions and establishes a Per-App tunnel connection with the Unified Access Gateway based on the Per-App VPN Profile configuration.

High-Level Architecture

A diagram of a network

Description automatically generated

The device contains the applications required by the end-user to perform their daily job. Some applications require access to internal resources to function. Those applications, based on Per-App VPN configuration, use Workspace ONE Tunnel which communicates with the Tunnel Service on Unified Access Gateway hosted on the DMZ, to validate if the device requesting access is in compliance or not before authorizing access through the internal resource.

Prerequisites

Before you can perform the steps in this exercise, you must have the following components installed and configured:

Note: See VMware Workspace ONE Tunnel for Windows Release Notes for updates to the client.

Configuring Device Traffic Rules for Windows

This exercise outlines how to configure device traffic rules for Windows. Before you start this section, read the Device Traffic Rules chapter for a better understanding of how device traffic rules are managed by Workspace ONE Tunnel.

For this example, the user must access internal websites, internal network file shares, and a remote desktop session. To allow secure access, you configure Workspace ONE Tunnel to allow only the applications required.

In this exercise, you configure the following:

  • Internal web browser access - defining Chrome as the application
  • Internal network file shares - allowing system access
  • Remote Desktop Session Connection - defining Microsoft Remote Desktop client as the application

Note: Domain values used in this section are examples only. Your values will differ.

  1. Access configurations.
    1. In the Workspace ONE UEM console, click Groups & Settings.
    2. Click Configurations.
  2. Scroll through the list of configurations and select Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. Edit Device Traffic Rule sets.
    1. From within the Device Traffic Rules information block on the Tunnel Configuration page, click Edit.
  4. Add or modify device traffic rule set.

    A screenshot of a computer

Description automatically generated

    Introduced in Workspace ONE UEM 2011, Device Traffic Rule Sets expand the functionality of device traffic rules allowing for granular assignment of rule sets to different groups of users and devices. Device Traffic Rule Sets are assigned when creating the per-app VPN profile in a later step.

    To get started with Device Traffic Rule Sets, perform the following in the Manage Traffic Assignments screen:
    1. If no other Device Traffic Rule Sets exist (or a new rule set is required), click Add to create a new Device Traffic Rule Set.
    2. If modifications to an existing rule set are required, click the Device Traffic Rule Set name.
  5. Set or modify device traffic rule name and tunnel mode.

    A screenshot of a computer

Description automatically generated 
    1. Enter a name for the Device Traffic Rule Set (or if necessary, modify the name of an existing rule set).
    2. Set the Tunnel Mode to Per Application.

This first tutorial on Windows shows you how to configure device traffic rules based on Per-Application Tunnel Mode. After completing the Windows tutorial return and switch the Tunnel Mode for this rule to Full Device. The Application fields will be removed and you will be required to specify only the actions and destination domains.

  1. Click Manage Applications.
  2. Click Add.
  3. Define the application.

    A screenshot of a computer

Description automatically generated 
    1. Select Windows as the Platform.
    2. Enter the friendly name of the application. The friendly name is displayed in the Device Traffic Rule.
    3. Select the App Type, for example, Desktop App. The App Type can be a traditional Windows application or a Windows Store application.
    4. Enter the App Identifier. For traditional Windows applications, use the File Path. For Store applications, you must enter the Package Family Name or PFN. You can use the PowerShell command Get-AppxPackage to find the PFN. For more information, see Microsoft Docs: Find a package family name (PFN) for per-app VPN.
  4. Add Chrome Web browser access.

    A screenshot of a computer

Description automatically generated 
    1. In this example, the Chrome application is defined under the Program Files (x86) path. The App Identifier value should contain the full path where the EXE file is located on the Windows machine.
    2. The screenshot shows that the App Identifier used for Chrome is C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
    3. After you have entered the application details, click Save.
  5. Add remote desktop (RDP) client.

    A screenshot of a computer

Description automatically generated 
    1. Next, add the Remote Desktop client. This allows end users to connect to Remote Desktop Hosts located behind the corporate firewall.
    2. As the Remote Desktop Client is built into the Windows Operating system, the file path of the executable is different.
    3. For example, in this screenshot, the App Identifier used for the RDP client is C:\Windows\System32\mstsc.exe
    4. After you have entered the application details, click Save.
  6. Add SMB for network drive and printer support.

    A screenshot of a computer

Description automatically generated 
    1. Next, add support for tunneling SMB traffic from the system to allow users to map network shares and network printers. This allows end users to connect to file shares and printers that are located behind the corporate firewall.
    2. As the SMB protocol is built into the Windows Operating system, the App Identifier is not an executable, instead, you define System as the App Identifier.
    3. After you have entered the application details, click Save.
  7. Add more applications to device traffic rules, if required.
    1. If more applications are needed for the ruleset, click Add and repeat starting at Define the Application.
    2. If all the required applications have been defined, click X to close the Manage Applications window.
  8. Add device traffic rule.

    A screenshot of a computer

Description automatically generated 
    1. Observe (and optionally modify) the default action which applies to all Windows applications.
      1. Tunnel – All apps on the device configured for Per-App Tunnel send network traffic through the tunnel. For example, set the Default Action to Tunnel to ensure all configured apps without a defined traffic rule use the Workspace ONE Tunnel for internal communications.
      2. Block – Blocks all apps on the device configured for Per-App Tunnel from sending network traffic. For example, set the Default Action to Block to ensure that all configured apps without a defined traffic rule cannot send any network traffic regardless of destination.
      3. Bypass – All apps on the device configured for Per-App Tunnel bypass the tunnel and connect to the Internet directly. For example, set the Default Action to Bypass to ensure all configured apps without a defined traffic rule bypass the Workspace ONE Tunnel to access their destination directly.
    2. Click Add Device Traffic Rule.
  9. Build device traffic rule.
    A screenshot of a computer

Description automatically generated
     
    1. In the newly created traffic rule, Click the down arrow to display the Application list.
    2. Select one or more triggering applications to control with this rule. All Applications not applicable to Windows.
    3. Select the Appropriate Action for Workspace ONE Tunnel to perform on traffic from the selected apps - For this exercise, select Tunnel.
      1. Tunnel – Sends app network traffic for specified domains through the tunnel to your internal network.
      2. Block – Blocks all traffic sent to specified domains.
      3. Bypass – Bypasses the Workspace ONE Tunnel so the application accesses specified domains directly.
      4. Proxy – Redirect traffic to the specified HTTPS proxy for the listed domains. The proxy must be HTTPS and must follow the correct format: https://example.com:port.
      5. Note: Proxy is not yet supported using the Workspace ONE Tunnel Desktop Application.
    4. Enter one or more comma-separated fully qualified domain names as destinations to which Workspace ONE Tunnel should apply the Device Traffic Rule. A single asterisk (*) can be used as a wild card for subdomains.
    5. If necessary, adjust the Device Traffic Rules rank in the list. Lower-numbered rank is the highest priority.
    6. If necessary, click Add Rule and repeat Build Device Traffic Rule until you have added all the necessary Device Traffic Rules for your organization.
    7. Click Save.

For more information on the formats (wildcards, IP, ports) allowed into the Destination field, see the Device Traffic Rules Destination formats supported chapter.

Note: For Windows Desktop devices, if Enhanced Domain Resolution is not enabled on the Per-App VPN profile, the domains added to the destination must also be added to the list of domains part of the DNS Resolution via Tunnel Gateway.

  1. Review the summary of the device traffic rule configurations.
    A screenshot of a computer

Description automatically generated
     
    1. The Application list contains triggering applications Chrome, Remote Desktop, and System.
      1. The applications appear in the following format: Application Friendly Name - UEM Organization Group - Platform
        1. Google Chrome - ACME Corp - WinRT
        2. RDP  - ACME Corp - WinRT
        3. System - ACME Corp - WinRT
    2. The Appropriate Action for Workspace ONE Tunnel to perform is Tunnel.
      1. Tunnel – Sends app network traffic for specified domains through the tunnel to your internal network
      2. Destination - For this example, the domains are *.corp.local and *.airwlab.com
    3. Optional - You can also configure Device Traffic Rules to Block.
      1. In this example, Chrome is set to block domains *.cnn.com, *.facebook.com, and *.match.com.

Distributing Workspace ONE Tunnel for Windows

In this exercise, you deploy the Workspace ONE Tunnel Desktop Application on Windows 10 devices.

Note: The Per-App VPN profile should already be configured as part of the Prerequisites.

  1. Download the Workspace ONE Tunnel desktop installer.

    A screenshot of a computer

Description automatically generated 
    1. Navigate to https://my.workspaceone.com/products and log in with your VMware Customer Connect credentials.
    2. Click View All.
  2. Scroll to the end of the page and select Workspace ONE Tunnel.

    A logo of a company

Description automatically generated 
  3. Select platform and version.

    A screenshot of a computer

Description automatically generated 
    1. Select Windows as the platform.
    2. Select the Latest version for the Workspace ONE Tunnel Desktop Application.
    3. Filter by console version.
    4. Select Install and Upgrades tab for a link to the download.

After you have Accepted the Terms of Use, the download should begin immediately.

Tip: It is helpful to have all Installation files pre-downloaded on your local machine, ready to upload into Workspace ONE UEM.

To improve user experience, have the application icons and screenshots of the application ready for the Application catalog.

  1. Upload Tunnel application into Workspace ONE UEM.

    A screenshot of a computer

Description automatically generated
     
    1. In the Workspace ONE UEM console, click Resources.
    2. Select Internal Application.
    3. Click Add > Application File and Upload.
    4. Browse for the Workspace ONE Tunnel EXE installer file and click Save.
    5. Select No for Is this a dependency app?.
    6. Click Continue.
  2. On the Details tab, enter a name. For example, Workspace ONE Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. On the Files tab, Scroll down to find the App Uninstall Process section. For VMware Tunnel, enter  VMware Workspace ONE Tunnel 1.2 for Win10_Desktop.exe /uninstall /Passive as the Uninstall Command.

    A screenshot of a computer

Description automatically generated 
  4. Configure the Deployment Options tab.

    A screenshot of a computer

Description automatically generated 
    1. Select the Deployment Options tab.
    2. Locate the When to Install section.
    3. Configure any minimum requirements for the following:
      1. Data Contingencies - Use where criteria type needs to check for existing/non-existing Applications, Files or Registry Keys.
      2. Disk Space Required - Which specifies the amount of disk space the device must have available to install the application.
      3. Device Power Required - Which specifies the battery power, in percentage, that the device must have to install the application.
      4. RAM Required - Which specifies the amount of RAM the device must have to install the application.
  5. Find the Install command options.

    Some application installers may contain help options. Find help options by running the application file and adding /help or /? to the end of the file.

    The following steps demonstrate how to run these commands.
    1. Find the installer file.

      A screenshot of a computer

Description automatically generated 
    2. Hold SHIFT + Right-click the installer file.
    3. Hold Select Copy As Path.
    4. Open Command Prompt.

      A screenshot of a computer

Description automatically generated 
    5. Paste in the installer file location, adding /help or /? to the end.
    6. This should show a dialog box to show supported installation commands.

The results of running the command are shown in the screenshot. This example shows the supported Workspace ONE Tunnel Desktop Application Install parameters.

  1. Define How to Install.

    A screenshot of a computer

Description automatically generated 
    1. Under Deployment Options tab, scroll down to find the How To Install section.
    2. For the Install Command, enter VMware Workspace ONE Tunnel 1.2 for Win10_Desktop.exe /Install /Passive.
    3. Ensure Admin Privileges is set to Yes.
    4. Change Device Restart if required. This example uses User Engaged Restart. This allows the user to reboot the machine to complete the install when the user is ready.
    5. For Installer Reboot Exit Code, the supported values are 3010 and 1641.
    6. For Installer Success Exit Code, the supported values are 0 and 3010.
       

Error Code

Value

Description

ERROR_SUCCESS

0

The action completed successfully.

ERROR_SUCCESS_REBOOT_INITIATED

1641

The installer has initiated a restart. This message indicates success.

ERROR_SUCCESS_REBOOT_REQUIRED

3010

A restart is required to complete the install. This message indicates success. This does not include installs where the ForceReboot action is run.

  1. Define When to Call Install Complete.

    A screen shot of a computer

Description automatically generated 
    1. Click Add.
    2. Select File Exists for the Criteria Type.
    3. Enter C:\Program Files\VMware\Workspace ONE Tunnel\VMwareTunnel.exe for the Path.
    4. Click Add.
  2. Add the application icon.

    A screenshot of a computer

Description automatically generated 
    1. Select the Images tab.
    2. Select the Icon tab.
    3. Click the area labeled Click or drag files here.
    4. Navigate to the folder containing the Application logo, or download the provided image to use.
  3. Set Terms of Use.
    1. Select the Terms of Use tab.
    2. If you decide to have a Terms of Use that your users must accept before installing applications, you can configure that here.  For this exercise, select None.
    3. Click Save & Assign.
  4. Select Assignments and click Add Assignment.
  5. Configure the assignment.
  6. Click Add Assignment.
  7. Configure application distribution settings.

    A screenshot of a computer

Description automatically generated 
    1. Give the application assignment a name.
    2. Select the Select Assignment Groups search box and select an assignment group, for example, (Acme Corp).
    3. Select On-Demand for the App Delivery Method.
    4. Select Show for Display in App Catalog.
    5. Navigate to the Restrictions Tab.
    6. Enable for Make App MDM Managed if User Installed.
    7. Select Save then click Save and Publish.
  8. Confirm that the application appears in List View.

    A screenshot of a computer

Description automatically generated 
    1. On the Internal applications List View, confirm that the Workspace ONE Tunnel Desktop Application is displayed.  

You have successfully added the Workspace ONE Tunnel Desktop Application to Workspace ONE UEM for deployment.

Creating Per-App VPN Profile for Windows Desktop

On Windows Desktop, VMware Tunnel can force selected applications to connect through your corporate VPN.

In this exercise, you configure the Windows Desktop profile which configures the tunnel client on the device to allow only designated applications to access content on internal servers.

Log in to the Workspace ONE UEM console to perform the next steps.

  1. Click Add and click Profile.
  2. Select Windows.
  3. Select Windows Desktop.
  4. Select Device Profile.
  5. Configure the General settings.

    A screenshot of a computer

Description automatically generated 
    1. Select the General tab.
    2. Enter a Name, for example, Per App VPN.
    3. Select Assignment type. This example uses Auto, so devices automatically receive the policy.
    4. Assign the policy to a Smart Group(s).
  6. Add and configure VPN payload.

    A screenshot of a computer

Description automatically generated 
    1. Select VPN from the payload menu and click Configure.
    2. Enter a Connection Name for the policy, for example, Corp VPN.
    3. Select Workspace ONE Tunnel from the Connection Type drop-down menu.
    4. Choose the Device Traffic Rule Set (as configured in Configuring Device Traffic Rules for Windows 10) to be assigned via this Profile Payload.
    5. Select Enable for Desktop Client - This enables the Workspace ONE Tunnel Desktop Application, otherwise it will use the Windows UWP client, no longer recommended.
    6. Configure Custom Configuration XML as needed. Refer to Custom Configuration XML for Windows Desktop for additional details on the list of  Custom Configuration parameters available.
    7. Select Enable for the Enhanced Domain Resolution located under DNS Resolution via Tunnel Gateway.
    8. Click Save & Publish.
  7. Click Publish to publish the VPN profile.

Custom Configuration XML for Windows Desktop

Custom Configuration allows the administrator to determine the behavior of the Tunnel Client on the device, from initialization process, UI elements and network behaviour.

As example, the following XML configuration allows the end user to turn on/off (ToggleTunnelFeature) the Tunnel from the tray icon, and change the Tunnel connection (OnDemand) from an on-demand basis to always connected.

<?xml version="1.0" encoding="utf-16"?>
<CustomConfiguration>
   <ToggleTunnelFeature>true</ToggleTunnelFeature>
   <OnDemand>false</OnDemand>
</CustomConfiguration>

The result of this XML configuration reflects on the UI of the Tunnel Windows Client showing an option to enable/disable the Tunnel Client, and for the OnDemand connection it determine the Tunnel internal behaviour as always be connected.

Several other parameters that can be customized to change the Tunnel behavior, the following table list the custom configuration parameters supported and their respective Tunnel Mode. For additional information visit the Configure Tunnel Profile for Windows Desktop Client in the VMware documentation.

Custom Configuration XML tag syntax

Description

Tunnel Mode

Format <ServerCertSN>{Subject  CN Name}</ServerCertSN>

 

For Wildcard Certificate

<ServerCertSN>*.airwlab.com</ServerCertSN>

For SAN Certificates mention the complete Subject Alternate Name 

<ServerCertSN>tunnel.airwlab.com</ServerCertSN>

Required when using Third-Party SSL certificate for the Tunnel Server Certificate. 

This applies only to SAN Certificate and Wildcard certificate.

To retrieve the subject CN name:

1. Open the certificate on a Windows machine.

2. Select the Details tab.

3.The Subject row contains the CN of the cert.

Per-App and Full Device

<DnsSearchDomain>domain.com</DnsSearchDomain>

List of DNS search domains in comma-separated values

Per-App and Full Device

<TrustedNetworkProbeUrl>https://probeurl, http://probeurl2</TrustedNetworkProbeUrl>

List of probe URLs used by the Desktop client to consider if it is connected to a trusted network based on the reachability.

Supported schemes: http:// & https:// or IP Addresses http://10.0.0.1

Per-App and Full Device

<ExcludeFQDN>host1.com,host2.com</ExcludeFQDN>

Comma separated list of hostnames whose resolution should not be tunneled

Per-App

<ToggleTunnelFeature>true/false</ToggleTunnelFeature>

Default is false.

 When set to true, users will be given an option to Enable and Disable tunnel client service OnDemand from the system tray icon.

The Tunnel Client Service will be up when the user deactivates from the tray icon, but the Tunnel client will not intercept any traffic. When the user enables the Tunnel Client from the tray icon the tunnel client will be ready to intercept the traffic and tunnel the requests.

Per-App and Full Device

<OnDemand>true/false</OnDemand>

Default is true.

When set to true, Tunnel Client will connect when required based on incoming requests from the apps, like user trying to browser. If there is not traffic for 5 minutes, Tunnel Client will disconnect automatically.

When set to false, Tunnel Client will be always connected.

Per-App and Full Device

<StartTunnelPreLogon>true/false</StartTunnelPreLogon>

Default is false.

Use this attribute to enable the Tunnel service to start before you login. This parameter is useful for specific domain authentication scenarios, such as dropship provision where Tunnel needs to start before the user logon.

Per-App and Full Device

<PreferExternalDNS>true/false</PreferExternalDNS>

Use this attribute to prefer external DNS response over internal DNS response when DNS response is received from both.

Per-App and Full Device

Note: Use the PreferInternalDNS or PreferExternalDNS XML code in the Configuration XML. If both the XML codes are used in the Configuration XML, then the PreferInternalDNS XML code takes precedence.

<PreferInternalDNS>true/false</PreferInternalDNS>

Use this attribute to prefer internal DNS response over external DNS response when DNS response is received from both.

 

Testing Per-App Tunnel on Windows

Now that the enrolled device has received the settings configured in the Workspace ONE UEM Console, you are ready to begin testing the Per-App VPN functionality. The Workspace ONE Tunnel Desktop Application should be installed on your device.

In this exercise, you learn how to:

  1. Launch an internal website with an authorized application.
  2. Launch an internal website with an unauthorized application.
  3. Launch a defined application and demonstrate blocked domains.
  4. Launch an RDP session and connect to the machine on the internal network.
  5. Connect to an SMB share to access file shares inside the corporate network.

Launch Internal Website with an Authorized Application
 

A screenshot of a computer

Description automatically generated

  1. Launch Chrome as a browser. Chrome was the application specified to Tunnel traffic.
  2. The Workspace ONE Tunnel Desktop Application is connected and an internal web page is displayed.
  3. The address used – atl-intranet-corp.airwlab.com – is specified in the Device Traffic Rules in the previous exercise.

This web page is accessible only to applications (in this use case, Chrome) defined in the policy.

Launch Internal Website with an Unauthorized Application

Next, open another web browser, such as Microsoft Edge, and navigate to an internal web page. For example, atl-intranet-corp.airwlab.com.

A screenshot of a computer

Description automatically generated

  1. Launch Chrome - this is the authorized application.
  2. Launch another browser - for example, Microsoft Edge.
  3. The Workspace ONE Tunnel Desktop Application is connected and an internal web page is displayed.
  4. The address atl-intranet-corp.airwlab.com can be resolved in Chrome, but not in Microsoft Edge.

Launch a Defined Application to Demonstrate Blocked Domains

A screenshot of a computer

Description automatically generated

  1. In the Application access rules, certain websites are blocked. These were listed in the Device Traffic Rules.
    1. Websites blocked are cnn.com, facebook.com, and match.com.
  2. Open Chrome and navigate to one of these websites. This example uses facebook.com.
    1. When trying to resolve the DNS name, the browser displays an error as this website is blocked.
  3. Launch another browser, in this case, Microsoft Edge. Facebook.com is accessible, as the policy is configured for Chrome only.

Test RDP Connections

Sometimes, you may need to RDP into desktop sessions that are located back in the office.

A screenshot of a computer

Description automatically generated

  1. In the Application access rules, confirm the domain configuration for Remote Desktop Client access.
    Note: The RDP application is not from the Windows Store.
  2. Launch the RDP application and enter the machine name. In this example, you connect to the machine atl-intranet-corp on the domain airwlab.com.
  3. Workspace ONE Tunnel Desktop Application resolves this address, and you should be prompted for authentication.

Test SMB Share Connections

Workspace ONE Tunnel Desktop Application allows remote Windows users to connect to file shares located behind the corporate firewall. This can be team shares, individual shares, or connecting to a specific machines' C drive, for example.

This example uses the host atl-intranet-corp and connects to its C: drive.

A screenshot of a computer

Description automatically generated

  1. In the search bar, enter Run and press the return key.
  2. Enter the address of the file share you would like to connect to. For example, \\atl-intranet-corp.airwlab.com\c$.
  3. In the Application access rules, confirm the domain configuration for System resource access.
  4. Launch the SMB share. VMware Tunnel will resolve this address, and you should be prompted for authentication to the SMB share.

Troubleshooting Workspace ONE Tunnel on Windows

If a Per-App Tunnel problem occurs on Windows Desktop, you can check a number of places to troubleshoot. This section of the operational tutorial covers where to troubleshoot on Windows Desktop at a high level. Depending on the problem, there may be steps that should be performed on the Unified Access Gateway. However, troubleshooting the Unified Access Gateway is outside the scope of this tutorial. Workspace ONE UEM administrators should contact VMware Support for assistance when troubleshooting  Per-App Tunnel, Workspace ONE Tunnel, or the Unified Access Gateway.

This section is divided into two and covers the following high-level set of initial troubleshooting steps.

  1. Workspace ONE Tunnel Desktop Application Installation Troubleshooting.
    1. Checking Workspace ONE UEM console for application install status.
    2. Locating Workspace ONE Tunnel desktop application installer logs.
    3. Checking device registry for Workspace ONE Tunnel desktop application install status.
    4. Checking Workspace ONE UEM console for Policy install status.
    5. Checking device registry for Per-App VPN Profile.
  2. Workspace ONE Tunnel Desktop Application Connectivity Troubleshooting.
    1. Confirming the Workspace ONE Tunnel status when Tunnel is connected.
    2. Confirming the Workspace ONE Tunnel status when Profile is not installed.
    3. Confirming Application Access and Tunnel Service.
    4. Checking the Workspace ONE Tunnel certificate.
    5. Enabling Workspace ONE Tunnel debug logging.
    6. Locating Workspace ONE Tunnel logs.
    7. Confirming Workspace ONE Tunnel DNS Resolution.

Troubleshoot Workspace ONE Tunnel Installation

In this section, check issues that may arise from the Workspace ONE Tunnel desktop client application installation.

  1. Check Workspace ONE UEM console for application install status.

    A screenshot of a computer

Description automatically generated 
    1. Navigate to the Details view of the device.
    2. Select the Apps tab.
    3. Confirm that the App Status for the Tunnel Installer is Installed.
    4. Confirm that the App Status for Workspace ONE Tunnel shows the correct version. In this example, Workspace ONE Tunnel 1.2.0.18 is installed.
  2. Locate Workspace ONE Tunnel desktop application installer logs.

    A screenshot of a computer

Description automatically generated

    By default, the Workspace ONE Tunnel Desktop Application Installer logs are found in %TEMP%.

    Two logs should exist:
    1. Workspace_ONE_Tunnel_<date>.log
      1. This is the Bootstrapper log which usually does not yield very important errors unless any dependency programs fail on install, for example, .NET.
    2. Workspace_ONE_Tunnel_<date>_000_VMwareTunnelClientInstaller.log
      1. This is the Tunnel Installer log which shows any failures during the Workspace ONE Tunnel desktop application installation.
  3. Check device registry for Workspace ONE Tunnel install status.

    Check the location of the registry installation settings for the Workspace ONE Tunnel desktop application. These values should match the values in the Workspace ONE UEM console.

    On the computer that should have the Workspace ONE Tunnel desktop application installed, open the Windows Registry or run regedit.msc.

    A screenshot of a computer

Description automatically generated 
    1. Navigate to Computer > HKEY_LOCAL_MACHINE >  SOFTWARE >  AirWatchMDM >  AppDeploymentAgent >  S-1-5-18.
    2. Click the GUID of the application. For example, {3A7FE2DB-8AE4-4DBA-A9D3-042C88F53A50}.
    3. Click the Registry key to show IsInstalled.

Tip: The Application GUID should match the value in the Workspace ONE UEM Console.

  1. Confirm application ID in the Workspace ONE UEM console.

    A screenshot of a computer

Description automatically generated 
    1. In the Workspace ONE UEM console, navigate to Resources >  and select the Workspace ONE Tunnel Application from List View.
    2. In the App Details View, the Application ID (GUID) should match the registry value in the previous screenshot.

      For more information on troubleshooting Windows Applications, see Troubleshooting Windows Devices: Workspace ONE Operational Tutorial.
  2. Check Workspace ONE UEM console for policy install status.

    A screenshot of a computer

Description automatically generated

    After you have confirmed that the application is installed, make sure the policy is installed on the device.
    1. In the Workspace ONE UEM console, navigate to the Details View of that device.
    2. Select the Profiles tab.
    3. Confirm that the Status of the Per App VPN Profile is successful.
  3. Check device registry for per-app VPN profile.

    On the computer that should have the Tunnel policy installed, open the Windows Registry or run regedit.msc.

    A screenshot of a computer

Description automatically generated 
    1. Navigate to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\VMware, Inc.\VMware Tunnel.
    2. Click TunnelConfiguration.
    3. This displays the Tunnel Policy applied to that machine.

      Tip: If no policy is shown in the registry, re-push the policy from the Workspace ONE UEM console and perform a Device Query on that device from the Workspace ONE UEM console.

Troubleshoot Workspace ONE Tunnel Client Connectivity

After you have successfully installed the Workspace ONE Tunnel, the next step is to test the Per-App Tunnel connectivity by attempting to access one of the internal resources through the domains defined on the Device Traffic Rules.

  1. Confirm the Workspace ONE Tunnel status when Tunnel is connected.
    1. When the Tunnel Client has reached a successful connection, the Tunnel Client UI displays Connected.
  2. Confirm Workspace ONE Tunnel status when profile is not installed.

    A screenshot of a computer

Description automatically generated 
    1. If the Workspace ONE Tunnel Client has installed, but the configuration settings have not, the Tunnel client status is Not Configured.

      Tip: To resolve, ensure the Per-App VPN profile is assigned to the device, and ensure it is successfully installed.
  3. Confirm application access and Tunnel service.
  • Problem: The Workspace ONE Tunnel Client status is Disconnected.
  • Solution: Confirm that the Application is defined in Application Access and that the application is running.
  • Problem: The Workspace ONE Tunnel Client status is Disconnected.
  • Solution: Confirm that the VMware Workspace ONE Tunnel Service is running in Windows Services. If the service is not started, start the service.

To check the Tunnel service:

A screenshot of a computer

Description automatically generated

  1. On the Windows machine, open Services and locate the VMware Workspace ONE Tunnel Service.
  2. Ensure that the Startup type is set to Automatic.
  3. Ensure that the Service is running.
  1. Check the Workspace ONE Tunnel desktop application certificate.
    • Authentication for the Tunnel Client can be configured to use Enterprise Certificates or internally-signed certificates. If no certificate is present, the Tunnel UI status displays Not Configured -  Authentication Certificates are not present.
    • If there is no certificate present, you may want to re-push the policy again to the device. By re-pushing the policy, the Tunnel certificate should be installed.

      A screenshot of a computer

Description automatically generated 

To check the certificates:

  1. On the Windows machine, search MMC, and open the Certificates snap in.
  2. Navigate to Local Computer > Personal > Certificates.
  3. Confirm that the certificate for certificate authentication to the Tunnel service is listed.
  4. Retrieve the device UDID from the Workspace ONE UEM console.
  5. Navigate to Devices > List View > Summary and confirm that the device UDID matches the Certificate request as shown in the previous screenshot.
  1. Enable Workspace ONE Tunnel debug logging.

    A screenshot of a computer

Description automatically generated 
    1. On the Windows machine, navigate to the system tray. You should see the Tunnel icon.
    2. Right-click the Tunnel client.
    3. Select Enable debug logging.
    4. Debug logging levels are from 0-4 - Enabling debug logging will set the log level to 4.

You can also check the Workspace ONE Tunnel log level in the device registry.

A screenshot of a computer

Description automatically generated
 

  1. On the computer that should have the Tunnel installed, open the Windows Registry or run regedit.msc.
  2. Navigate to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\VMware, Inc.\VMware Tunnel.
  3. Under the LogLevel entry, you should see a value from 0-4. In this example, the value is 0.
  4. You cannot change the value in the registry. You must follow the steps to Enable Workspace ONE Tunnel Debug Logging.
  1. Locate Workspace ONE Tunnel logs.
    1. By default, the Workspace ONE Tunnel Client Installer logs are located in C:\ProgramData\VMware\VMware Tunnel.

Two logs should exist:

  1. win_tunnel   This log file shows connectivity issues with the Workspace ONE Tunnel desktop application.

    A screenshot of a computer

Description automatically generated 
  2. win_tunnelui  This log file shows User Interface changes within the Workspace ONE Tunnel desktop application.

    A screenshot of a computer program

Description automatically generated 
  1. Confirm Workspace ONE Tunnel desktop application DNS resolution.

    A screenshot of a computer program

Description automatically generated

    After you have confirmed Tunnel connectivity, check the DNS resolution.

Sometimes, the Workspace ONE Tunnel Client may be in good working order. For example, the profile is installed, the application is installed, the service is running, and the status is Connected. But the DNS resolution is still failing. In this case, general networking troubleshooting can assist greatly.

You can check the Name Resolution Policy Table (NRPT).

On the Windows machine, open PowerShell and enter Get-DnsClientNrptRule. This command retrieves the Name Resolution Policy Table (NRPT) for the device. For more information, see Microsoft PowerShell Docs - Get-DnsClientNrptRule.

Deploying Workspace ONE Tunnel for Android

Per-App Tunneling helps users to access critical information using applications on their devices from their devices. Mobile flows help users perform business-critical tasks from a single app — streamlining the user experience.

Leveraging Per-App Tunnel allows you to control which applications are on a device and what internal resources the applications have access to by automatically activating or deactivating Per-App VPN access, based on which applications are active. By enabling remote access, you no longer need to provide a device-wide VPN on your devices, which can allow unintended or unauthorized apps or processes to access your VPN. In this tutorial, you configure and deploy VMware Workspace ONE Tunnel to enable the Per-App Tunnel component on managed devices.

These exercises involve the following components:

  • Workspace ONE Tunnel – The app used on the device to securely connect to the Unified Access Gateway to provide Per-App Tunnel functionality, also referred to as Tunnel Client.
  • Unified Access Gateway – The virtual appliance where the VMware Tunnel edge service is installed, and to which the tunnel client connects.
  • Per-App Tunnel – Component of VMware Tunnel edge service for connecting to a secure tunnel channel on a per-application basis, which is controlled and configured by the VPN profile payload and Device Traffic Rules.
  • Per-App VPN Profile and Device Traffic Rules – The Workspace ONE UEM configuration is pushed to the device that contains the Per-App Tunnel configurations. Every time a specified application is opened, the Workspace ONE Tunnel client evaluates the Device Traffic Rules assigned to it before making any routing decisions and establishes a Per-App tunnel connection with the Unified Access Gateway based on the Per-App VPN Profile configuration.

High-Level Architecture

A diagram of a network

Description automatically generated

The device contains the applications required by the end-user to perform their daily job. Some applications require access to internal resources to function. Those applications, based on Per-App VPN configuration, use Workspace ONE Tunnel which communicates with the Tunnel Service on Unified Access Gateway hosted on the DMZ, to validate if the device requesting access is in compliance or not before authorizing access through the internal resource.

Prerequisites

Before you can perform the steps in this exercise, you must have the following components installed and configured:

  • Workspace ONE UEM version 2203 and later
  • Android 10.0+ enrolled in Workspace ONE UEM
  • The latest version of Workspace ONE Tunnel app from Google Play Store
    • Deploy Workspace ONE Tunnel using Android Enterprise

Configuring Device Traffic Rules for Android

In this exercise, you configure device traffic rules for Android.

Note: Domain values used in this section are examples only. Your values will differ.

In the Workspace ONE UEM console:

  1. Navigate to Groups & Settings > Configurations.
  2. Select Tunnel.

    A screenshot of a computer

Description automatically generated 
  3. From the Device Traffic Rules tile, click Edit.
  4. Click Add or the Default assignment to manage the device traffic rules.

    A screenshot of a computer

Description automatically generated
    Administrators can create multiple Device Traffic Rules that will be assigned to the Per-APP VPN profile and will deploy to the devices based on the smart group assigned to the Profile. The first device traffic rule assignment created will be set as default.
  5. Observe the default device traffic rule.

    A screenshot of a computer

Description automatically generated 
    1. Update the Assignment Name with the name of your choice.
    2. Observe (or modify) the default action which applies to all Android applications selected to use Per-App VPN:
      1. Tunnel – All apps, on the device configured for Per-App Tunnel send network traffic through the tunnel. For example, set the Default Action to Tunnel to ensure all configured apps without a defined traffic rule use the Workspace ONE Tunnel for internal communications.
      2. Block – Blocks all apps, on the device configured for Per-App Tunnel from sending network traffic. For example, set the Default Action to Block to ensure that all configured apps without a defined traffic rule cannot send any network traffic regardless of destination.
      3. Bypass – All apps, except Safari, on the device configured for Per-App Tunnel bypass the tunnel and connect to the Internet directly. For example, set the Default Action to Bypass to ensure all configured apps without a defined traffic rule bypass the Workspace ONE Tunnel to access their destination directly.
    3. Click ADD RULE.
  6. Build the device traffic rule.

    A screenshot of a computer

Description automatically generated 
    1. Click ADD RULE.
    2. Click the down arrow to display the  Application list.
    3. Select one or more triggering applications to control with this rule. Alternatively, on the drop-down select All Applications to apply the rule to all Android applications listed in the drop-down, which are the ones that you assigned the Per-App VPN profile.
    4. Enter one or more comma-separated fully qualified domain names as destinations to which Workspace ONE Tunnel should apply the Device Traffic Rule. A single asterisk (*) can be used as a wildcard for subdomains.  
    5. Select the Appropriate Action for Workspace ONE Tunnel to perform on traffic from the selected apps:
      1. Tunnel – Sends app network traffic for specified domains through the tunnel to your internal network.
      2. Block – Blocks all traffic sent to specified domains.
      3. Bypass – Bypasses the Workspace ONE Tunnel so the application accesses specified domains directly.
      4. Proxy – Redirect traffic to the specified HTTPS proxy for the listed domains. The proxy must be HTTPS and must follow the correct format: https://example.com:port.
    6. If necessary, adjust the Device Traffic Rules rank in the list. Lower-numbered rank is the highest priority.
    7. Click Save.

The example shown blocks access to Facebook, Tinder, and Utorrent domains for all applications available on the Android device.

For more information on the formats (wildcards, IP, ports) allowed into the Destination field, see the Device Traffic Rules Destination formats supported chapter.

Distributing Workspace ONE Tunnel for Android

In this exercise, you deploy an application configured to use the Per-App VPN tunnel on Android.

  1. Click Add and click Public Application.

    A screenshot of a computer

Description automatically generated 
  2. Search for Workspace ONE Tunnel.

    A screenshot of a application

Description automatically generated 
    1. Select Android for the Platform.
    2. Enter an application Name. For example, Workspace ONE Tunnel.
    3. Click Next.
  3. Select Tunnel – Workspace ONE Tunnel.
    A screenshot of a computer application

Description automatically generated
     
  4. Click Approve for the Workspace ONE Tunnel app and for any following requests.
  5. Click Save and Assign.
  6. Click Add Assignment.
  7. Configure Assignment settings.

    A screenshot of a computer

Description automatically generated 
    1. Click the Selected Assignment Groups field to display the list of created Assignment Groups. Enter All Devices, and select the All Devices (your@email.shown.here) group.
    2. Select Auto for the App Delivery Method.
  8. Configure Policies.

    A screen shot of a computer

Description automatically generated 
    1. Scroll down to find the Policies section.
    2. Select Enabled for Managed Access.
    3. Click Add.
  9. Confirm that your assignment is displayed and click Save and Publish.

    A screenshot of a computer

Description automatically generated 
  10. Preview your assigned devices and click Publish.

Android Considerations

Note the following for Workspace ONE Tunnel on Android:

  • After installing VMware Workspace ONE Tunnel for Android, end users must run the application at least once and accept the connection request.
  • The key icon in the notification center displays on the device because there is an application installed that uses the Per-App Tunnel functionality. This icon does not indicate an active connection or session with the VMware Tunnel Service. The key icon displays even if you are not actively browsing.
  • Certain Android devices allow end users to disable the VPN on an OS level. This prevents the VMware Tunnel from working on the device.

Creating Per-App VPN Profile for Android

Per-App VPN profile allows you to force selected applications to connect through your corporate VPN. Your VPN provider must support this feature, and you must publish the applications as managed applications.

In this exercise, you create the Android profile which configures the Workspace ONE Tunnel client on the device to allow only designated applications to access content on internal servers.

Log in to the Workspace ONE UEM console to perform the next steps.

  1. Click Add and click Profile.
  2. Select Android.
  3. Configure the General settings.
    A screenshot of a computer

Description automatically generated
     
    1. Select the General tab.
    2. Enter a Name, for example, Per App VPN.
    3. Select the name of your device's assignment group, and select that group. For example, select All MDM Enrolled Devices (ACME Corp) as the Assigned Smart Group.
  4. Add and configure VPN payload.

    A screenshot of a computer

Description automatically generated 
    1. Select VPN from the payload menu and click Configure.
    2. Select Workspace ONE Tunnel from the Connection Type drop-down menu.
    3. Select the Default traffic rule previously created for Device Traffic Rule Sets.
    4. Click Save & Publish.
  5. Click Publish to publish the VPN profile.

Configuring Workspace ONE Web for Per-App Tunnel

Workspace ONE Web is part of the secure productivity app suite from VMware. Administrators can deploy Workspace ONE Web when data loss and copy/paste restrictions are critical to the business use case.

In this exercise, you distribute and configure Workspace ONE Web for Per-App Tunnel on Android.

  1. Add application.

    A screenshot of a computer

Description automatically generated 
    1. In the Workspace ONE UEM console, click Resources.
    2. Select Native under Apps.
    3. Select Public and click Add Application.
  2. Search for Workspace ONE Web on Google Play Store.

    A screenshot of a computer

Description automatically generated 
    1. Select Android for the Platform.
    2. Enter an application Name. For example, Workspace ONE Web.
    3. Click Next.
  3. Select Workspace ONE Web app and approve.

    A screenshot of a application

Description automatically generated 
  4. Click Save and Assign.
  5. Click Add Assignment.
  6. Assign Per-App VPN profile to Workspace ONE Web.

    A screenshot of a computer

Description automatically generated 
    1. Select All Devices on Assignment Groups.
    2. Select Auto for App Delivery Method.
    3. Enable Managed Access.
    4. Enable App Tunneling
    5. On Android, select the Per-App VPN Profile that you previous created.
    6. Click Add.
  7. Click Save and Publish.

Testing Per-App Tunnel on Android

Now that the enrolled device has received the settings configured in the Workspace ONE UEM Console, you are ready to begin testing the Per-App Tunnel functionality. The applications assigned in the previous exercises should push down during enrollment. The VMware Tunnel and Workspace ONE Web applications should be installed on your device.

In this exercise, launch Workspace ONE Web and access the internal website. Then verify that, although the VPN connection is active, other applications on the device are not able to access the tunnel or internal resources.

  1. Open Workspace ONE Tunnel.

    A screenshot of a phone

Description automatically generated

    Press the Home button on your device to return to the Launchpad. Swipe right to see the downloaded applications, if needed.

    Tap the Workspace ONE Tunnel icon to launch the application. If prompted, select OK to allow Workspace ONE Web to send your device push notifications.
    After the application has been opened, accept the privacy prompts and tap Continue.

    Note: On Android, the Workspace ONE Tunnel Client must be launched once to silently route traffic for future occurrences.
  2. Tap I Understand to accept the Privacy Prompt.
  3. Tap I agree to accept the Data Sharing Prompt.
  4. Confirm Tunnel connectivity.
    After the Tunnel Client has been opened, you can see three areas.

    A screenshot of a phone

Description automatically generated 
    1. Device VPN Configuration
      1. The Profile or Policy that is delivered from Workspace ONE UEM. It shows a list of apps that will use the VPN Tunnel.
    2. Internet 
      1. Displays whether the device has internet connectivity or not.
    3. Enterprise Server
      1. Displays whether the device has connectivity to the VMware Tunnel edge service.
  5. Launch Workspace ONE Web.

    A screenshot of a phone

Description automatically generated

    Press the Home button on your device to return to the Launchpad. Swipe right to see the downloaded applications, if needed.

    Tap the Workspace ONE Web icon to launch the application. If prompted, tap OK to allow the Web to send your device push notifications.
  6. Access the internal website with Workspace ONE Web.
    A screenshot of a phone

Description automatically generated
     
    1. After the application launches, enter the URL for your intranet website, such as https://atl-intranet-corp.airwlab.com.
    2. Confirm that the VPN icon appears, indicating the connection is active. The application now connects to Workspace ONE UEM and retrieves the settings for your Organization Group.
    3. The website should load. In this example, it displays a Welcome message.
    4. Select and copy the internal URL. In the next step, you test entering this URL into another browser.
  7. Paste the URL into another browser.
    A screenshot of a black screen

Description automatically generated
     
    1. Open another browser, such as Chrome.
    2. Copy and paste the URL from the previous step.
    3. Confirm that only the defined applications can access internal resources.

Note: This example used a Work Managed Device. Work Managed devices provide separation from personal and corporate data. With Per-App Tunnel, you can isolate traffic to only those applications that need it rather than all corporate resources. This example shows Chrome inside the Work Profile attempting to access internal resources.

Troubleshooting Workspace ONE Tunnel on Android

If a Per-App Tunnel problem occurs on Android, you can check a number of places to troubleshoot. This section of the operational tutorial covers where to troubleshoot the Workspace ONE Tunnel client for Android at a high level.  

Depending on the problem, there may be steps that should be performed on the Unified Access Gateway. However, troubleshooting the Unified Access Gateway is outside the scope of this tutorial. 

Workspace ONE UEM administrators should contact VMware Support for assistance when troubleshooting Per-App VPN, Workspace ONE Tunnel, or the Unified Access Gateway.

This section is divided into three parts and guides you through high-level steps to troubleshoot the Workspace ONE Tunnel installation and connectivity.

  1. Troubleshooting Device Connectivity
    1. This section displays where to search for Tunnel Client connectivity issues.
  2. Collecting logs automatically
    1. This step is useful for recreating issues and retrieving the Workspace ONE Tunnel Client log file.
  3. Advanced: Collecting logs manually on an Android Device
    1. This step is for advanced cases where you may need to see how the devices VPN stack is behaving. This step should be used only for test devices; it is not recommended to leave Developer Options turned on.

Troubleshoot Device Connectivity

  1. Open the Tunnel Application and tap the Diagnostics menu option.

    A screenshot of a phone

Description automatically generated 
  2. Any issues related to connectivity issues with the Tunnel server or a Proxy server are shown on the UI.

    A screenshot of a phone

Description automatically generated 
  3. Tap the email option in the upper-right corner to send these logs to your administrator.

Collect Logs Automatically

  1. Open the Tunnel Application and tap the Diagnostics menu option.
  2. Activate the Enable debug logs toggle.

    A screenshot of a phone

Description automatically generated 
  3. After the issue is reproduced, go to your internal storage and open the AirWatchLogs folder.
  4. This folder contains a set of log files that, if required, can be shared with the Workspace ONE support teams.

Advanced: Collect Logs Manually on Android

  1. To collect logs manually, you must enable developer options on the mobile device.
    1. Navigate to Settings > About page on the device and tap the build number more than 7 times to enable developer options.
  2. Enable USB debugging in the Settings > Developer Options.
  3. Connect the device via USB cable to a laptop and install the device drivers.
    1. Check whether the device is getting detected in the laptop by running adb devices in the command prompt. The device should be listed with a Unique id.
    2. adb is a tool part of the android-sdk which you must download from http://developer.android.com.
  4. After the device is detected (keep the device connected) run adb logcat –v threadtime > TunnelLogs.log. Logs will continuously dump to the file. 
  5. After the issue is reproduced, logging can be stopped either by disconnecting the device or using Ctrl + c command.
  6. If required, share the TunnelLogs.log with the Workspace ONE support teams.

Summary and Additional Resources

This operational tutorial provided steps to leverage native Per-App Tunnel capabilities across mobile platforms, Android and iOS, and desktop platforms, macOS and Windows. 

By publishing Per-App VPN profiles to your devices, you can ensure that only authorized apps are accessing authorized applications through the Tunnel. This eliminates the user requirement to manually start and end a network connection like traditional VPN solutions based on the apps they are accessing. 

It also provides an extra layer of security to your corporate resources by ensuring that non-authorized apps are unable to connect to your VPN, creating the beginnings of a Zero Trust model for application access.

Additional Resources

For more information about Workspace ONE, explore the VMware Workspace ONE Activity Path. The activity path provides step-by-step guidance to help you level-up in your Workspace ONE knowledge. You will find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon.

Changelog

The following updates were made to this guide:

Date

Description of Changes

2023-09-07

  • Updated requirements for Workspace ONE UEM
  • Referenced new documentation links

2023-3-28

  • Updated supported platform matrix for Workspace ONE Tunnel
  • Updated list of Custom XML Configuration for Windows Desktop
  • Updated requirements for Windows deployment
  • Added Windows 11 support

2022-12-05

  • Updated the Trust Network Detection chapter: added DNS resolution details when Trust Network Detection is enabled.
  • Updated platform support and features availability matrix.
  • Added details on the new Device Traffic Rules sync process for Android.

2021-07-09

  • Updated the Device Traffic Rules chapter adding a detailed explanation of default action rule per platform.
  • Added supported custom configuration parameters for Windows 10.
  • Added details for Trusted Network Detection based on probe URL.

2021-06-30

  • Updated Device Traffic Rules with an explanation about the new Full Device Tunnel Mode.
  • Added Device Traffic Rules Guidelines for use of the asterisk, IP, and port range.
  • Added steps to deploy Workspace ONE Tunnel for iOS as Public App (App Store) using Workspace ONE UEM.

2020-11-13

  • Added Trusted Network Detection chapter.
  • Updated Device Traffic Rules topic, adding support to manage traffic assignments based on multiple Device Traffic Rules sets.
  • Update Profile configuration for all platforms to support device traffic rule configuration via profile.

2020-3-26

  • Added Windows, Android, and macOS Platforms. 
  • Edited iOS Platform.

About the Author and Contributors

This tutorial was written by:

Feedback

Your feedback is valuable.

To comment on this paper, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.

Filter Tags

Workspace ONE Workspace ONE UEM Document Operational Tutorial Intermediate Deploy Zero Trust