chrome.networking.onc

Description

The chrome.networking.onc API is used for configuring network connections (Cellular, Ethernet, VPN or WiFi). This API is available in auto-launched Chrome OS kiosk sessions.

Network connection configurations are specified following Open Network Configuration (ONC) specification.

NOTE: Most dictionary properties and enum values use UpperCamelCase to match the ONC specification instead of the JavaScript lowerCamelCase convention.

Permissions

networking.onc

Availability

Chrome 59+ ChromeOS only

Types

ActivationStateType

Enum

"Activated"

"Activating"

"NotActivated"

"PartiallyActivated"

CaptivePortalStatus

Enum

"Unknown"

"Offline"

"Online"

"Portal"

"ProxyAuthRequired"

CellularProperties

Properties

  • ActivationState

    Carrier account activation state.

  • ActivationType

    string optional

    The cellular network activation type.

  • AllowRoaming

    boolean optional

    Whether roaming is allowed for the network.

  • AutoConnect

    boolean optional

    Whether the cellular network should be connected automatically (when in range).

  • Family

    string optional

    Cellular device technology family - CDMA or GSM.

  • FirmwareRevision

    string optional

    The firmware revision loaded in the cellular modem.

  • FoundNetworks

    The list of networks found during the most recent network scan.

  • HardwareRevision

    string optional

    The cellular modem hardware revision.

  • HomeProvider

    Information about the operator that issued the SIM card currently installed in the modem.

  • Manufacturer

    string optional

    The cellular modem manufacturer.

  • ModelID

    string optional

    The cellular modem model ID.

  • NetworkTechnology

    string optional

    If the modem is registered on a network, the network technology currently in use.

  • PaymentPortal

    PaymentPortal optional

    Online payment portal a user can use to sign-up for or modify a mobile data plan.

  • RoamingState

    string optional

    The roaming state of the cellular modem on the current network.

  • SIMLockStatus

    SIMLockStatus optional

    The state of SIM lock for GSM family networks.

  • SIMPresent

    boolean optional

    Whether a SIM card is present.

  • Scanning

    boolean optional

    Chrome 63+

    True when a cellular network scan is in progress.

  • ServingOperator

    Information about the operator on whose network the modem is currently registered.

  • SignalStrength

    number optional

    The current network signal strength.

  • SupportNetworkScan

    boolean optional

    Whether the cellular network supports scanning.

CellularProviderProperties

Properties

  • Code

    string

    Cellular network ID as a simple concatenation of the network's MCC (Mobile Country Code) and MNC (Mobile Network Code).

  • Country

    string optional

    The two-letter country code.

  • Name

    string

    The operator name.

CellularStateProperties

Properties

CertificatePattern

Properties

  • EnrollmentURI

    string[] optional

    List of URIs to which the user can be directed in case no certificates that match this pattern are found.

  • Issuer

    If set, pattern against which X.509 issuer settings should be matched.

  • IssuerCARef

    string[] optional

    List of certificate issuer CA certificates. A certificate must be signed by one of them in order to match this pattern.

  • Subject

    If set, pattern against which X.509 subject settings should be matched.

ClientCertificateType

Enum

"Ref"

"Pattern"

ConnectionStateType

Enum

"Connected"

"Connecting"

"NotConnected"

DeviceStateProperties

Properties

  • SIMLockStatus

    SIMLockStatus optional

    Chrome 62+

    The SIM lock status if Type = Cellular and SIMPresent = True.

  • SIMPresent

    boolean optional

    Chrome 62+

    Set to the SIM present state if the device type is Cellular.

  • Scanning

    boolean optional

    Set if the device is enabled. True if the device is currently scanning.

  • The current state of the device.

  • The network type associated with the device (Cellular, Ethernet or WiFi).

DeviceStateType

Enum

"Uninitialized"
Device is available but not initialized.

"Disabled"
Device is initialized but not enabled.

"Enabling"
Enabled state has been requested but has not completed.

"Enabled"
Device is enabled.

"Prohibited"
Device is prohibited.

