Configure networks

You can use policy to configure Wi-Fi networks on a device. The Android Management API uses Open Network Configuration, a standard JSON-based format which was originally developed as part of the Chromium project. Refer to the specification for full details on Open Network Configuration.

To include an Open Network Configuration in a policy, set the openNetworkConfiguration field on a Policy resource.

For fully managed devices, you can optionally prevent a user from manually configuring Wi-Fi settings on their device by setting wifiConfigDisabled to true in the Policy resource.

Supported features

The Android Management API only supports a subset of the Open Network Configuration specification.

  • Top-level object:
    • Type must be omitted or set to UnencryptedConfiguration. There is no need to encrypt the network configuration within a policy because the entire policy is encrypted within the Android Management API service. Additionally, there is a second layer of encryption for sensitive information such as passphrases and private keys.
  • NetworkConfiguration objects:
    • GUID, Name, Type, and WiFi are supported fields, and are all required.
    • ProxySettings is an optional field. If this is used, only Manual and PAC (Proxy Auto-Configuration) are supported.
    • Type must be set to WiFi. Other types of networks are not supported.
  • WiFi objects:
    • SSID and HexSSID are supported and at least one of them must be present.
      • If both HexSSID and SSID are set, the values must be consistent.
    • HiddenSSID is supported.
    • AllowGatewayARPPolling is not supported.
    • SignalStrength is not supported.
    • Security is required and following values are supported: - None - WEP-PSK - WPA-PSK - WPA-EAP - WEP-8021X - WPA3-Enterprise_192
    • For WEP-PSK passphrases, only 40-bit (10-digit) or 104-bit (26-digit) passphrases are supported.
    • The specification states that WEP-PSK passphrases must start with the prefix 0x. However, for consistency with the Android Framework, this prefix is not required.
    • To set MAC randomization mode, use the property MACAddressRandomizationMode set with the values Hardware or Automatic. This property is currently unavailable in the Open Network Configuration (ONC) specification but is provided in AMAPI and can be specified while configuring WiFi networks. This applies only to Android 13+ on all management modes.
      • Hardware uses the factory MAC address when connecting to the network.
      • Automatic lets the Wi-Fi framework automatically decide the MAC randomization strategy. This can either be persistent or non-persistent randomly generated MAC addresses which are used while connecting to the network.
  • EAP objects:
    • ClientCertPattern is not supported.
    • SaveCredentials is not supported as credentials are always saved.
    • UseSystemCAs is not supported.
    • ServerCARef is supported.
    • ServerCARefs is supported.
    • DomainSuffixMatch is supported. Enterprise wireless configurations without this field (or with an empty list as value) are considered insecure and rejected by the platform. Values should be valid domain names (e.g. "example.com", "subdomain.example.com").
    • The following values are supported for ClientCertType: Ref, KeyPairAlias
    • The following values are supported for Inner: MSCHAPv2, PAP
    • The following values are supported for Outer: EAP-AKA, EAP-TLS, EAP-TTLS, EAP-SIM, PEAP
  • Certificate objects:
    • Remove is not supported. Omit the certificate in the configuration instead.
    • TrustBits is not supported.

Examples

Multiple Wi-Fi networks

This example policy fragment shows three Wi-Fi networks configured with different security schemes. The Open Network Configuration JSON is nested within the openNetworkConfiguration field of the Policy JSON.

"openNetworkConfiguration": {
  "NetworkConfigurations": [
    {
      "GUID": "a",
      "Name": "Example A",
      "Type": "WiFi",
      "WiFi": {
        "SSID": "Example A",
        "Security": "None",
        "AutoConnect": true
      }
    },
    {
      "GUID": "b",
      "Name": "Example B",
      "Type": "WiFi",
      "WiFi": {
        "SSID": "Example B",
        "Security": "WEP-PSK",
        "Passphrase": "1234567890"
      }
    },
    {
      "GUID": "c",
      "Name": "Example C",
      "Type": "WiFi",
      "WiFi": {
        "SSID": "Example C",
        "Security": "WPA-PSK",
        "Passphrase": "baseball"
      }
    },
    {
      "GUID": "networkA",
      "Name": "networkA",
      "Type": "WiFi",
      "WiFi": {
        "SSID": "networkA",
        "Security": "WPA-PSK",
        "Passphrase": "pwd1234567",
        "MACAddressRandomizationMode": "Hardware"
      }
    }
  ]
}

