Windows 8 Integration for Wireless Hotspot Operators

Offering the best experience in apps and browsers

September 28, 2012

Abstract

This paper provides information about wireless hotspots for Windows 8. It provides guidelines for hotspot operators to offer a tailored experience to Windows 8 users. It assumes that the reader is familiar with common hotspot practices, such as captive portals and the WISPr protocol. This information applies to the following operating systems: Windows 8 References and resources discussed here are listed at the end of this paper. The current version of this paper is maintained on the Web at: Windows 8 Integration for Wireless Hotspot Operators

Disclaimer: This document is provided as-is. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to prereleased product which may be substantially modified before its commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. You may modify this document for your internal, reference purposes. 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 2

Document History
Date September 28, 2012 August 15, 2012 June 27, 2012 May 31, 2012 Change Updated to reflect changes in branding Updated for Windows 8 RTM Updated information about Provisioning for Hotspot Authentication Updated information about provisioning for hotspot authentication, signing the provisioning file, handling large numbers of SSIDs, and getting started with a hotspot authentication app First publication

February 28, 2012

Contents
Introduction ................................................................................................................... 3 Hotspot Authentication Methods .................................................................................. 3 Captive Portals ........................................................................................................... 3 Consistent Connection Handling ........................................................................... 4 Touch-Friendly Web Pages .................................................................................... 4 Provisioning after Purchase ................................................................................... 4 Offer App Installation ............................................................................................ 4 WISPr Authentication ................................................................................................ 5 Provisioning for Hotspot Authentication............................................................... 6 Handling large numbers of SSIDs........................................................................... 7 Handling the Hotspot Authentication Event ......................................................... 9 Hotspot 2.0 .............................................................................................................. 11 Getting started with a Hotspot Authentication app .................................................... 11 Review the sample ................................................................................................... 11 Update the sample................................................................................................... 12 Verify background events ........................................................................................ 12 Resources ..................................................................................................................... 13

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 3

Introduction
Wi-Fi hotspots have proliferated in public areas such as airports, coffee shops, and hotels. Operators of such networks generally offer Internet access, either as a complimentary service to their clients funded by the venue owner or as a paid offering. Various methods have arisen to handle the need to authenticate to these networks. Open networks with captive portals (called the Universal Access Method in WISPr) are the common denominator, as they are accessible to users on any device equipped with a WLAN interface and a web browser. However, captive portal extensions (WISPr) and alternate authentication methods (Hotspot 2.0, EAP) offer opportunities to streamline the hotspot connection experience. This document addresses the interaction between a Wi-Fi hotspot operator, their app, and Windows 8. The actions described can be taken by a standard app downloaded from the Windows Store, or by an operator app installed by Windows to complement a mobile broadband device attached to the PC.

Hotspot Authentication Methods

Captive Portals
Most hotspots implement customer interaction via a captive portal, a restricted network connection in which all client HTTP requests are redirected to the providers site. This site may then prompt users to agree to the operators terms and conditions, enter payment information, or enter credentials to verify prior payment arrangements. Several problems exist with such an experience: Other applications (such as e-mail clients) are also redirected. If the user attempts to use an app other than the web browser first, they will encounter errors without knowing how to resolve them. If the initial connection attempted is over SSL, the browser displays a security warning to the user prior to encountering the redirect to the captive portal. This creates a confusing experience for users, since they must ignore the security warning to get connected.

Windows 8 supports captive portal networks by immediately launching the web browser if a captive portal is detected. The user will see the operators branded web page in the foreground of their device, helping them understand what actions they should take to authenticate via the captive portal. Windows provides mechanisms which may enable users to bypass captive portals on subsequent attempts. However, the captive portal will always be the experience encountered by a first-time user. In order to offer these users the best possible experience, this section discusses a number of best practices for captive portals.

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 4

Consistent Connection Handling