EAPProperties

Properties

  • AnonymousIdentity

    string optional

  • ClientCertPKCS11Id

    string optional

    Chrome 60+
  • ClientCertPattern
  • ClientCertProvisioningProfileId

    string optional

    Chrome 93+
  • ClientCertRef

    string optional

  • ClientCertType
  • Identity

    string optional

  • Inner

    string optional

  • Outer

    string optional

    The outer EAP type. Required by ONC, but may not be provided when translating from Shill.

  • Password

    string optional

  • SaveCredentials

    boolean optional

  • ServerCAPEMs

    string[] optional

  • ServerCARefs

    string[] optional

  • SubjectMatch
    Chrome 60+
  • UseProactiveKeyCaching

    boolean optional

  • UseSystemCAs

    boolean optional

EthernetProperties

Properties

  • Authentication

    string optional

    The authentication used by the Ethernet network. Possible values are None and 8021X.

  • AutoConnect

    boolean optional

    Whether the Ethernet network should be connected automatically.

  • EAP

    EAPProperties optional

    Network's EAP settings. Required for 8021X authentication.

EthernetStateProperties

Properties

FoundNetworkProperties

Properties

  • LongName

    string optional

    The network operator's long-format name.

  • NetworkId

    string

    Network ID.

  • ShortName

    string optional

    The network operator's short-format name.

  • Status

    string

    Network availability.

  • Technology

    string

    Access technology used by the network.

GlobalPolicy

Properties

  • AllowOnlyPolicyNetworksToAutoconnect

    boolean optional

    If true, only policy networks may auto connect. Defaults to false.

  • AllowOnlyPolicyNetworksToConnect

    boolean optional

    If true, only policy networks may be connected to and no new networks may be added or configured. Defaults to false.

  • AllowOnlyPolicyNetworksToConnectIfAvailable

    boolean optional

    Chrome 70+

    If true and a managed network is available in the visible network list, only policy networks may be connected to and no new networks may be added or configured. Defaults to false.

  • BlockedHexSSIDs

    string[] optional

    Chrome 86+

    List of blocked networks. Connections to blocked networks are prohibited. Networks can be unblocked again by specifying an explicit network configuration. Defaults to an empty list.

IPConfigProperties

Properties

  • ExcludedRoutes

    string[] optional

    Chrome 76+

    Array of IP blocks in CIDR notation, see onc_spec.md for details.

  • Gateway

    string optional

    Gateway address used for the IP configuration.

  • IPAddress

    string optional

    The IP address for a connection. Can be IPv4 or IPv6 address, depending on value of Type.

  • IncludedRoutes

    string[] optional

    Chrome 76+

    Array of IP blocks in CIDR notation, see onc_spec.md for details.

  • NameServers

    string[] optional

    Array of addresses used for name servers.

  • RoutingPrefix

    number optional

    The routing prefix.

  • SearchDomains

    string[] optional

    Chrome 76+

    Array of strings for name resolution, see onc_spec.md for details.

  • Type

    string optional

    The IP configuration type. Can be IPv4 or IPv6.

  • WebProxyAutoDiscoveryUrl

    string optional

    The URL for WEb Proxy Auto-Discovery, as reported over DHCP.

IPConfigType

Enum

"DHCP"

"Static"

IssuerSubjectPattern

Properties

  • CommonName

    string optional

    If set, the value against which to match the certificate subject's common name.

  • Locality

    string optional

    If set, the value against which to match the certificate subject's common location.

  • Organization

    string optional

    If set, the value against which to match the certificate subject's organizations. At least one organization should match the value.

  • OrganizationalUnit

    string optional

    If set, the value against which to match the certificate subject's organizational units. At least one organizational unit should match the value.

ManagedBoolean

