WiFi CSP

The WiFi configuration service provider provides the functionality to add or delete Wi-Fi networks on a Windows device. The configuration service provider accepts SyncML input and converts it to a network profile that is installed on the device. This profile enables the device to connect to the Wi-Fi network when it's in range.

Programming considerations:

• If the authentication method needs a certificate (for example, client certificates for EAP-TLS), you must configure it through the CertificateStore configuration service provider. The WiFi configuration service provider doesn't provide that functionality; instead, the Wi-Fi profile can specify characteristics of the certificate to be used for choosing the right certificate for that network. The server must successfully enroll the certificate first before deploying the Wi-Fi network configuration. For example, for an EAP-TLS profile, the server must successfully configure and enroll the required client certificate before deploying the Wi-Fi profile. Self-signed certificate works for EAP-TLS/PEAP-MSCHAPv2, but it isn't supported in EAP-TLS.
• For WEP, WPA, and WPA2-based networks, include the passkey in the network configuration in plaintext. The passkey is encrypted automatically when it's stored on the device.
• The SSID part of the LocURI node must be a valid URI based on RFC 2396. This condition requires that all nonexcluded ASCII characters must be escaped using a %-character, including replacing the space character (' ') with '%20'. Characters (including Unicode) without the necessary escaping aren't supported.
• For the WiFi CSP, you can't use the Replace command unless the node already exists.
• Using Proxy, ProxyPacUrl or ProxyWPAD in Windows client editions (Home, Pro, Enterprise, and Education) may fail or have no effect. Use NetworkProxy CSP instead.

The following list shows the WiFi configuration service provider nodes:

• ./Device/Vendor/MSFT/WiFi
  • Profile
    • {SSID}
      • ProfileSource
      • Proxy
      • ProxyPacUrl
      • ProxyWPAD
      • WiFiCost
      • WlanXml
• ./User/Vendor/MSFT/WiFi
  • Profile
    • {SSID}
      • ProfileSource
      • Proxy
      • ProxyPacUrl
      • ProxyWPAD
      • WiFiCost
      • WlanXml

Device/Profile

./Device/Vendor/MSFT/WiFi/Profile

Identifies the Wi-Fi network configuration. Each Wi-Fi network configuration is represented by a profile object. This network profile includes all the information required for the device to connect to that network - for example, the SSID, authentication and encryption methods and passphrase in case of WEP or WPA2 networks.

Description framework properties:

Device/Profile/{SSID}

./Device/Vendor/MSFT/WiFi/Profile/{SSID}

The Profile name of the Wi-Fi network. This is added when WlanXml node is added and deleted when WlanXml is deleted.

Specifies the Profile name of the Wi-Fi network (32 bytes maximum) to create, configure, query, or delete. The name is case sensitive and can be represented in ASCII. In the URI, it must be %-escaped, but the non-%-escaped value is used inside the system.

The Profile name can be the same or different from the SSID of the actual network being broadcast (which is under <WLANProfile> <SSIDConfig> <SSID> <name>). For example, the broadcast SSID might be "CC_Corp_7" but the Profile name might be "ContosoWiFi".

Description framework properties:

In the following example, the 'ContosoWiFi' Profile is added, targeting the 'CC_Corp_7' SSID. The rest of the profile is omitted for brevity - for complete examples, see Add a network.

<Atomic>
  <CmdID>300</CmdID>
  <Add>
    <CmdID>301</CmdID>
    <Item>
      <Target>
        <LocURI>./Vendor/MSFT/WiFi/Profile/ContosoWiFi/WlanXml</LocURI>
      </Target>
      <Meta>
        <Format xmlns="syncml:metinf">chr</Format>
      </Meta>
      <Data><![CDATA[<?xml version="1.0"?><WLANProfile xmlns="http://www.microsoft.com/networking/WLAN/profile/v1"><name>ContosoWiFi</name><SSIDConfig><SSID><name>CC_Corp_7</name></SSID></SSIDConfig>{...}</WLANProfile>]]></Data>
    </Item>
  </Add>
</Atomic>

Device/Profile/{SSID}/ProfileSource

./Device/Vendor/MSFT/WiFi/Profile/{SSID}/ProfileSource

Allows for defining which administrative entity is setting this Wi-Fi profile. This can currently be set to either 0=Enterprise or 1=Mobile Operator.

Description framework properties:

Allowed values:

Device/Profile/{SSID}/Proxy

./Device/Vendor/MSFT/WiFi/Profile/{SSID}/Proxy

Optional node. The format is url:port. Configuration of the network proxy (if any).

Description framework properties:

Device/Profile/{SSID}/ProxyPacUrl

