chrome.networking.config

Description: Use the networking.config API to authenticate to captive portals.
Availability: Since Chrome 43.
Permissions: "networking.config"

Important: This API works only on Chrome OS.

Implementing a Captive Portal Authenticator

This API allows an Extension to implement an authenticator for captive portals. The interaction between Extension, Chrome, and the user will be:
  1. Using setNetworkFilter, the Extension registers for a list of Wi-Fi networks that it wants to handle captive portals on.
  2. If one of these networks is detected by Chrome, it will appear in the network list, badged with an icon to indicate that a captive portal handler is available.

    Badge icon in tray network list

  3. If the user selects such a network, but a captive portal is not detected, Chrome will connect as usual - the Extension will never be involved.
  4. Otherwise, if a captive portal is detected, the user is notified and asked to authenticate using the registered Extension or whether to visit the captive portal page.

    Captive portal notification

  5. If the user selects the Extension, Chrome notifies the Extension through the onCaptivePortalDetected event.
  6. The Extension should now interact with the user if necessary and authenticate at the captive portal.
  7. Once the Extension finished the authentication, it notifies the API using finishAuthentication about its success or failure.

In the Extension, this can look similar to the following snippet:

      var myNetworks = [
        { Type: 'WiFi', SSID: 'MyHotSpot-1' },
        { Type: 'WiFi', SSID: 'MyHotSpot-2' }
      ];
      
      chrome.networking.config.setNetworkFilter(myNetworks, function() {
          if (chrome.runtime.lastError) {
              // Handle Error
          }
      });
      
      chrome.networking.config.onCaptivePortalDetected.addListener(
        function(networkInfo) {
          var guid = networkInfo.GUID;
      
          // Check at first whether we really care about this network.
          // This can look at additional network properties like BSSID that are not
          // supported in the filter.
          if (isBadNetwork(networkInfo)) {
            chrome.networking.config.finishAuthentication(guid, 'unhandled');
            return;
          }
          checkForMyCaptivePortalServer(function(serverStatus) {
            if (serverStatus == 'not-detected') {
              chrome.networking.config.finishAuthentication(guid, 'unhandled');
              return;
            }
            if (serverStatus == 'error') {
              chrome.networking.config.finishAuthentication(guid, 'failed');
              return;
            }
      
            // If required, interact with the user, e.g. for registration on first
            // usage. Credentials can be cached for subsequent authentications.
            ShowUIToRegisterUser(continueAuthentication.bind(null, guid));
          });
      });
      
      function continueAuthentication(guid, credentials) {
        if (!credentials) {
          chrome.networking.config.finishAuthentication(guid, 'failed');
        }
        AuthenticateToMyCaptivePortalServer(credentials, function(success) {
          chrome.networking.config.finishAuthentication(
              guid, success ? 'succeeded' : 'rejected');
        });
      }
      

Summary

Types
NetworkInfo
Methods
setNetworkFilter chrome.networking.config.setNetworkFilter(array of NetworkInfo networks, function callback)
finishAuthentication chrome.networking.config.finishAuthentication(string GUID, enum of "unhandled", "succeeded", "rejected", or "failed" result, function callback)
Events
onCaptivePortalDetected

Types

NetworkInfo

properties
enum of or "WiFi" Type

Currently only WiFi supported.

string (optional) GUID

A unique identifier of the network.

string (optional) HexSSID

A hex-encoded byte sequence.

string (optional) SSID

The decoded SSID of the network (default encoding is UTF-8). To filter for non-UTF-8 SSIDs, use HexSSID instead.

string (optional) BSSID

The basic service set identification (BSSID) uniquely identifying the basic service set. BSSID is represented as a human readable, hex-encoded string with bytes separated by colons, e.g. 45:67:89:ab:cd:ef.

string (optional) Security

Identifier indicating the security type of the network. Valid values are None, WEP-PSK, WPA-PSK and WPA-EAP.

Methods

setNetworkFilter

chrome.networking.config.setNetworkFilter(array of NetworkInfo networks, function callback)

Allows an extension to define network filters for the networks it can handle. A call to this function will remove all filters previously installed by the extension before setting the new list.

Parameters
array of NetworkInfo networks

Network filters to set. Every NetworkInfo must either have the SSID or HexSSID set. Other fields will be ignored.

function callback

Called back when this operation is finished.

The callback parameter should be a function that looks like this:

function() {...};

finishAuthentication

chrome.networking.config.finishAuthentication(string GUID, enum of "unhandled", "succeeded", "rejected", or "failed" result, function callback)

Called by the extension to notify the network config API that it finished a captive portal authentication attempt and hand over the result of the attempt. This function must only be called with the GUID of the latest onCaptivePortalDetected event.

Parameters
string GUID

Unique network identifier obtained from onCaptivePortalDetected.

enum of "unhandled", "succeeded", "rejected", or "failed" result

The result of the authentication attempt.

unhandled
The extension does not handle this network or captive portal (e.g. server end-point not found or not compatible).
succeeded
The extension handled this network and authenticated successfully.
rejected
The extension handled this network, tried to authenticate, however was rejected by the server.
failed
The extension handled this network, tried to authenticate, however failed due to an unspecified error.
function (optional) callback

Called back when this operation is finished.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

Events

onCaptivePortalDetected

This event fires everytime a captive portal is detected on a network matching any of the currently registered network filters and the user consents to use the extension for authentication. Network filters may be set using the setNetworkFilter. Upon receiving this event the extension should start its authentication attempt with the captive portal. When the extension finishes its attempt, it must call finishAuthentication with the GUID received with this event and the appropriate authentication result.

addListener

chrome.networking.config.onCaptivePortalDetected.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( NetworkInfo networkInfo) {...};
NetworkInfo networkInfo

Information about the network on which a captive portal was detected.