Properties

  • Active

    boolean optional

    The active value currently used by the network configuration manager (e.g. Shill).

  • DeviceEditable

    boolean optional

    Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • DevicePolicy

    boolean optional

    The property value provided by the device policy.

  • Effective

    string optional

    The source from which the effective property value was determined.

  • SharedSetting

    boolean optional

    The value set for all users of the device. Only provided if DeviceEditiable is true.

  • UserEditable

    boolean optional

    Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • UserPolicy

    boolean optional

    The property value provided by the user policy.

  • UserSetting

    boolean optional

    The property value set by the logged in user. Only provided if UserEditable is true.

ManagedCellularProperties

Properties

ManagedDOMString

Properties

  • Active

    string optional

    The active value currently used by the network configuration manager (e.g. Shill).

  • DeviceEditable

    boolean optional

    Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • DevicePolicy

    string optional

    The property value provided by the device policy.

  • Effective

    string optional

    The source from which the effective property value was determined.

  • SharedSetting

    string optional

    The value set for all users of the device. Only provided if DeviceEditiable is true.

  • UserEditable

    boolean optional

    Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • UserPolicy

    string optional

    The property value provided by the user policy.

  • UserSetting

    string optional

    The property value set by the logged in user. Only provided if UserEditable is true.

ManagedDOMStringList

Properties

  • Active

    string[] optional

    The active value currently used by the network configuration manager (e.g. Shill).

  • DeviceEditable

    boolean optional

    Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • DevicePolicy

    string[] optional

    The property value provided by the device policy.

  • Effective

    string optional

    The source from which the effective property value was determined.

  • SharedSetting

    string[] optional

    The value set for all users of the device. Only provided if DeviceEditiable is true.

  • UserEditable

    boolean optional

    Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • UserPolicy

    string[] optional

    The property value provided by the user policy.

  • UserSetting

    string[] optional

    The property value set by the logged in user. Only provided if UserEditable is true.

ManagedEthernetProperties

Properties

ManagedIPConfigProperties

Properties

ManagedIPConfigType

Properties

  • Active

    IPConfigType optional

    The active value currently used by the network configuration manager (e.g. Shill).

  • DeviceEditable

    boolean optional

    Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • DevicePolicy

    IPConfigType optional

    The property value provided by the device policy.

  • Effective

    string optional

    The source from which the effective property value was determined.

  • SharedSetting

    IPConfigType optional

    The value set for all users of the device. Only provided if DeviceEditiable is true.

  • UserEditable

    boolean optional

    Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • UserPolicy

    IPConfigType optional

    The property value provided by the user policy.

  • UserSetting

    IPConfigType optional

    The property value set by the logged in user. Only provided if UserEditable is true.

ManagedLong

Properties

  • Active

    number optional

    The active value currently used by the network configuration manager (e.g. Shill).

  • DeviceEditable

    boolean optional

    Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • DevicePolicy

    number optional

    The property value provided by the device policy.

  • Effective

    string optional

    The source from which the effective property value was determined.

  • SharedSetting

    number optional

    The value set for all users of the device. Only provided if DeviceEditiable is true.

  • UserEditable

    boolean optional

    Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • UserPolicy

    number optional

    The property value provided by the user policy.

  • UserSetting

    number optional

    The property value set by the logged in user. Only provided if UserEditable is true.

ManagedManualProxySettings

ManagedProperties

Properties

ManagedProxyLocation

ManagedProxySettings

ManagedProxySettingsType

Properties

  • Active

    The active value currently used by the network configuration manager (e.g. Shill).

  • DeviceEditable

    boolean optional

    Whether a DevicePolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • DevicePolicy

    The property value provided by the device policy.

  • Effective

    string optional

    The source from which the effective property value was determined.

  • SharedSetting

    The value set for all users of the device. Only provided if DeviceEditiable is true.

  • UserEditable

    boolean optional

    Whether a UserPolicy for the property exists and allows the property to be edited (i.e. the policy set recommended property value). Defaults to false.

  • UserPolicy

    The property value provided by the user policy.

  • UserSetting

    The property value set by the logged in user. Only provided if UserEditable is true.

ManagedThirdPartyVPNProperties

Properties

ManagedVPNProperties

Properties

ManagedWiFiProperties

Properties

ManualProxySettings

Properties

NetworkConfigProperties

Properties

NetworkFilter