Windows performs a number of network tests when first connecting to a network in order to determine Internet connectivity and captive portal status. The destination site of these tests is msftncsi.com, a reserved domain used exclusively for connectivity testing. When a captive portal is detected, these tests are repeated periodically until the captive portal is released. In order to avoid false positives or false negatives, your captive portal should not: Allow access to www.msftncsi.com when the user does not have access to the Internet in general. Change the captive portal behavior displayed to clients. For example, do not redirect some requests and drop others; you should continue to redirect all requests until authentication succeeds. o Denial of Service mitigations should be based on frequency of attempts per client, not number of attempts per client or total attempts from all clients.

Touch-Friendly Web Pages

The Windows 8 experience is designed to be touch-first. This extends to web pages. Consider laying out your web page with larger, easy-to-target controls for a touch user. Use layout that doesnt require excessive scrolling to interact with, and break flows into multiple pages if necessary. For more information on touch-friendly web design, see Touch interaction design.

Provisioning after Purchase

The same provisioning file that can be applied by an application can also be applied by a website. In the web pages JavaScript, check for the availability of the window.external.msProvisionNetworks method. If it is present, the browser is able to relay a provisioning file to the operating system. See Providing Mobile Broadband Metadata for more information about generating this provisioning file. Note that this provisioning file must be signed when provided by a website or an app that is not the mobile operator app. Passing an XML provisioning file enables the operating system to automatically connect to other networks included in the users service, even if they have different SSIDs. If you use static WISPr credentials, it also enables a smoother connection experience because Windows can automatically authenticate with those credentials in the future.

Offer App Installation

The richest experience on Windows 8 is through the use of a Windows Store app. It is not possible to allow access to only one app in the Windows Store through a captive portal, so the app cannot be installed prior to the user obtaining Internet connectivity. However, after the user has authenticated, consider directing them to the Windows Store to install your app.

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 5

WISPr Authentication
A WISPr-capable hotspot includes a payload like the following in its captive portal page:
<HTML> <!-<?xml version=1.0 encoding=UTF-8?> <WISPAccessGatewayParam xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation=http://www.acmewisp.com/WISPAccess GatewayParam.xsd> <Redirect> <AccessProcedure>1.0</AccessProcedure> <AccessLocation>Hotel Contoso Guest Network</AccessLocation> <LocationName>Hotel Contoso</LocationName> <LoginURL>https://captiveportal.com/login</LoginURL> <MessageType>100</MessageType> <ResponseCode>0</ResponseCode> </Redirect> </WISPAccessGatewayParam> --> </HTML>

This XML, contained in an HTML comment to avoid its display to customers, is interpreted by a smart client such as Windows to learn where the users credentials must be submitted. When a customer manually connects to a WISPr-capable network, they see the following prompt:

Customers who select No, I need to sign up are directed to the operators captive portal as usual. Customers who select Yes, Ill enter my user name and password are prompted for credentials as part of the Windows connection experience. These credentials are automatically provided to the operators website, and the user is connected after successfully authenticating.

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 6

It is also possible for an operators app to automatically supply credentials or replace the credentials prompt with a tailored purchase or authentication flow. This requires that the network support WISPr, and that the app be installed before the user connects to the network. If your network only offers WISPr to clients with certain UserAgent strings, the user will not see this prompt and cannot manually enter credentials. However, your app can still participate in WISPr authentication by including the appropriate UserAgent when creating the network profile.

Provisioning for Hotspot Authentication

In order for an application to participate in the hotspot authentication process, it must first create one or more profiles for Wi-Fi hotspots. This is done using the Provisioning Agent interface, discussed in Providing Mobile Broadband Metadata. The hotspot must use Open authentication, and must include the HotspotProfile element. The following provisioning file sample shows how to associate an SSID with your app:
<WLANProfile xmlns="http://www.microsoft.com/networking/CarrierControl/WLAN/v1"> <name>Contoso Wi-Fi</name> <SSIDConfig> <SSID> <name>Contoso Wi-Fi___33</name> </SSID> </SSIDConfig> <MSM> <security> <authEncryption> <authentication>open</authentication> <encryption>none</encryption> <useOneX>false</useOneX> </authEncryption> <HotspotProfile xmlns="http://www.microsoft.com/networking/WLAN/HotspotProfile/v1"> <ExtAuth> <ExtensionId>YourAppIdGoesHere</ExtensionId> </ExtAuth> <TrustedDomains> <TrustedDomain>www.mycaptiveportal.com</TrustedDomain> </TrustedDomains> <UserAgent>contoso</UserAgent> </HotspotProfile> </security> </MSM> </WLANProfile>