./Device/Vendor/MSFT/WiFi/Profile/{SSID}/ProxyPacUrl

Optional node. URL to the PAC file ___location.

Description framework properties:

Device/Profile/{SSID}/ProxyWPAD

./Device/Vendor/MSFT/WiFi/Profile/{SSID}/ProxyWPAD

Optional node. The presence of the field enables WPAD for proxy lookup.

Description framework properties:

Allowed values:

Device/Profile/{SSID}/WiFiCost

./Device/Vendor/MSFT/WiFi/Profile/{SSID}/WiFiCost

Optional node. If the policy is active selecting one of the values from the following list will set the cost of WLAN connection for the Wi-Fi profile. (1:Unrestricted - unlimited connection, 2: Fixed - capacity constraints up to a certain data limit, 3: Variable - costed on per byte basic) Default behavior: Unrestricted.

Description framework properties:

Allowed values:

Device/Profile/{SSID}/WlanXml

./Device/Vendor/MSFT/WiFi/Profile/{SSID}/WlanXml

XML describing the network configuration and follows Windows WLAN_profile schema.

Link to schema: https://msdn.microsoft.com/library/windows/desktop/ms707341(v=vs.85).aspx

The profile XML must be escaped, as shown in the following examples.

If it exists in the blob, the keyType and protected elements must come before keyMaterial, as shown in the example in WPA2-Personal Profile Sample.

Description framework properties:

See Add a network for examples.

User/Profile

./User/Vendor/MSFT/WiFi/Profile

Identifies the Wi-Fi network configuration. Each Wi-Fi network configuration is represented by a profile object. This network profile includes all the information required for the device to connect to that network - for example, the SSID, authentication and encryption methods and passphrase in case of WEP or WPA2 networks.

Description framework properties:

User/Profile/{SSID}

./User/Vendor/MSFT/WiFi/Profile/{SSID}

The Profile name of the Wi-Fi network. This is added when WlanXml node is added and deleted when WlanXml is deleted.

For more information, see Device/Profile/{SSID}.

Description framework properties:

User/Profile/{SSID}/ProfileSource

./User/Vendor/MSFT/WiFi/Profile/{SSID}/ProfileSource

Allows for defining which administrative entity is setting this Wi-Fi profile. This can currently be set to either 0=Enterprise or 1=Mobile Operator.

Description framework properties:

Allowed values:

User/Profile/{SSID}/Proxy

./User/Vendor/MSFT/WiFi/Profile/{SSID}/Proxy

Optional node. The format is url:port. Configuration of the network proxy (if any).

Description framework properties:

User/Profile/{SSID}/ProxyPacUrl

./User/Vendor/MSFT/WiFi/Profile/{SSID}/ProxyPacUrl

Optional node. URL to the PAC file ___location.

Description framework properties:

User/Profile/{SSID}/ProxyWPAD

./User/Vendor/MSFT/WiFi/Profile/{SSID}/ProxyWPAD

Optional node. The presence of the field enables WPAD for proxy lookup.

Description framework properties:

Allowed values:

User/Profile/{SSID}/WiFiCost

./User/Vendor/MSFT/WiFi/Profile/{SSID}/WiFiCost

Optional node. If the policy is active selecting one of the values from the following list will set the cost of WLAN connection for the Wi-Fi profile. (1:Unrestricted - unlimited connection, 2: Fixed - capacity constraints up to a certain data limit, 3: Variable - costed on per byte basic) Default behavior: Unrestricted.

Description framework properties:

Allowed values:

User/Profile/{SSID}/WlanXml

./User/Vendor/MSFT/WiFi/Profile/{SSID}/WlanXml

XML describing the network configuration and follows Windows WLAN_profile schema.

Link to schema: https://msdn.microsoft.com/library/windows/desktop/ms707341(v=vs.85).aspx

For more information, see Device/Profile/{SSID}/WlanXml.

Description framework properties:

Examples

These XML examples show how to perform various tasks using OMA DM.

Add a network

The following example shows how to add a WPA2-Enterprise network with SSID and profile name MyNetwork that authenticates with PEAP-MSCHAPv2. This example is based on the sample profile at WPA2-Enterprise with PEAP-MSCHAPv2 profile sample.