Properties

  • configured

    boolean optional

    If true, only include configured (saved) networks. Defaults to 'false'.

  • limit

    number optional

    Maximum number of networks to return. Defaults to 1000 if unspecified. Use 0 for no limit.

  • networkType

    The type of networks to return.

  • visible

    boolean optional

    If true, only include visible (physically connected or in-range) networks. Defaults to 'false'.

NetworkProperties

Properties

  • Cellular

    For cellular networks, cellular network properties.

  • Connectable

    boolean optional

    Whether the network is connectable.

  • ConnectionState

    The network's current connection state.

  • ErrorState

    string optional

    The last recorded network error state.

  • Ethernet

    For Ethernet networks, the Ethernet network properties.

  • GUID

    string

    The network GUID.

  • IPAddressConfigType

    IPConfigType optional

    The network's IP address configuration type.

  • IPConfigs

    IPConfigProperties[] optional

    The network's IP configuration.

  • MacAddress

    string optional

    The network's MAC address.

  • Metered

    boolean optional

    Chrome 85+

    Whether the network is metered.

  • Name

    string optional

    A user friendly network name.

  • NameServersConfigType

    IPConfigType optional

    The IP configuration type for the name servers used by the network.

  • Priority

    number optional

    The network priority.

  • ProxySettings

    ProxySettings optional

    The network's proxy settings.

  • RestrictedConnectivity

    boolean optional

    For a connected network, whether the network connectivity to the Internet is limited, e.g. if the network is behind a portal, or a cellular network is not activated.

  • SavedIPConfig

    IP configuration that was received from the DHCP server before applying static IP configuration.

  • Source

    string optional

    Indicates whether and how the network is configured. Possible values are:

    • Device
    • DevicePolicy
    • User
    • UserPolicy
    • None

    'None' conflicts with extension code generation so we must use a string for 'Source' instead of a SourceType enum.

  • StaticIPConfig

    The network's static IP configuration.

  • The network type.

  • VPN

    VPNProperties optional

    For VPN networks, the network VPN properties.

  • WiFi

    WiFiProperties optional

    For WiFi networks, the network WiFi properties.

NetworkStateProperties

Properties

NetworkType

Enum

"All"

"Cellular"

"Ethernet"

"Tether"

"VPN"

"Wireless"

"WiFi"

PaymentPortal

Properties

  • Method

    string

    The HTTP method to use for the payment portal.

  • PostData

    string optional

    The post data to send to the payment portal. Ignored unless Method is POST.

  • Url

    string optional

    The payment portal URL.

ProxyLocation

Properties

  • Host

    string

    The proxy IP address host.

  • Port

    number

    The port to use for the proxy.

ProxySettings

Properties

  • ExcludeDomains

    string[] optional

    Domains and hosts for which manual proxy settings are excluded.

  • Manual

    Manual proxy settings - used only for Manual proxy settings.

  • PAC

    string optional

    URL for proxy auto-configuration file.

  • The type of proxy settings.

ProxySettingsType

Enum

"Direct"

"Manual"

"PAC"

"WPAD"

SIMLockStatus

Properties

  • LockEnabled

    boolean

    Whether SIM lock is enabled.

  • LockType

    string

    The status of SIM lock - possible values are 'sim-pin', 'sim-puk' and ''.

  • RetriesLeft

    number optional

    Number of PIN lock tries allowed before PUK is required to unlock the SIM.

ThirdPartyVPNProperties

Properties

  • ExtensionID

    string

    ID of the third-party VPN provider extension.

  • ProviderName

    string optional

    The VPN provider name.

VPNProperties

Properties

  • AutoConnect

    boolean optional

    Whether the VPN network should be connected automatically.

  • Host

    string optional

    The VPN host.

  • Type

    string optional

    The VPN type. This cannot be an enum because of 'L2TP-IPSec'. This is optional for NetworkConfigProperties which is passed to setProperties which may be used to set only specific properties.

VPNStateProperties

Properties

WiFiProperties