EAP authentication

This example policy fragment shows a wireless network configured with EAP-TLS authentication. In addition to the NetworkConfigurations object, the example includes two Certificates objects for the client and server certificates.

"openNetworkConfiguration": {
   "Type": "UnencryptedConfiguration",
   "NetworkConfigurations": [
      {
         "GUID": "a",
         "Name": "Example A",
         "Type": "WiFi",
         "WiFi": {
            "SSID": "Example A",
            "EAP": {
               "Outer": "EAP-TLS",
               "Identity": "example",
               "DomainSuffixMatch": [
                  "example.com",
                  "example.org"
               ],
               "ServerCARefs": ["abc123"],
               "ClientCertType": "Ref",
               "ClientCertRef": "xyz456"
            },
            "Security": "WPA-EAP"
         }
      }
   ],
   "Certificates": [
      {
         "GUID": "abc123",
         "Type": "Server",
         "X509": "TWFuIGlzIGRpc3Rpbmd1a"
      },
      {
         "GUID": "xyz456",
         "Type": "Client",
         "PKCS12": "6PQIEQYJKoZbdDu8gwggRlqCCAPEbAAcGClgvcNAQc"
      }
   ]
}

The ClientCertType field can also be set to KeyPairAlias, and the ClientCertKeyPairAlias field can be used to specify the alias of an installed (see DevicePolicyManager.installKeyPair ) or generated (see DevicePolicyManager.generateKeyPair ) KeyChain key pair that is used for Wi-Fi authentication. On Android 12 and above, the KeyChain key pair having the alias specified with ClientCertKeyPairAlias is granted for authentication to Wi-Fi networks and is used for authentication to the corresponding Wi-Fi network. Below Android 12, a nonComplianceDetail with API_LEVEL reason is reported. A nonComplianceDetail with INVALID_VALUE reason and ONC_WIFI_KEY_PAIR_ALIAS_NOT_CORRESPONDING_TO_EXISTING_KEY specific reason is reported if specified key pair alias does not correspond to an existing key. Following is an example policy:

"openNetworkConfiguration": {
   "Type": "UnencryptedConfiguration",
   "NetworkConfigurations": [
      {
         "GUID": "a",
         "Name": "Example A",
         "Type": "WiFi",
         "WiFi": {
            "SSID": "Example A",
            "EAP": {
               "Outer": "EAP-TLS",
               "Identity": "example",
               "DomainSuffixMatch": [
                  "example.com",
                  "example.org"
               ],
               "ServerCARefs": ["abc123"],
               "ClientCertType": "KeyPairAlias",
               "ClientCertKeyPairAlias": "key-alias"
            },
            "Security": "WPA-EAP"
         }
      }
   ],
   "Certificates": [
      {
         "GUID": "abc123",
         "Type": "Server",
         "X509": "TWFuIGlzIGRpc3Rpbmd1a"
      }
   ]
}

The Security field can also be WPA3-Enterprise_192 which is a WPA-EAP network configured with WPA3 192-bit mode.

"openNetworkConfiguration": {
   "Type": "UnencryptedConfiguration",
   "NetworkConfigurations": [
      {
         "Type": "WiFi",
         "Name": "Example A",
         "GUID": "A",
         "WiFi": {
            "SSID": "Example A",
            "EAP": {
               "Outer": "EAP-TLS",
               "Identity": "example",
               "ServerCARefs": ["abc123"],
               "ClientCertType": "Ref",
               "ClientCertRef": "xyz456",
               "DomainSuffixMatch": ["example.com"]
            },
            "Security": "WPA3-Enterprise_192",
            "AutoConnect": true
         }
      }
   ],
   "Certificates": [
      {
         "GUID": "abc123",
         "Type": "Server",
         "X509": "TWFuIGlzIGRpc3Rpbmd1a"
      },
      {
         "GUID": "xyz456",
         "Type": "Client",
         "PKCS12": "6PQIEQYJKoZbdDu8gwggRlqCCAPEbAAcGClgvcNAQc"
      }
   ]
}