Overview

Public Wi-Fi networks offering temporary internet access often begin new connections using a Captive Portal Mini-Browser (or “CPMB”). These CPMB utilities are built into operating systems in order to make it easier to connect to public Wi-Fi networks. The problem is that their behavior is nuanced, often undocumented and can be difficult to understand.

The goal for this project is to document captive portal behavior across the various client devices and to hopefully make it easier to build captive portal solutions that offer a better experience for users.

Organized by the WBA

This project is organized by the Wireless Broadband Alliance (WBA). The aim of the WBA, together with its 100+ members, is to secure an outstanding user experience through the global deployment of next generation Wireless. While the WBA organizes this project, anyone is encouraged to contribute. Please see the GitHub repository to learn how or contact the WBA to find out more.

Device Database

Go to Device Database

Go to Device Submission Form

Captive Network Portal Standards Whitepaper

The Captive Network Portal Standards whitepaper defines existing use cases, aligns user experience (UX), presents practices to consider and provides suggested guidelines for future features that can be adopted as a unified standard by client devices, client manufacturers and network hardware manufacturers.

The Captive Portal - Onboarding Evolution WBA workgroup is continuing to focus on improving the user experience of “captivation” and how end-users engage with captive portals in the Passpoint® era. You can learn more about the team behind the Captive Network Portal Standards project and the above whitepaper here.

Contents

• Connection Process
• Device Behavior Summary
• Device Behavior
  • iOS
  • Android (Google)
  • Android (Samsung)
  • MacOS
  • Windows
  • ChromeOS
  • FireOS
  • Linux
• List of Captive Portal Check URLs

Connection Process

The connection process for the CPMB usually involves the following steps:

• Network/Access Point Association
• Checking connectivity state (detection of Captive Network)
• Pop-up of a notification (in some cases)
• Waiting for device activation (if device is in a blocked state)
• Opening CPMB or waiting for the activation of the notification
• Checking current connectivity state based on user’s action while CPMB is open
• Closing CPMB after authentication process is completed (automatically or manually)

Device Behavior Summary (latest versions)

Platform	Captive Portal Display Method	Default Browser	Details
iOS	Mini-Browser Popup	Websheet	More Details
Android	Push Notification	Google Chrome	More Details
Samsung Android	Push Notification	Samsung Internet Browser	More Details
MacOS	Mini-Browser Popup	Safari	More Details
Windows 10	Manual Browser Redirect	User’s Preferred Browser	More Details

Device Behavior

General Behavior (for most devices)

• There are no persistent cookies in CPMB: all the written cookies are destroyed after CPMB closes.

• CPMB closes after authorization is completed (sometimes it requires additional actions from the user)

• The CPMB disappears and the device disconnects from the network when focus is changed to another app, such as SMS or email.

• Most external services (file system, applications and etc.) are not accessible from CPMB. There are various differences in device behavior in pre-authenticated vs post-authenticated states, along with many limitations including memory usage, local storage, Javascript support etc.

iOS (latest)

• The standard flow for the Captive Network authentication process starts with Wi-Fi association. It doesn’t matter what kind of Wi-Fi association protocol is used (Hotspot 2.0 or other), in all cases just after the association is complete, the device makes a request for an IP-address (DHCP DISCOVER).

• After receiving an IP-address, the device goes to check http://captive.apple.com/hotspot-detect.html (exact domain and URI could be different from this one: see appendix for complete list) via so-called CNA Helper.

• In this request the device uses a specific User-Agent: “CaptiveNetworkSupport-355.200.27 wispr” (the version mentioned could be different). The received answer is analyzed to verify if the existence of Web-authorization and in case of detection, Wi-Fi network marks as captive (appropriate switches appears in the network settings), and switching from cellular connection to Wi-Fi doesn’t appear otherwise the device switches to the Wi-Fi connection as major one.

• In the case of association with a known Captive Network SSID when the device is not active (in a locked state in a pocket, for example), there are no further requests produced by device before unlocking. After this device is unlocked, additional checking requests are made and in case of Web-authorization confirms, CPMB is rising.

• When CPMB is risen it generate additional request to http://captive.apple.com/hotspot-detect.html (see appendix for complete list) but with different kind of User-Agent: “Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/16A366” (the version mentioned could be different). During authorization process in CPMB, almost all network actions followed by additional checks of current state.

• When the CPMB detects that the captive domain is accessible, it changes the control button in the top right corner from “Cancel” to “Done” and switches the primary connection from cellular network to Wi-Fi. The CPMB only performs a check of the captive domain after a full URL navigation or by timer. A javascript-triggered AJAX call for example will not result in the CPMB performing an additional check of the captive domain. With a single page app that does not redirect to a separate post-authentication landing page, a full page navigation must occur for the CPMB to change the control button from “Cancel’ to “Done”. If this doesn’t happen, the user’s device will be authenticated and connected to Wi-Fi but the CPMB will only provide the “Cancel” option, which will disassociate the device from the SSID and take the user back the Wi-Fi network selection screen in the Settings menu.

• Sometimes, after several connections to the Wi-Fi network without Captive Portal with the same SSID as used in Captive Network, iOS may switch off Captive Checker for this particular SSID and there will no Captive Browser rising

iOS (With VPN)

With VPN or some other software that blocks Captive Detector Installed

