WLAN XML Profiles

What a WLAN XML profile is

A WLAN XML profile is a document rooted at <WLANProfile> in the namespace http://www.microsoft.com/networking/WLAN/profile/v1. It is consumed by the WLAN AutoConfig service (Wlansvc) and is the only supported way to describe a wireless network to Windows programmatically. The same schema is used by netsh wlan add profile, by WlanSetProfile, and by wclWiFiProfilesManager.SetProfile.

A profile answers four questions:

• Which network? — the SSID (named or hex-encoded) and whether it is an infrastructure (ESS) or ad-hoc (IBSS) network.
• How should Windows connect? — automatically when the network is in range, or only on explicit user request.
• How is the link secured? — open, WPA2-Personal, WPA2-Enterprise, WPA3-Enterprise, and so on, together with the cipher.
• How is the user or machine authenticated? — for enterprise networks, the 802.1X and EAP method, server validation policy, and credential source.

The profile does not contain the user's password or private key. Those are supplied separately — through the Windows logon, a certificate in the certificate store, a user prompt, or an explicit call to SetProfileEapXmlUserData. Keeping configuration and credentials separate is the key design decision behind the enterprise sections below.

Profile store and lifecycle

Windows keeps profiles in a per-interface store under %ProgramData%\Microsoft\Wlansvc\Profiles\Interfaces\{GUID}. Each profile is an XML file named after the profile. The store is managed by WLAN AutoConfig; applications do not write to it directly. Instead, they call an API that validates the XML and then persists it.

The lifecycle has three states that matter for development:

• Installed — the profile exists in the store. GetProfileList returns it, and GetProfile returns its XML.
• Active — Windows is currently using the profile for a connection. This is visible through the ACM and MSM events described in Wi-Fi events.
• Temporary — the profile exists only for the duration of a single Connect call and is never written to the store. This is the cmTemporaryProfile mode of wclWiFiClient.Connect.

Two flags control installation behavior. With Overwrite = false, SetProfile refuses to replace an existing profile with the same name and returns an error. With Overwrite = true, the existing profile is replaced in place; its position in the preferred-network list does not change. This is the correct behavior for updating an enterprise profile when the EAP configuration changes.

Minimal profile structure

The schema enforces element order. The following skeleton is the smallest valid profile for an open network, and it is the base on which every other example in this article is built:

The following table separates the required elements from the optional ones. The ordering column reflects the sequence enforced by the schema.

Two details are easy to miss. First, SSIDConfig supports up to 256 SSID entries in the v1 namespace, but the Windows UI and most enterprise deployments use one. Second, the MSM element is technically optional in the schema, but a secured network without it is not usable; for any profile that uses WPA2, WPA3, or 802.1X, treat MSM/security as required.

Building a profile step by step

Creating a profile by hand is a five-step process. The order matters because each step constrains the next.

1. Collect the network parameters. SSID, security type (WPA2-Enterprise, WPA3-Enterprise, WPA3-Enterprise 192-bit), cipher, and EAP method. If the network is enterprise, also collect the server names or root CA thumbprint and the credential source (certificate store, Windows logon, or explicit username and password).
2. Write the outer shell. Root element with the v1 namespace, name, SSIDConfig, connectionType, and connectionMode. At this point the XML is valid but does not describe security.
3. Add the security block. MSM/security/authEncryption with authentication, encryption, and useOneX. For enterprise, set useOneX to true; this is the switch that makes Windows look for the OneX element.
4. Add the EAP block. OneX/EAPConfig/EapHostConfig with the correct EapMethod type and the method-specific configuration. This is the largest part of an enterprise profile and the subject of the next sections.
5. Validate before installing. Use netsh wlan add profile as a syntax gate, then install through SetProfile and read the profile back with GetProfile to confirm that Windows accepted every element.

The XML escape rules apply throughout. An SSID or profile name containing &, <, or > must be escaped, or encoded as hex. This is a common cause of profiles that import successfully but never match the intended network.

Personal vs Enterprise profiles

The difference between a personal and an enterprise profile is concentrated in one element: authEncryption/useOneX. When it is false or absent, Windows uses a pre-shared key supplied in security/sharedKey. When it is true, Windows ignores sharedKey and starts 802.1X, which reads the OneX element.