<SyncML xmlns="SYNCML:SYNCML1.2">
  <SyncBody>
    <Atomic>
      <CmdID>301</CmdID>
      <Add>
        <CmdID>302</CmdID>
        <Item>
          <Target>
            <LocURI>./Vendor/MSFT/WiFi/Profile/MyNetwork/WlanXml</LocURI>
          </Target>
          <Meta>
            <Format xmlns="syncml:metinf">chr</Format>
          </Meta>
          <Data><![CDATA[<?xml version="1.0"?><WLANProfile xmlns="http://www.microsoft.com/networking/WLAN/profile/v1"><name>MyNetwork</name><SSIDConfig><SSID><hex>4d794e6574776f726b</hex><name>MyNetwork</name></SSID><nonBroadcast>false</nonBroadcast></SSIDConfig><connectionType>ESS</connectionType><connectionMode>manual</connectionMode><MSM><security><authEncryption><authentication>WPA2</authentication><encryption>AES</encryption><useOneX>true</useOneX></authEncryption><OneX xmlns="http://www.microsoft.com/networking/OneX/v1"><authMode>user</authMode><EAPConfig><EapHostConfig xmlns="http://www.microsoft.com/provisioning/EapHostConfig"><EapMethod><Type xmlns="http://www.microsoft.com/provisioning/EapCommon">25</Type><VendorId xmlns="http://www.microsoft.com/provisioning/EapCommon">0</VendorId><VendorType xmlns="http://www.microsoft.com/provisioning/EapCommon">0</VendorType><AuthorId xmlns="http://www.microsoft.com/provisioning/EapCommon">0</AuthorId></EapMethod><Config xmlns="http://www.microsoft.com/provisioning/EapHostConfig"><Eap xmlns="http://www.microsoft.com/provisioning/BaseEapConnectionPropertiesV1"><Type>25</Type><EapType xmlns="http://www.microsoft.com/provisioning/MsPeapConnectionPropertiesV1"><ServerValidation><DisableUserPromptForServerValidation>true</DisableUserPromptForServerValidation><ServerNames></ServerNames></ServerValidation><FastReconnect>true</FastReconnect><InnerEapOptional>false</InnerEapOptional><Eap xmlns="http://www.microsoft.com/provisioning/BaseEapConnectionPropertiesV1"><Type>26</Type><EapType xmlns="http://www.microsoft.com/provisioning/MsChapV2ConnectionPropertiesV1"><UseWinLogonCredentials>false</UseWinLogonCredentials></EapType></Eap><EnableQuarantineChecks>false</EnableQuarantineChecks><RequireCryptoBinding>false</RequireCryptoBinding><PeapExtensions><PerformServerValidation xmlns="http://www.microsoft.com/provisioning/MsPeapConnectionPropertiesV2">false</PerformServerValidation><AcceptServerName xmlns="http://www.microsoft.com/provisioning/MsPeapConnectionPropertiesV2">false</AcceptServerName></PeapExtensions></EapType></Eap></Config></EapHostConfig></EAPConfig></OneX></security></MSM></WLANProfile>]]></Data>
        </Item>
      </Add>
    </Atomic>
    <Final/>
  </SyncBody>
</SyncML>

The following example shows how to add a WPA3-Enterprise network with profile name My Network and SSID MySSID that authenticates with EAP-TLS. This example is based on the sample profile at WPA2-Enterprise with TLS profile sample.

