How to set network capabilities (HTML)

Article
08/31/2015

This topic explains the network isolation concept and how to set network capabilities to fully control network access for a Windows Runtime app. Network capabilities ensure that Windows Runtime apps have access to required network resources, and that accurate expectations regarding levels of access are provided to the end-user. Understanding this topic will ensure that your Windows Runtime app can connect to network resources appropriately. Network isolation ensures that Windows Runtime apps have access to network resources only after specifically requesting the correct capability.

What you need to know

Technologies

Windows.Networking.BackgroundTransfer

Enables advanced download and upload operations.
Windows.Networking.Sockets

Enables network communications using sockets and WebSockets.
Windows.Web.AtomPub

Enables access to Web resources using the AtomPub protocol.
Windows.Web.Http

Provides a modern HTTP client API for connecting to web services.
Windows.Web.Syndication

Manages syndication feeds.
System.Net.Http

Enables connecting to web services with a web client (C#/VB only).

Prerequisites

The following information applies to any connected or network-aware Windows Runtime app that needs to make network connections. This affects apps written in JavaScript. This also affects apps written using the .NET Framework 4.5 in C#, VB.NET, and C++.

Checklist for network isolation

Use this checklist to be sure that network isolation is configured for your app.

Determine the direction of network access needed by the app. This can be either outbound client-initiated requests or inbound unsolicited requests or it could be a combination of both of these network request types.
Determine the type of network resources that app will communicate with. An app may need to communicate with trusted resources on a Home or Work network. An app might need to communicate with resources on the Internet. An app might need access to both types of network resources.
Configure the minimum-required networking isolation capabilities in the app manifest. These capabilities are normally configured using Microsoft Visual Studio 2013 when the app is developed.
Deploy and run your app to test it using the network isolation tools provided for troubleshooting.

More information about network isolation

Not all apps require access to the network, however for apps that do, Windows 8.1 provides different levels of network access that can be enabled by selecting appropriate capabilities.

Network isolation allows you to define the scope of required network access for each app. Network access requests are divided into two categories:

Outbound client-initiated requests
The app acts as the client and initiates network access by sending an initial network request to a remote computer, usually a server. The client app sends one or more requests to the server and the server sends back a single response or several responses to the client app. All traffic from a web client app to a web server would be in this category.
Inbound unsolicited requests
The app acts as a network server and listens for inbound network requests from a remote computer. The remote computer initiates network access by sending an initial request to the app, which acts as server. The remote computer sends one or more requests to the app, which sends back one or more responses to the remote computer. An app that functions as a media server would be in this category.

An app with an undefined scope is prevented from accessing the specified type of network connection. The ability to set and enforce network isolation ensures that if an app gets compromised, it can only access networks where the app has explicitly been granted access. This significantly reduces the scope of the impact on other applications and on the system.

Network isolation affects any methods and properties in the following namespaces that try to access the network.

Windows actively enforces network isolation. A call to a method or any access to a property in these namespaces that results in network access may fail because of network isolation if the appropriate network capability has not been enabled. Classes in other namespaces that call methods or access properties in the above namespaces are also affected.

The network capabilities for an app are configured in the app manifest when it is built. Network capabilities are usually added using Visual Studio when developing the app. Network capabilities may be set manually in the app manifest file using a text editor.

Network isolation and capabilities

Network isolation is part of the application security model used by the Windows 8. Windows actively discovers the network boundaries and enforces network access restrictions for network isolation. The following are the network boundaries the system will look for:

Home\Work Network
This is your local home or work network. It is composed of the local subnets the computer is connected to and local proxies configured as part of the network. Internet proxies are excluded from this boundary. In a domain environment, this includes ranges defined by Active Directory Sites and subnets
Internet
The Internet, excluding the home or work network. This is composed of any proxy that provides access the Internet. Any network access that is not part of your Home\Work Network is considered to be Internet.

Windows 8 categorizes all remote network hosts into one of these two categories. By understanding the applicable direction and categorization of hosts that your app will communication with, you will be able to choose the right capabilities for your app.

Certain capabilities that relate to networking must be enabled in the app manifest for the app to be granted network access. These capabilities are defined as security identifiers (SIDs) which are used by Windows 8 to enforce the boundaries.

The following networking isolation capabilities are defined:

Term used in Visual Studio	Description
Internet (Client)	Provides outbound access to the Internet and networks in public places, like airports and coffee shop. Most apps that require Internet access should use this capability. This is the internetClient capability in the app manifest.
Internet (Client & Server)	Gives the app inbound and outbound network access from the Internet and networks in public places like airports and coffee shops. This is the internetClientServer capability in the app manifest.
Private Networks (Client & Server)	Gives the app inbound and outbound network access at the user's trusted places, like home and work. This is the privateNetworkClientServer capability in the app manifest.

Internet (Client)

Provides outbound access to the Internet and networks in public places, like airports and coffee shop. Most apps that require Internet access should use this capability.

This is the internetClient capability in the app manifest.

Internet (Client & Server)

Gives the app inbound and outbound network access from the Internet and networks in public places like airports and coffee shops.

This is the internetClientServer capability in the app manifest.

Private Networks (Client & Server)

Gives the app inbound and outbound network access at the user's trusted places, like home and work.

This is the privateNetworkClientServer capability in the app manifest.

Note

Windows Phone Store apps have a single network capability that enables all network access for the app. The Internet (Client & Server) capability enables complete access to the network for both client operations (outbound access) and server operations (inbound access). However, if any of the network capabilities (internetClient, internetClientServer, or privateNetworkClientServer) are specified in the Package.appxmanifest file, a Windows Phone Store app has complete access to the network at run time for both client and server operations.

While you’re developing and testing your Windows Phone Store app app in Visual Studio, you get the networking capability (Internet (Client & Server)) when you run the app, even if you haven’t specified this capability in the app manifest file. When you publish your app, however, your app does not automatically get the networking capability. Make sure you check the Internet (Client & Server) capability on the Capabilities page of Manifest Designer if your app requires network connectivity.

Certain other capabilities may need to be enabled in the app manifest for network access. These capabilities are defined as GUIDs, which are used to enforce the boundaries.

Term used in Visual Studio	Description
Enterprise Authentication	Allows an app to connect to network resources that require domain credentials. This capability will require a domain administrator to enable the functionality for all apps. An example would be an app that retrieves data from Intranet Sharepoint servers. With this capability your credentials can be used to access network resources on a network that requires credentials. An app with this capability can impersonate you on the network. This capability is not required to allow an app to access the Internet via an authenticating proxy. This is the enterpriseAuthentication capability in the app manifest.
Proximity	Required for near-field proximity communication with devices in close proximity to the computer. Near-field proximity may be used to send or connect with an application on a nearby device. This capability allows an app to access the network to connect to a device in close proximity, with user consent to send an invite or accept an invite. This is the proximity capability in the app manifest.
Shared User Certificates	This capability allows an app to access software and hardware certificates, such as smart card certificates. When this capability is invoked at runtime, the user must take action, such as inserting a card or selecting a certificate. With this capability, your software and hardware certificates or a smart card are used for identification in the app. This capability may be used by your employer, bank, or government services for identification. This is the sharedUserCertificates capability in the app manifest.

Enterprise Authentication

Allows an app to connect to network resources that require domain credentials. This capability will require a domain administrator to enable the functionality for all apps. An example would be an app that retrieves data from Intranet Sharepoint servers.

With this capability your credentials can be used to access network resources on a network that requires credentials. An app with this capability can impersonate you on the network.

This capability is not required to allow an app to access the Internet via an authenticating proxy.

This is the enterpriseAuthentication capability in the app manifest.

Proximity

Required for near-field proximity communication with devices in close proximity to the computer. Near-field proximity may be used to send or connect with an application on a nearby device.

This capability allows an app to access the network to connect to a device in close proximity, with user consent to send an invite or accept an invite.

This is the proximity capability in the app manifest.

Shared User Certificates

This capability allows an app to access software and hardware certificates, such as smart card certificates. When this capability is invoked at runtime, the user must take action, such as inserting a card or selecting a certificate.

With this capability, your software and hardware certificates or a smart card are used for identification in the app. This capability may be used by your employer, bank, or government services for identification.

This is the sharedUserCertificates capability in the app manifest.

Certain device capabilities that are related to device access may also need to be enabled in the app manifest for network access to function as expected. These device capabilities are defined as GUIDs which are used by the system to enforce boundaries.

Term used in Visual Studio	Description
Webcam	Provides access to a webcam's video feed. This capability is needed if the app intends to share a webcam's video feed with a remote computer over the network. This is the webcam capability in the app manifest.

Webcam

Provides access to a webcam's video feed.

This capability is needed if the app intends to share a webcam's video feed with a remote computer over the network.

This is the webcam capability in the app manifest.

It is important for you to understand what capabilities are required for your application. The following table lists some common operations and what capabilities are needed.

Capabilities Required

Application	Description
A Web client that only consumes content. This would include apps that loads HTML from a website and apps that uses RSS syndication or the AtomPub protocol.	internetClient
A social network app. This includes an app that consumes and produces content on a social network site.	internetClient
A peer to peer (p2p) app. This includes an app that provide access to instant messenger or chat.	internetClientServer
An app for sharing in a home or work network. This includes an app that accesses media or network attached storage (NAS) content.	privateNetworkClientServer
A line of business app at home or work. This includes an app that acts as an HTTP client or uses sockets or WebSockets.	privateNetworkClientServer
A productivity app with networking features at home or work. This includes a productivity app that accesses network features.	privateNetworkClientServer
A game app that requires network access.	internetClient
A multiplayer internet game app that does matchmaking.	internetClient
A multiplayer game with people in close proximity.	proximity
A multiplayer game app that discovers players with multicast discovery or using multicast.	internetClientServer
A multiplayer game app that uses the home or work network. This includes an app that discovers players with multicast discovery or is discovered using multicast.	privateNetworkClientServer
A broadcasting app. This includes an app that receives radio broadcasts over the Internet.	internetClient

Network isolation and network boundaries

For Windows 8.1 to enforce network isolation, the system needs to discover and determine the network boundaries. Windows 8.1 performs this discovery in a dynamic fashion. The system probes the network to discover the addresses on the local computer's network interfaces and any addresses the interfaces are bound to determine the presence of gateways or IP addresses that act as an access point to and from the Internet. The following will be discovered:

Local addresses and subnets used by a home or work network.
Internet gateways and proxies to the Internet.

Typical local IPv4 addresses and subnets discovered at home or work include the following private IPv4 address ranges:

10.0.0.0-10.255.255.255
172.16.0.0-172.31.255.255
192.168.0.0-192.168.255.255

Typical local IPv6 addresses and subnets discovered at home or work include the following IPv6 address ranges:

The local IPv6 subnet associated with the IPV6 address.
IPv6 Link-Local addresses (fe80::/10).
IPv6 tunnel addresses used for transition technologies (6to4 and ISATAP, for example) excluding the IPv6 address range used by Teredo (2001::/32).

When a user first connects their computer to a network, a Wireless LAN (Wi-Fi) network in their house, they are given the option to enable sharing on the network. This decision is used by Windows to categorize the network as either trusted or non-trusted.

A network endpoint is considered part of the Home\Work Network if any of the following conditions are met:

It is part of the local subnet of a trusted network as indicated by the user. For example, home users generally flag their home network as Trusted. Computers on the local subnet will be designated as part of the Home\Work Network.
A computer is on a network and it is authenticated to a domain controller. Network endpoints within the local subnet are considered private. Network endpoints within the Intranet address space are considered private.
The computer is configured for DirectAccess and the network endpoint is part of the Intranet address space.

The Intranet address space is composed of configured Active Directory sites and subnets, and it is configured for Windows network isolation specifically by using Group Policy. Domain-joined machines will query Active Directory and Group Policy for this information.

All other network endpoints that do not meet the previously stated criteria are considered network endpoints on the Internet.

For more information on Administrator controls for network isolation, please see Isolating Windows Store apps on Your Network

Network isolation and enforcement

When an app attempts an outbound client-initiated request (an HTTP web request to www.contoso.com, for example), the system will perform a check on the capabilities enabled for the app in its manifest and make a decision to allow or block the outbound client-initiated request to the specific host (www.contoso.com, for example). If the outbound client-initiated request is allowed, then responses from the server in response to outbound client-initiated requests are also allowed.

When an app attempts to listen for inbound unsolicited requests, the system will perform a check on the capabilities set for the app in its manifest and make a decision to allow or block the inbound unsolicited request from a remote IP address. An app must have either the InterentClientServer or the privateNetworkClientServer capability enabled to be allowed to listen for inbound unsolicited requests. If at least one of these capabilities is enabled, the app is allowed to listen on a port or several ports for inbound unsolicited requests on the specified network type. Every inbound unsolicited request attempt is checked to determine if an inbound unsolicited request from the specific remote source IP address is allowed. Windows determines whether the inbound unsolicited request is from a home\work IP address or the Internet and allows or denies access depending on the capabilities enabled and the specific remote address.

Network isolation is fully integrated with any proximity components. When the proximity capability is enabled in an app manifest, there is no need for any additional networking capability to be enabled. The user must still consent to send or accept an invite from the proximity device to allow communication between the proximity device and the local computer.

Network isolation and loopback

IP loopback addresses and the loopback interface have traditionally been used for communication between different applications over the network, as well as for interprocess communication within several applications on a local computer.

Network communications using an IP loopback address cannot normally be used for interprocess communication (between two different apps) because this is restricted by network isolation. Network communication using an IP loopback address is allowed within an app within the same process for communication purposes.

For more information on enabling developer access to IP loopback addresses between apps for debugging purposes, see How to enable loopback and debug network isolation.

Background transfer and toast notifications

The BackgroundDownloader and BackgroundUploader classes in the Windows.Networking.BackgroundTransfer namespace in Windows 8.1, Windows Phone 8.1, and Windows Server 2012 R2 support options for the user to receive tile and toast notifications when a transfer is completed successfully or fails to complete.

For an app using Windows.Networking.BackgroundTransfer to communicate through a toast notification, you must declare that it is Toast capable in the app manifest file. This setting is not under the Capabilities section with the network isolation settings. The Toast capable setting is located under the Notifications section of Application tab. Set the Toast capable option to "Yes" so the app can receive toast notifications.

If Toast capable is not enabled in the app manifest, then any toast settings in the Windows.Networking.BackgroundTransfer namespace will be silently ignored and no toasts notifications will be received by the app.

Note A user can manually disable or enable toast notifications for your app at any time.

For more information on toast notifications, see Sending toast notifications and How to opt in for toast notifications.

Other resources

App capability declarations

App Package Manifest

Capability

DeviceCapability

How to enable loopback and debug network isolation

How to opt in for toast notifications

Sending toast notifications

Troubleshooting and debugging network connections

Reference