Properties

  • AllowGatewayARPPolling

    boolean optional

    Whether ARP polling of default gateway is allowed. Defaults to true.

  • AutoConnect

    boolean optional

    Whether the WiFi network should be connected automatically when in range.

  • BSSID

    string optional

    The BSSID of the associated access point..

  • EAP

    EAPProperties optional

    The network EAP properties. Required for WEP-8021X and WPA-EAP networks.

  • Frequency

    number optional

    The WiFi service operating frequency in MHz. For connected networks, the current frequency on which the network is connected. Otherwise, the frequency of the best available BSS.

  • FrequencyList

    number[] optional

    Contains all operating frequency recently seen for the WiFi network.

  • HexSSID

    string optional

    HEX-encoded copy of the network SSID.

  • HiddenSSID

    boolean optional

    Whether the network SSID will be broadcast.

  • Passphrase

    string optional

    Chrome 66+

    The passphrase for WEP/WPA/WPA2 connections. This property can only be set - properties returned by getProperties will not contain this value.

  • RoamThreshold

    number optional

    Deprecated, ignored.

  • SSID

    string optional

    The network SSID.

  • Security

    string optional

    The network security type.

  • SignalStrength

    number optional

    The network signal strength.

WiFiStateProperties

Properties

WiMAXProperties

Properties

  • AutoConnect

    boolean optional

    Whether the network should be connected automatically.

  • EAP

    EAPProperties optional

    The network EAP properties.

Methods

createNetwork()

chrome.networking.onc.createNetwork(
  shared: boolean,
  properties: NetworkConfigProperties,
  callback?: function,
)

Creates a new network configuration from properties. If a matching configured network already exists, this will fail. Otherwise returns the GUID of the new network.

Parameters

  • shared

    boolean

    If true, share this network configuration with other users.

    This option is exposed only to Chrome's Web UI.* When called by apps, false is the only allowed value.

  • The properties to configure the new network with.

  • callback

    function optional

    The callback parameter looks like:

    (result: string)=>void

    • result

      string

disableNetworkType()

chrome.networking.onc.disableNetworkType(
  networkType: NetworkType,
)

Disables any devices matching the specified network type. See note for enableNetworkType.

Parameters

  • networkType

    The type of network to disable.

enableNetworkType()

chrome.networking.onc.enableNetworkType(
  networkType: NetworkType,
)

Enables any devices matching the specified network type. Note, the type might represent multiple network types (e.g. 'Wireless').

Parameters

  • networkType

    The type of network to enable.

forgetNetwork()

chrome.networking.onc.forgetNetwork(
  networkGuid: string,
  callback?: function,
)

Forgets a network configuration by clearing any configured properties for the network with GUID networkGuid. This may also include any other networks with matching identifiers (e.g. WiFi SSID and Security). If no such configuration exists, an error will be set and the operation will fail.

In kiosk sessions, this method will not be able to forget shared network configurations.

Parameters

  • networkGuid

    string

    The GUID of the network to forget.

  • callback

    function optional

    The callback parameter looks like:

    ()=>void

getCaptivePortalStatus()

chrome.networking.onc.getCaptivePortalStatus(
  networkGuid: string,
  callback: function,
)

Returns captive portal status for the network matching 'networkGuid'.

Parameters

  • networkGuid

    string

    The GUID of the network to get captive portal status for.

  • callback

    function

    The callback parameter looks like:

    (result: CaptivePortalStatus)=>void

getDeviceStates()

chrome.networking.onc.getDeviceStates(
  callback: function,
)

Returns states of available networking devices.

Parameters

getGlobalPolicy()

chrome.networking.onc.getGlobalPolicy(
  callback: function,
)

Gets the global policy properties. These properties are not expected to change during a session.

Parameters

getManagedProperties()

chrome.networking.onc.getManagedProperties(
  networkGuid: string,
  callback: function,
)

Gets the merged properties of the network with id networkGuid from the sources: User settings, shared settings, user policy, device policy and the currently active settings.

Parameters

  • networkGuid

    string

    The GUID of the network to get properties for.

  • callback

    function

    The callback parameter looks like:

    (result: ManagedProperties)=>void