Everything that follows in the EAP sections applies only when useOneX is true. A profile with an OneX block but useOneX=false is accepted by the schema and then silently ignored for authentication — a failure mode that is difficult to diagnose without reading the XML carefully.

EAP Enterprise in detail

Enterprise authentication is expressed as a chain of nested elements. Each level has its own namespace, and a missing namespace is the most common reason a profile is rejected with a generic "invalid profile" error.

The OneX element itself is in https://www.microsoft.com/networking/OneX/v1. Its child EAPConfig is the exception: it is in https://www.microsoft.com/provisioning/EapHostConfig, not in the OneX namespace. Inside EapHostConfig, the EapMethod and Config elements carry the EapHost namespace, and the method-specific payload declares a further namespace such as EapTlsConnectionPropertiesV1 or MsPeapConnectionPropertiesV1.

Credentials vs configuration

A WLAN profile is a configuration document, not a secret store. This distinction is enforced by the API surface: SetProfile installs the profile, and SetProfileEapXmlUserData installs the credentials that the profile references. For certificate-based methods, the credential is the certificate in the certificate store; for password-based methods, it is the username and password.

SetProfileEapXmlUserData takes the interface ID, the profile name, an AllUsers flag, and an EapHostUserCredentials XML document. The AllUsers flag is available on Windows 7 and later; when it is true, the credentials apply to every user of the profile, not just the caller. On Windows 7, setting AllUsers to true requires administrative privileges.

For PEAP-MSCHAPv2, the credential document is compact:

The RoutingIdentity is the outer identity sent in the clear during the PEAP negotiation; it can be a generic value or the user's domain-qualified identity. The Username, Password, and LogonDomain are the inner MS-CHAPv2 credentials. The password is stored by WLAN AutoConfig in a protected form; it is not written into the profile XML.

Practical scenarios

The following examples use the wclWiFiProfilesManager class from the Wi-Fi Framework. The manager is opened together with the client, as described in Opening the client.

procedure TfmMain.InstallProfile(const Id: TGUID; const FileName: string);
var
  List: TStringList;
  Xml: string;
  Flags: TwclWiFiProfileFlags;
begin
  List := TStringList.Create;
  try
    List.LoadFromFile(FileName);
    Xml := List.Text;

    Flags := [];
    ShowResult(wclWiFiProfilesManager.SetProfile(Id, Flags, Xml, True));
  finally
    List.Free;
  end;
end;

void TfmMain::InstallProfile(const TGUID Id, const String FileName)
{
  TStringList* List = new TStringList();
  __try
  {
    List->LoadFromFile(FileName);
    String Xml = List->Text;

    TwclWiFiProfileFlags Flags;
    Flags.Clear();
    ShowResult(wclWiFiProfilesManager->SetProfile(Id, Flags, Xml, true));
  }
  __finally
  {
    List->Free();
  }
}

private void InstallProfile(Guid Id, String FileName)
{
    String Xml = System.IO.File.ReadAllText(FileName);
    ShowResult(ProfilesManager.SetProfile(Id, 0, Xml, true));
}

Private Sub InstallProfile(ByVal Id As Guid, ByVal FileName As String)
    Dim Xml As String = System.IO.File.ReadAllText(FileName)
    ShowResult(ProfilesManager.SetProfile(Id, 0, Xml, True))
End Sub

void CWiFiClientDlg::InstallProfile(const GUID& Id, const CString& FileName)
{
    CStdioFile File;
    if (!File.Open(FileName, CFile::modeRead | CFile::typeText))
        return;

    CString Xml;
    CString Line;
    while (File.ReadString(Line))
        Xml += Line;

    ShowResult(wclWiFiProfilesManager.SetProfile(Id, wclWiFiProfileFlags(), tstring(Xml), true));
}

procedure TfmMain.InstallPeapCredentials(const Id: TGUID;
  const ProfileName, UserName, Password, Domain: string);
var
  CredXml: string;