The ExtensionId field contains the package family name of the app that will be used to generate hotspot credentials. The package family name is automatically generated by Visual Studio. To find the package family name for your application, open the package.appxmanifest file in your Visual Studio solution and go to the Packaging window.

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 7

After the provisioning file is processed, the app with the package family name YourAppIdGoesHere needs to register for the Hotspot Authentication event. It is required that the provisioning file is processed first in order to grant the specified app access to this event. An app can register a single handler for this event. The event registration remains valid as long as there is at least one profile that refers to the corresponding app.
Signing the Provisioning File

Because provisioning modifies system settings that persist after the user has exited or even uninstalled the app, a stricter measure of verification is required than for most APIs. This verification is provided by a combination of operator-specific hardware (the SIM), cryptographic signatures, and user confirmation. Table 1. Requirements for verification
SIM present? Yes, MB provider Yes, MB provider Source of provisioning Mobile operator app Operator web site Signature requirement None Certificate must: User confirmation requirement None None

Chain back to trusted root CA Be associated with mobile broadband hardware in APN database or experience metadata User prompted to confirm the first time the certificate is used; none thereafter

No, Wi-Fi provider

Mobile operator app or web site

Certificate must:

Chain back to trusted root CA Be marked for Extended Validation

Handling large numbers of SSIDs

Multiple SSIDs per profile

If you are provisioning Windows to connect to several SSIDs, it is both possible and recommended to provide multiple SSIDs per profile. This greatly reduces the size of the provisioning file and improves the responsiveness of the PC. If you intend to use the APIs discussed later to mark a network that should no longer be used, these actions apply to all SSIDs covered by the same profile, so it is a best practice to group related SSIDs in a single profile. There is a maximum of ten profiles with 25 primary SSIDs each.
September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 8

Secondary SSIDs

If you need to configure more than 25 SSIDs per profile, you may specify secondary SSIDs for each profile in the SSIDConfig note of the HotspotAuth section. This does not create additional profiles for these networks, but will associate the Hotspot settings from this profile with that SSID. If the user connects manually in the future, creating a new profile, the hotspot settings from this profile are automatically associated with the user-created profile. Because secondary SSIDs will not autoconnect unless the user manually connects to them once, these should be less common networks that most users do not encounter. There is a maximum of 250 secondary SSIDs per profile.
Prefixes

If you need to associate with a particularly large or dynamic set of SSIDs, the secondary SSID list may contain prefixes as well as static SSIDs. This allows you to associate your app with a broad set of SSIDs that have four or more octets in common at the beginning of the SSID. Prefixes may be only secondary SSIDs, not primary. A best practice is to create primary SSIDs for the most common variants, then a secondary prefix to handle the less common cases. A prefix counts as a single secondary SSID, even though it applies to multiple networks. Table 2. SSIDs for profiles
Number of SSIDs 1 - 10 11 - 250 Type of profile Simple WLAN Profile WLAN Profile with multiple primary SSIDs Location of SSID list WLANProfile/SSIDConfig WLANProfile/SSIDConfig Comments None Group related SSIDs into each profile; app and user actions apply to all SSIDs in a profile Make frequentlyencountered SSIDs primary; less common SSIDs should be secondary

250 - 2750

WLAN Profile with multiple primary SSIDs and secondary SSIDs

Primary SSIDs in WLANProfile/SSIDConfig Secondary SSIDs in WLANProfile/HotspotAuth/SSIDConfig

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 9

Number of SSIDs 2750+

Type of profile WLAN Profile with multiple primary SSIDs and secondary SSIDs including prefixes

Location of SSID list Primary SSIDs in WLANProfile/SSIDConfig Secondary SSIDs in WLANProfile/HotspotAuth/SSIDConfig

Comments Put most common variants as primary SSIDs, even if secondary SSID prefixes also cover them.

Handling the Hotspot Authentication Event