<Atomic>
  <CmdID>300</CmdID>
  <Add>
    <CmdID>301</CmdID>
    <Item>
      <Target>
        <LocURI>./Vendor/MSFT/WiFi/Profile/My%20Network/WlanXml</LocURI>
      </Target>
      <Meta>
        <Format xmlns="syncml:metinf">chr</Format>
      </Meta>
      <Data><![CDATA[<?xml version="1.0"?><WLANProfile xmlns="http://www.microsoft.com/networking/WLAN/profile/v1"><name>My Network</name><SSIDConfig><SSID><name>MySSID</name></SSID></SSIDConfig><connectionType>ESS</connectionType><connectionMode>auto</connectionMode><MSM><security><authEncryption><authentication>WPA3ENT</authentication><encryption>AES</encryption><useOneX>true</useOneX></authEncryption><PMKCacheMode>enabled</PMKCacheMode><PMKCacheTTL>720</PMKCacheTTL><PMKCacheSize>128</PMKCacheSize><preAuthMode>disabled</preAuthMode><OneX xmlns="http://www.microsoft.com/networking/OneX/v1"><authMode>machine</authMode><EAPConfig><EapHostConfig xmlns="http://www.microsoft.com/provisioning/EapHostConfig"><EapMethod><Type xmlns="http://www.microsoft.com/provisioning/EapCommon">13</Type><VendorId xmlns="http://www.microsoft.com/provisioning/EapCommon">0</VendorId><VendorType xmlns="http://www.microsoft.com/provisioning/EapCommon">0</VendorType><AuthorId xmlns="http://www.microsoft.com/provisioning/EapCommon">0</AuthorId></EapMethod><Config xmlns="http://www.microsoft.com/provisioning/EapHostConfig"><Eap xmlns="http://www.microsoft.com/provisioning/BaseEapConnectionPropertiesV1"><Type>13</Type><EapType xmlns="http://www.microsoft.com/provisioning/EapTlsConnectionPropertiesV1"><CredentialsSource><CertificateStore><SimpleCertSelection>true</SimpleCertSelection></CertificateStore></CredentialsSource><ServerValidation><DisableUserPromptForServerValidation>true</DisableUserPromptForServerValidation><ServerNames></ServerNames><TrustedRootCA>00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff 00 11 22 33</TrustedRootCA></ServerValidation><DifferentUsername>false</DifferentUsername><PerformServerValidation xmlns="http://www.microsoft.com/provisioning/EapTlsConnectionPropertiesV2">true</PerformServerValidation><AcceptServerName xmlns="http://www.microsoft.com/provisioning/EapTlsConnectionPropertiesV2">false</AcceptServerName><TLSExtensions xmlns="http://www.microsoft.com/provisioning/EapTlsConnectionPropertiesV2"><FilteringInfo xmlns="http://www.microsoft.com/provisioning/EapTlsConnectionPropertiesV3"><AllPurposeEnabled>false</AllPurposeEnabled><CAHashList Enabled="true"><IssuerHash>00112233445566778899aabbccddeeff00112233</IssuerHash></CAHashList><EKUMapping><EKUMap><EKUName>Client Authentication</EKUName><EKUOID>1.3.6.1.5.5.7.3.2</EKUOID></EKUMap></EKUMapping><ClientAuthEKUList Enabled="true"><EKUMapInList><EKUName>Client Authentication</EKUName></EKUMapInList></ClientAuthEKUList></FilteringInfo></TLSExtensions></EapType></Eap></Config></EapHostConfig></EAPConfig></OneX></security></MSM></WLANProfile>]]></Data>
    </Item>
  </Add>
</Atomic>

The following example shows how to add a WPA3-Personal (transition mode) network with profile name and SSID MyNetwork that includes the passphrase TestPassword1!. This example is based on the sample profile at WPA3-Personal with transition mode profile sample.

<Atomic>
  <CmdID>300</CmdID>
  <Add>
    <CmdID>301</CmdID>
    <Item>
      <Target>
        <LocURI>./Vendor/MSFT/WiFi/Profile/MyNetwork/WlanXml</LocURI>
      </Target>
      <Meta>
        <Format xmlns="syncml:metinf">chr</Format>
      </Meta>
      <Data><![CDATA[<?xml version="1.0"?><WLANProfile xmlns="http://www.microsoft.com/networking/WLAN/profile/v1"><name>MyNetwork</name><SSIDConfig><SSID><name>MyNetwork</name></SSID></SSIDConfig><connectionType>ESS</connectionType><connectionMode>auto</connectionMode><MSM><security><authEncryption><authentication>WPA3SAE</authentication><encryption>AES</encryption><useOneX>false</useOneX><transitionMode xmlns="http://www.microsoft.com/networking/WLAN/profile/v4">true</transitionMode></authEncryption><sharedKey><keyType>passPhrase</keyType><protected>false</protected><keyMaterial>TestPassword1!</keyMaterial></sharedKey></security></MSM></WLANProfile>]]></Data>
    </Item>
  </Add>
</Atomic>

Query network profiles

The following example shows how to query Wi-Fi profiles installed on an MDM server.

<Get>
   <CmdID>301</CmdID>
   <Item>
      <Target>
         <LocURI>./Vendor/MSFT/WiFi/Profile</LocURI>
      </Target>
   </Item>
</Get>

The following example shows the response.

<Results>
   <CmdID>3</CmdID>
   <MsgRef>1</MsgRef>
   <CmdRef>301</CmdRef>
   <Item>
      <Source><LocURI>./Vendor/MSFT/WiFi/Profile</LocURI></Source>
      <Meta><Format xmlns="syncml:metinf">node</Format></Meta>
      <Data>TestWLAN1/TestWLAN2</Data>
   </Item>
</Results>

Remove a network

The following example shows how to remove a network with SSID MyNetwork and no proxy. Removing all network authentication types is done in this same manner.

<Atomic>
  <CmdID>300</CmdID>
  <Delete>
    <CmdID>301</CmdID>
    <Item>
      <Target>
        <LocURI>./Vendor/MSFT/WiFi/Profile/MyNetwork/WlanXml</LocURI>
      </Target>
    </Item>
  </Delete>
</Atomic>

Related articles

• Wireless profile samples
• Configuration service provider reference
• Extensible Authentication Protocol (EAP) for network access
• Configure EAP profiles and settings in Windows