begin
  CredXml :=
    '<?xml version="1.0" ?>' +
    '<EapHostUserCredentials ' +
      'xmlns="http://www.microsoft.com/provisioning/EapHostUserCredentials" ' +
      'xmlns:eapCommon="http://www.microsoft.com/provisioning/EapCommon" ' +
      'xmlns:baseEap="http://www.microsoft.com/provisioning/BaseEapMethodUserCredentials">' +
      '<EapMethod>' +
        '<eapCommon:Type>25</eapCommon:Type>' +
        '<eapCommon:AuthorId>0</eapCommon:AuthorId>' +
      '</EapMethod>' +
      '<Credentials ' +
        'xmlns:baseEap="http://www.microsoft.com/provisioning/BaseEapUserPropertiesV1" ' +
        'xmlns:MsPeap="http://www.microsoft.com/provisioning/MsPeapUserPropertiesV1" ' +
        'xmlns:MsChapV2="http://www.microsoft.com/provisioning/MsChapV2UserPropertiesV1">' +
        '<baseEap:Eap>' +
          '<baseEap:Type>25</baseEap:Type>' +
          '<MsPeap:EapType>' +
            '<baseEap:Eap>' +
              '<baseEap:Type>26</baseEap:Type>' +
              '<MsChapV2:EapType>' +
                '<MsChapV2:Username>' + UserName + '</MsChapV2:Username>' +
                '<MsChapV2:Password>' + Password + '</MsChapV2:Password>' +
                '<MsChapV2:LogonDomain>' + Domain + '</MsChapV2:LogonDomain>' +
              '</MsChapV2:EapType>' +
            '</baseEap:Eap>' +
          '</MsPeap:EapType>' +
        '</baseEap:Eap>' +
      '</Credentials>' +
    '</EapHostUserCredentials>';

  ShowResult(wclWiFiProfilesManager.SetProfileEapXmlUserData(
    Id, ProfileName, False, CredXml));
end;

void TfmMain::InstallPeapCredentials(const TGUID Id,
  const String ProfileName, const String UserName,
  const String Password, const String Domain)
{
  String CredXml =
    "<?xml version=\"1.0\" ?>"
    "<EapHostUserCredentials "
      "xmlns=\"http://www.microsoft.com/provisioning/EapHostUserCredentials\" "
      "xmlns:eapCommon=\"http://www.microsoft.com/provisioning/EapCommon\" "
      "xmlns:baseEap=\"http://www.microsoft.com/provisioning/BaseEapMethodUserCredentials\">"
      "<EapMethod>"
        "<eapCommon:Type>25</eapCommon:Type>"
        "<eapCommon:AuthorId>0</eapCommon:AuthorId>"
      "</EapMethod>"
      "<Credentials "
        "xmlns:baseEap=\"http://www.microsoft.com/provisioning/BaseEapUserPropertiesV1\" "
        "xmlns:MsPeap=\"http://www.microsoft.com/provisioning/MsPeapUserPropertiesV1\" "
        "xmlns:MsChapV2=\"http://www.microsoft.com/provisioning/MsChapV2UserPropertiesV1\">"
        "<baseEap:Eap>"
          "<baseEap:Type>25</baseEap:Type>"
          "<MsPeap:EapType>"
            "<baseEap:Eap>"
              "<baseEap:Type>26</baseEap:Type>"
              "<MsChapV2:EapType>"
                "<MsChapV2:Username>" + UserName + "</MsChapV2:Username>"
                "<MsChapV2:Password>" + Password + "</MsChapV2:Password>"
                "<MsChapV2:LogonDomain>" + Domain + "</MsChapV2:LogonDomain>"
              "</MsChapV2:EapType>"
            "</baseEap:Eap>"
          "</MsPeap:EapType>"
        "</baseEap:Eap>"
      "</Credentials>"
    "</EapHostUserCredentials>";

  ShowResult(wclWiFiProfilesManager->SetProfileEapXmlUserData(
    Id, ProfileName, false, CredXml));
}

