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.

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.
  • AutoConnect If enabled, this network will be considered as a potential candidate to connect to during network selection.
  • 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 unavailable in the Open Network Configuration (ONC) specification but is provided in AMAPI and can be specified while configuring Wi-Fi 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. For Android 12 and newer, 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. Prior to 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"
      }
   ]
}