• Normally, there is a local Push-notification raise instead of CPMB.
• Observed in iOS 11+

iOS (With “Auto-Connect” disabled)

With “Auto-connect” selector in the Wi-Fi SSID settings switched off.

• The CPMB does not display automatically. Manual redirection from a browser is needed.
• Observed in iOS 6+

Android (Google) Latest CNA Behavior

• The Android OS determines the existence of the captive portal by attempting to access a list of domains (See appendix for complete list). If the domains are accessible, it can assume that it is not constrained by a captive portal. Otherwise, it will trigger the notification.

• When clicked, users are redirected to CPMB.

• PostAuth experience – Once a user has successfully authenticated, the mini-browser may be hidden automatically or manually by pressing a button.

Android (Samsung)

• Active Captive Portal - Notifies user about the need to log in by pushing the OS-level mini browser.

• The Android OS determines the existence of the captive portal by attempting to access a list of domains (See appendix for complete list). If the domains are accessible, it can assume that it is not constrained by a captive portal. Otherwise, it will pops up Captive Portal or Full browser.

• Post-auth experience – Once a user has successfully authenticated, the mini-browser may be hidden automatically or manually by pressing some special button.

• It can be artificial ad block on CPMB in some Android devices.

MacOS

• Native Mini-Browser – AKA “Captive Network Assistant” (CNA) - Notifies user about the need to log in by pushing the OS-level mini browser.

• It displays a browser window that is 900px wide by 572px tall

• Javascript methods window.alert() and window.confirm() do not work

Windows 10

• Notifies user about the need to log in by opening the user’s default browser and attempting to redirect the user to a default HTTP destination which should be intercepted by the network.

Chrome OS

• Connection manager for Chrome OS attempts to retrieve the web page http://clients3.google.com/generate_204. This well known URL is known to return an empty page with an HTTP status 204. If for any reason the web page is not returned, or an HTTP response other than 204 is received, then shill marks the service as being in the portal state.

• Other captive portals, sometimes run by cellular carriers, provide absolutely no IP connectivity other than to their own servers, but they use a standard DNS server and do not intercept HTTP requests. When a Chrome Book connects to this type of network, the HTTP requests fail because the TCP connection to clients3.google.com can never be established. The portal code tries multiple times for up to 10 seconds to connect to clients3.google.com. If it cannot connect it marks the service as being in a captive portal. This determination is somewhat unreliable because very high latency connections, lossy connections and other network issues can also result in failure to connect to clients3.google.com. All of these are indicative of a network that is not fully functional, but they do not necessarily indicate that the machine is stuck in a captive portal.

Linux

Ubuntu

• Doesn’t support OS level captive portal login in available LTS (long term support) releases so far. Now there is a discussion in Ubuntu WiKi networking section where it is proposed to provide OS level support in coming releases. GNOME (GNU Network Object Model Environment) had introduced automatic login prompt for Wi-Fi captive portals (Wi-Fi access points which required web based login, such as those found in public places) quite a while ago. However this functionality is still unavailable in Ubuntu GNOME, The same is part of wish-list in upcoming Ubuntu LTS releases.

Linux (Firefox Browser Installed)

• Firefox introduces automatic detection of Captive portals and notifies user about the need to log in. Additionally, after Firefox detects a Captive portal, it replaces certificate error pages with a message encouraging user to log in.

• Firefox determines the existence of a captive portal constraint by attempting to download the file success.txt from http://detectportal.firefox.com/success.txt (there is only one word in that file, the word “success”. If it can successfully retrieve that file, it can assume that it is not constrained by a Captive portal. Otherwise, it will trigger an in-browser notification.

Linux (Chrome Browser Installed)

• Chrome introduces automatic detection of Captive portals and notifies user about the need to log in. Additionally, after Chrome detects a Captive portal, it replaces certificate error pages with a message encouraging user to log in.

FireOS

• Fire OS (based on Android) uses http://spectrum.s3.amazonaws.com/kindle-wifi/wifistub.html for connectivity checks and if the URI is not reachable, a notification appears indicating a captive portal login is required.

• Tapping the notifications triggers the the captive portal mini-browser to open, the device attempts to reach http://spectrum.s3.amazonaws.com/kindle-wifi/wifiredirect.html and the user is greeted with “Unsecured Connection. This connection is not secure. When using an unsecured connection, your personal information may be visible to others.” After clicking continue, the captive portal loads.

• The Unsecured Connection warning appears to be triggered by the attempt to hit the “wifiredirect” page over HTTP, not because of a TLS certificate mismatch.

List of captive portal check URLs

Apple iOS

• www.apple.com
• www.appleiphonecell.com
• captive.apple.com
• www.airport.us
• www.ibook.info
• www.itools.info
• www.thinkdifferent.us
• apple.com

Apple MacOS

• captive.apple.com

Google Android

• clients3.google.com
• clients4.google.com
• android.clients.google.com
• connectivitycheck.android.com
• connectivitycheck.gstatic.com
• www.gstatic.com
• www.google.com
• www.androidbak.net

Samsung Android

• http://connectivitycheck.android.com/generate_204
• http://connectivitycheck.gstatic.com/generate_204
• d2uzsrnmmf6tds.cloudfront.net

HTC Android

• clients3.google.com

Windows

• msftncsi.com