private void InstallPeapCredentials(Guid Id, String ProfileName,
    String UserName, String Password, String Domain)
{
    String CredXml =
        "<?xml version=\"1.0\" ?>" +
        "<EapHostUserCredentials " +
          "xmlns=\"http://www.microsoft.com/provisioning/EapHostUserCredentials\" " +
          "xmlns:eapCommon=\"http://www.microsoft.com/provisioning/EapCommon\" " +
          "xmlns:baseEap=\"http://www.microsoft.com/provisioning/BaseEapMethodUserCredentials\">" +
          "<EapMethod>" +
            "<eapCommon:Type>25</eapCommon:Type>" +
            "<eapCommon:AuthorId>0</eapCommon:AuthorId>" +
          "</EapMethod>" +
          "<Credentials " +
            "xmlns:baseEap=\"http://www.microsoft.com/provisioning/BaseEapUserPropertiesV1\" " +
            "xmlns:MsPeap=\"http://www.microsoft.com/provisioning/MsPeapUserPropertiesV1\" " +
            "xmlns:MsChapV2=\"http://www.microsoft.com/provisioning/MsChapV2UserPropertiesV1\">" +
            "<baseEap:Eap>" +
              "<baseEap:Type>25</baseEap:Type>" +
              "<MsPeap:EapType>" +
                "<baseEap:Eap>" +
                  "<baseEap:Type>26</baseEap:Type>" +
                  "<MsChapV2:EapType>" +
                    "<MsChapV2:Username>" + UserName + "</MsChapV2:Username>" +
                    "<MsChapV2:Password>" + Password + "</MsChapV2:Password>" +
                    "<MsChapV2:LogonDomain>" + Domain + "</MsChapV2:LogonDomain>" +
                  "</MsChapV2:EapType>" +
                "</baseEap:Eap>" +
              "</MsPeap:EapType>" +
            "</baseEap:Eap>" +
          "</Credentials>" +
        "</EapHostUserCredentials>";

    ShowResult(ProfilesManager.SetProfileEapXmlUserData(
        Id, ProfileName, false, CredXml));
}

Private Sub InstallPeapCredentials(ByVal Id As Guid, ByVal ProfileName As String,
    ByVal UserName As String, ByVal Password As String, ByVal Domain As String)

    Dim CredXml As String =
        "<?xml version=""1.0"" ?>" &
        "<EapHostUserCredentials " &
          "xmlns=""http://www.microsoft.com/provisioning/EapHostUserCredentials"" " &
          "xmlns:eapCommon=""http://www.microsoft.com/provisioning/EapCommon"" " &
          "xmlns:baseEap=""http://www.microsoft.com/provisioning/BaseEapMethodUserCredentials"">" &
          "<EapMethod>" &
            "<eapCommon:Type>25</eapCommon:Type>" &
            "<eapCommon:AuthorId>0</eapCommon:AuthorId>" &
          "</EapMethod>" &
          "<Credentials " &
            "xmlns:baseEap=""http://www.microsoft.com/provisioning/BaseEapUserPropertiesV1"" " &
            "xmlns:MsPeap=""http://www.microsoft.com/provisioning/MsPeapUserPropertiesV1"" " &
            "xmlns:MsChapV2=""http://www.microsoft.com/provisioning/MsChapV2UserPropertiesV1"">" &
            "<baseEap:Eap>" &
              "<baseEap:Type>25</baseEap:Type>" &
              "<MsPeap:EapType>" &
                "<baseEap:Eap>" &
                  "<baseEap:Type>26</baseEap:Type>" &
                  "<MsChapV2:EapType>" &
                    "<MsChapV2:Username>" & UserName & "</MsChapV2:Username>" &
                    "<MsChapV2:Password>" & Password & "</MsChapV2:Password>" &
                    "<MsChapV2:LogonDomain>" & Domain & "</MsChapV2:LogonDomain>" &
                  "</MsChapV2:EapType>" &
                "</baseEap:Eap>" &
              "</MsPeap:EapType>" &
            "</baseEap:Eap>" &
          "</Credentials>" &
        "</EapHostUserCredentials>"

    ShowResult(ProfilesManager.SetProfileEapXmlUserData(Id, ProfileName, False, CredXml))
End Sub

