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:- Using setNetworkFilter, the Extension registers for a list of Wi-Fi networks that it wants to handle captive portals on.
- 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.
- 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.
- 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.
- If the user selects the Extension, Chrome notifies the Extension through the onCaptivePortalDetected event.
- The Extension should now interact with the user if necessary and authenticate at the captive portal.
- 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
| |
Events | |
onCaptivePortalDetected |
Types
NetworkInfo
properties | ||
---|---|---|
enum of "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. |
string | (optional) Security |
Identifier indicating the security type of the network. Valid values are |
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 |
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.
|
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) {...};
|