The Hotspot Authentication event is triggered by Windows upon the detection of a captive portal that supports WISPr. When the event occurs, the receiving app must immediately call the Windows.Networking.NetworkOperator.HotspotAuthentication.TryGetAuthenticati onContext function with the event token provided as an argument to the event handler. This function returns an object that manages the hotspot authentication attempt. In the event that the function fails, the event handler must exit without performing any additional actions. Properties on the object allow your app to retrieve: The SSID of the wireless network Details about the network adapter that is connected to the hotspot The URL that contained the WISPr message The XML payload of the WISPr message The authentication URL to which credentials are supplied

Other APIs exist to retrieve: The BSSID of the wireless network (see the Windows.Networking.Connectivity namespace) DHCP parameters of the network (see Win32 and COM for Windows Store apps - Networking)

Using this information and any other information your app needs to obtain from the local system or the network, credentials can be generated. The object also contains methods that permit the app to continue or complete the hotspot authentication. Possible paths for the app are covered in the following sections.
Issuing Credentials

In the simplest case, the app generates credentials based on information it has or can retrieve. For example, a username and password are generated using information in the WISPr payload and information about the network adapter.

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 10

After performing any actions necessary to generate or obtain credentials, the app calls the IssueCredentials method on the HotspotAuthenticationContext object. This method permits the app to supply: The UserName WISPr parameter The Password WISPr parameter Arbitrary non-standard parameters to be included in the WISPr response Behavior on failure

In the event that the server rejects the credentials supplied by the application, Windows disconnects from the network and does not reattempt a connection in the current user session. The final flag allows the application to indicate that Windows should never automatically reattempt a connection using this profile if the credentials are unsuccessful.
Abort Authentication

If the app discovers that it cannot generate credentials for the current network (because roaming agreements have changed, information is unavailable, or for another reason), it must call the AbortAuthentication method on the HotspotAuthenticationContext object. Windows disconnects from the network and does not reattempt a connection in the current user session. This function accepts a flag that indicates Windows should never automatically reattempt a connection using this profile. Note that this does not remove the profile from the system, and the app may be asked for credentials again if the user manually attempts to connect to the network. If the profile is completely removed, the app must supply a new provisioning file that removes the associated profile.
Alternate Authentication Methods

If the app is able to authenticate using a method other than WISPr, it may do so. After successfully authenticating to the network using an alternate method, it must complete the connection by calling the SkipAuthentication method on the HotspotAuthenticationContext object. When this method is called, Windows redetects connectivity to the Internet, helping the UI correctly reflect the authenticated state as soon as possible. Note that the Hotspot Authentication event is not invoked for hotspots that do not advertise support for the WISPr protocol. However, this permits an app to choose a different protocol to use in response, or to use a custom version of WISPr if required.
Interacting with the User

In the event that user interaction is required before authentication can proceed, the app must call the TriggerAttentionRequired method on the HotspotAuthenticationContext object. This is useful in circumstances such as: The user has elected not to store credentials in the app and needs to sign in. Connecting will charge the users credit card or other account, and consent is required before proceeding.

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 11

No credit is available on the users account, and a new purchase is required.

This method does not complete the authentication. When this method is invoked, the app requests to be launched in the foreground with the specified arguments. The event token should be passed to the foreground application so that it can retrieve the HotspotAuthenticationContext object again and complete the authentication using one of the other three methods. The apps request to launch is not guaranteed to succeed. The Hotspot Authentication event may occur due to an automatic connection while the PC is in Connected Standby. The app is launched only when the PC is no longer in Connected Standby, has been unlocked, and is still connected to the wireless network. Because this delays Internet access until the user unlocks the PC, this state should be avoided whenever credentials can be generated automatically.