void CWiFiClientDlg::InstallPeapCredentials(const GUID& Id,
    const CString& ProfileName, const CString& UserName,
    const CString& Password, const CString& Domain)
{
    CString CredXml;
    CredXml.Format(
        _T("<?xml version=\"1.0\" ?>")
        _T("<EapHostUserCredentials ")
          _T("xmlns=\"http://www.microsoft.com/provisioning/EapHostUserCredentials\" ")
          _T("xmlns:eapCommon=\"http://www.microsoft.com/provisioning/EapCommon\" ")
          _T("xmlns:baseEap=\"http://www.microsoft.com/provisioning/BaseEapMethodUserCredentials\">")
          _T("<EapMethod>")
            _T("<eapCommon:Type>25</eapCommon:Type>")
            _T("<eapCommon:AuthorId>0</eapCommon:AuthorId>")
          _T("</EapMethod>")
          _T("<Credentials ")
            _T("xmlns:baseEap=\"http://www.microsoft.com/provisioning/BaseEapUserPropertiesV1\" ")
            _T("xmlns:MsPeap=\"http://www.microsoft.com/provisioning/MsPeapUserPropertiesV1\" ")
            _T("xmlns:MsChapV2=\"http://www.microsoft.com/provisioning/MsChapV2UserPropertiesV1\">")
            _T("<baseEap:Eap>")
              _T("<baseEap:Type>25</baseEap:Type>")
              _T("<MsPeap:EapType>")
                _T("<baseEap:Eap>")
                  _T("<baseEap:Type>26</baseEap:Type>")
                  _T("<MsChapV2:EapType>")
                    _T("<MsChapV2:Username>%s</MsChapV2:Username>")
                    _T("<MsChapV2:Password>%s</MsChapV2:Password>")
                    _T("<MsChapV2:LogonDomain>%s</MsChapV2:LogonDomain>")
                  _T("</MsChapV2:EapType>")
                _T("</baseEap:Eap>")
              _T("</MsPeap:EapType>")
            _T("</baseEap:Eap>")
          _T("</Credentials>")
        _T("</EapHostUserCredentials>"),
        UserName, Password, Domain);

    ShowResult(wclWiFiProfilesManager.SetProfileEapXmlUserData(
        Id, tstring(ProfileName), false, tstring(CredXml)));
}

procedure TfmMain.ConnectTemporary(const Id: TGUID; const Xml: string);
begin
  ShowResult(wclWiFiClient.Connect(Id, cmTemporaryProfile, '', '', bssAny, [], Xml));
end;

void TfmMain::ConnectTemporary(const TGUID Id, const String Xml)
{
  ShowResult(wclWiFiClient->Connect(Id, cmTemporaryProfile, "", "", bssAny,
    TwclWiFiConnectFlags(), Xml));
}

private void ConnectTemporary(Guid Id, String Xml)
{
    ShowResult(Client.Connect(Id, wclWiFiConnectionMode.cmTemporaryProfile,
        "", "", wclWiFiBssType.bssAny, 0, Xml));
}

Private Sub ConnectTemporary(ByVal Id As Guid, ByVal Xml As String)
    ShowResult(Client.Connect(Id, wclWiFi.wclWiFiConnectionMode.cmTemporaryProfile,
        "", "", wclWiFi.wclWiFiBssType.bssAny, 0, Xml))
End Sub

void CWiFiClientDlg::ConnectTemporary(const GUID& Id, const CString& Xml)
{
    ShowResult(wclWiFiClient.Connect(Id, cmTemporaryProfile, _T(""), _T(""),
        bssAny, wclWiFiConnectFlags(), tstring(Xml)));
}

procedure TfmMain.RoundTripProfile(const Id: TGUID; const ProfileName: string);
var
  Flags: TwclWiFiProfileFlags;
  Xml: string;
begin
  Flags := [];
  if ShowResult(wclWiFiProfilesManager.GetProfile(Id, ProfileName, Flags, Xml)) then
  begin
    // Modify the XML here, for example replace the EAP method type.
    ShowResult(wclWiFiProfilesManager.SetProfile(Id, [], Xml, True));
  end;
end;