getNetworks()

chrome.networking.onc.getNetworks(
  filter: NetworkFilter,
  callback: function,
)

Returns a list of network objects with the same properties provided by getState. A filter is provided to specify the type of networks returned and to limit the number of networks. Networks are ordered by the system based on their priority, with connected or connecting networks listed first.

Parameters

getProperties()

chrome.networking.onc.getProperties(
  networkGuid: string,
  callback: function,
)

Gets all the properties of the network with id networkGuid. Includes all properties of the network (read-only and read/write values).

Parameters

  • networkGuid

    string

    The GUID of the network to get properties for.

  • callback

    function

    The callback parameter looks like:

    (result: NetworkProperties)=>void

getState()

chrome.networking.onc.getState(
  networkGuid: string,
  callback: function,
)

Gets the cached read-only properties of the network with id networkGuid. This is meant to be a higher performance function than getProperties, which requires a round trip to query the networking subsystem. The following properties are returned for all networks: GUID, Type, Name, WiFi.Security. Additional properties are provided for visible networks: ConnectionState, ErrorState, WiFi.SignalStrength, Cellular.NetworkTechnology, Cellular.ActivationState, Cellular.RoamingState.

Parameters

requestNetworkScan()

chrome.networking.onc.requestNetworkScan(
  networkType?: NetworkType,
)

Requests that the networking subsystem scan for new networks and update the list returned by getVisibleNetworks. This is only a request: the network subsystem can choose to ignore it. If the list is updated, then the onNetworkListChanged event will be fired.

Parameters

  • networkType

    NetworkType optional

    Chrome 63+

    If provided, requests a scan specific to the type. For Cellular a mobile network scan will be requested if supported.

setProperties()

chrome.networking.onc.setProperties(
  networkGuid: string,
  properties: NetworkConfigProperties,
  callback?: function,
)

Sets the properties of the network with id networkGuid. This is only valid for configured networks (Source != None). Unconfigured visible networks should use createNetwork instead. In kiosk sessions, calling this method on a shared network will fail.

Parameters

  • networkGuid

    string

    The GUID of the network to set properties for.

  • The properties to set.

  • callback

    function optional

    The callback parameter looks like:

    ()=>void

startConnect()

chrome.networking.onc.startConnect(
  networkGuid: string,
  callback?: function,
)

Starts a connection to the network with networkGuid.

Parameters

  • networkGuid

    string

    The GUID of the network to connect to.

  • callback

    function optional

    The callback parameter looks like:

    ()=>void

startDisconnect()

chrome.networking.onc.startDisconnect(
  networkGuid: string,
  callback?: function,
)

Starts a disconnect from the network with networkGuid.

Parameters

  • networkGuid

    string

    The GUID of the network to disconnect from.

  • callback

    function optional

    The callback parameter looks like:

    ()=>void

Events

onDeviceStateListChanged

chrome.networking.onc.onDeviceStateListChanged.addListener(
  callback: function,
)

Fired when the list of devices has changed or any device state properties have changed.

Parameters

  • callback

    function

    The callback parameter looks like:

    ()=>void

onNetworkListChanged

chrome.networking.onc.onNetworkListChanged.addListener(
  callback: function,
)

Fired when the list of networks has changed. Sends a complete list of GUIDs for all the current networks.

Parameters

  • callback

    function

    The callback parameter looks like:

    (changes: string[])=>void

    • changes

      string[]

onNetworksChanged

chrome.networking.onc.onNetworksChanged.addListener(
  callback: function,
)

Fired when the properties change on any of the networks. Sends a list of GUIDs for networks whose properties have changed.

Parameters

  • callback

    function

    The callback parameter looks like:

    (changes: string[])=>void

    • changes

      string[]

onPortalDetectionCompleted

chrome.networking.onc.onPortalDetectionCompleted.addListener(
  callback: function,
)

Fired when a portal detection for a network completes. Sends the GUID of the network and the corresponding captive portal status.

Parameters