Hotspot 2.0
Hotspot 2.0 is a newer standard for seamless authentication to hotspots. Rather than the current industry practice of unencrypted hotspot networks, Hotspot 2.0 offers an encrypted connection between the client and the access point, using IEEE 802.11u to communicate with the provider prior to establishing a connection. Authentication and encryption are provided by using WPA2-Enterprise with one of several EAP methods. Windows does not support the discovery or online sign-up portions of Hotspot 2.0, but does support WPA2-Enterprise and all EAP methods required by the Hotspot 2.0 specification. Therefore, Windows 8 is capable of connecting to a Hotspot 2.0 network when the user already has credentials. These are the common credential types defined by Hotspot 2.0: Table 3. Hotspot 2.0 credential types Credential EAP method EAP User can Operator can method enter provision supported credentials credentials Username and EAP-TTLS Yes Yes No password Yes* Certificate EAP-TLS Yes No SIM EAP-SIM or Yes Yes* Yes EAP-AKA *User can select from certificates or SIMs already present on the system. Because Windows does not support 802.11u discovery, operators must provision Windows with wireless profiles containing the applicable SSIDs for their networks.

Getting started with a Hotspot Authentication app

Review the sample
The Hotspot Authentication Sample demonstrates the application of a provisioning file and the handling of the hotspot authentication event. This sample does not run with privileged APIs, meaning it demonstrates the application of signed provisioning

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 12

metadata. For an example using unsigned provisioning metadata with privilege APIs, see the Mobile Broadband Provisioning sample.

Update the sample

The sample project uses a default carrier ID and application family name. In order to use the sample in your own test environment, you need to change the following items: Update your Carrier ID. If you are publishing a mobile operator app, this should be the Experience ID associated with your application and service metadata. If you are a Wi-Fi-only operator, generate a new GUID to use as your companys ID. Update the SSID. The SSID you use for test should match the SSID in the provisioning file and must offer captive portal and WISPr challenge to connecting clients. Sign the provisioning file. If you are a Wi-Fi-only operator, you need to sign the provisioning file. In the Windows 8 SDK, find the tool ProvisioningTestHelper.psd1. Importing this tool into a PowerShell session adds four additional cmdlets: o Install-TestEVCert: Generates a new CA certificate, registers it on your test machine as a trusted EV SSL provider, and uses it to generate and sign an EV certificate for use in signing. ConvertTo-SignedXml: Uses an EV certificate (generated for test, or issued by a third-party provider) to apply an XML-DSig signature to a Provisioning Metadata XML file. This signature from a trusted certificate causes Windows to accept the provisioning file as valid from an operator app with no affiliated hardware. Test-SignedXml: Checks a provisioning file to ensure schema conformance and valid signature. Install-RootCertFromFile: Applies the test root certificate on a different machine, in order to test the client experience on a machine other than the development PC.

o o

Verify background events

After connecting to your hotspot network, check that the background event is launched. If not, check the following: Did Windows detect your hotspot? If so, the network list should indicate a limited connection. If Windows detects connectivity to the Internet after connecting to the network, no hotspot authentication actions will be taken. Did Windows detect WISPr on your hotspot? If so, the background event will fire or the user will be prompted for credentials. If Windows opens the browser instead, WISPr was not detected. Check that the XML message is

September 28, 2012 2012 Microsoft. All rights reserved.

Windows 8 Integration for Wireless Hotspot Operators - 13

present in the browsers redirect page and that it conforms to the WISPr specification. Is your app correctly associated with the profile? If so, the background event will fire. If not, the user will be prompted for credentials upon manually connecting to the network. Check that the application family name specified as the ExtensionId matches your application and that provisioning was successful.

Next, check that you are able to successfully handle authenticate to the network. In particular, you should cover the following cases: Successful authentication: In the ideal case, your app can provide credentials and connect the user to the network. User interaction: If you need to interact with the user in certain cases, ensure that your app launches to the correct context to perform the interaction, and not simply to you apps home page. Unsuccessful authentication: Particularly when using prefixes, you should handle the possibility that a network matches your prefix, but you are not able to generate credentials for it. In this case, you should abort authentication. Access denied: In certain cases, your app will receive the background event, but may not be able to retrieve the details of the authentication attempt. In this case, your background event should cleanly terminate as soon as possible.

Resources
Designing for Touch http://go.microsoft.com/fwlink/?LinkId=244250 Providing Mobile Broadband Metadata http://go.microsoft.com/fwlink/?linkid=242064

September 28, 2012 2012 Microsoft. All rights reserved.