void TfmMain::RoundTripProfile(const TGUID Id, const String ProfileName)
{
  TwclWiFiProfileFlags Flags;
  Flags.Clear();
  String Xml;

  if (ShowResult(wclWiFiProfilesManager->GetProfile(Id, ProfileName, Flags, Xml)))
  {
    // Modify the XML here.
    ShowResult(wclWiFiProfilesManager->SetProfile(Id, TwclWiFiProfileFlags(), Xml, true));
  }
}

private void RoundTripProfile(Guid Id, String ProfileName)
{
    String Xml;
    wclWiFiProfileFlag Flags = 0;

    if (ShowResult(ProfilesManager.GetProfile(Id, ProfileName, ref Flags, out Xml)))
    {
        // Modify the XML here.
        ShowResult(ProfilesManager.SetProfile(Id, 0, Xml, true));
    }
}

Private Sub RoundTripProfile(ByVal Id As Guid, ByVal ProfileName As String)
    Dim Xml As String
    Dim Flags As wclWiFi.wclWiFiProfileFlag = 0

    If ShowResult(ProfilesManager.GetProfile(Id, ProfileName, Flags, Xml)) Then
        ' Modify the XML here.
        ShowResult(ProfilesManager.SetProfile(Id, 0, Xml, True))
    End If
End Sub

void CWiFiClientDlg::RoundTripProfile(const GUID& Id, const CString& ProfileName)
{
    wclWiFiProfileFlags Flags;
    tstring Xml;

    if (ShowResult(wclWiFiProfilesManager.GetProfile(Id, tstring(ProfileName), Flags, Xml)))
    {
        // Modify the XML here.
        ShowResult(wclWiFiProfilesManager.SetProfile(Id, wclWiFiProfileFlags(), Xml, true));
    }
}

Validation and debugging

Profile problems fall into two categories: schema errors and semantic errors. Schema errors are rejected at install time; semantic errors allow the profile to be installed but cause connection or authentication failures.

Schema validation

The fastest syntax gate is netsh wlan add profile. It parses the XML with the same schema that Windows uses and returns an error that identifies the offending element or attribute. If netsh accepts the file, SetProfile will accept it as well, assuming the interface exists and the overwrite flag is set correctly.

Semantic validation

Semantic errors are not visible until a connection is attempted. The most useful diagnostic is the OneX event stream from wclWiFiEvents. OnOneXAuthUpdate carries the 802.1X state, the EAP method, the identity, and — when the method fails — the EAP error details, including the root cause string and the repair hint. OnOneXAuthRestarted indicates that the authenticator restarted the exchange, which often accompanies a certificate or credential mismatch.

The ACM and MSM events provide the connection-level context. OnAcmConnectionComplete reports whether the connection succeeded or failed at the manager level; OnMsmConnected and OnMsmDisconnected report the link state; OnMsmLinkDegraded and OnMsmLinkImproved are useful when the profile connects but the link is unstable because of a cipher or band mismatch.

Common failure patterns

Enterprise profile checklist

Before installing an enterprise profile, verify each item. The list is ordered from the outer shell to the credential layer.

• The root WLANProfile declares http://www.microsoft.com/networking/WLAN/profile/v1.
• name, SSIDConfig/SSID/name (or hex), and connectionType are present.
• connectionMode is auto for unattended provisioning and manual for user-initiated connections.
• MSM/security/authEncryption contains authentication, encryption, and useOneX=true.
• The OneX element declares http://www.microsoft.com/networking/OneX/v1.
• EAPConfig/EapHostConfig declares http://www.microsoft.com/provisioning/EapHostConfig.
• EapMethod/Type is 13, 25, or 55, matching the intended method.
• For EAP-TLS, EapTlsConnectionPropertiesV1 has a CredentialsSource/CertificateStore.
• For PEAP, the inner baseEap:Type is 26 and MsChapV2 is configured.
• For TEAP, both InnerMethodConfig blocks are present and authMode is machineOrUser.
• ServerValidation has a trusted root thumbprint and, for unattended setups, DisableUserPromptForServerValidation=true.
• Credentials are available through the certificate store, Windows logon, or SetProfileEapXmlUserData.
• The profile installs through netsh and reads back through GetProfile without unexpected normalization.