Integrate your website as a search provider in Microsoft Edge

Windows 10’s new web browser still use OpenSearch auto-discovery to let users customize their preferred search-engine, but adds new and stricter technical requirements.

The user interface for changing the default search-engine in Edge is very well hidden from users. Websites wanting to offer their visitors the choice of setting them as their default search-engine only need to configure OpenSearch to be listed as an available option.

Microsoft Edge has a search provider discovery system that works very similarly to Safari’s Quick Website Search. Internet Explorer started utilizing OpenSearch auto-discovery all the way back in version 7.

In Internet Explorer, OpenSearch was used to extend the browsers’ search box by allowing it to be used to search the current site or add it as a search provider. Firefox 39 still uses OpenSearch in this way. Since there isn’t a separate search field in Edge anymore, auto-discovered search-engines are now added to a list of available search providers in App Settings: Advanced settings: Search in the address bar with: Add new.

To appear in this list, your site must enable OpenSearch auto-discovery to describe how search clients can direct queries at your site’s search system:

Add a OpenSearch auto-discovery link in your <head> element:

<head> …
  <link rel="search"
    type="application/opensearchdescription+xml"
    href="https://example.com/opensearch.xml"
    title="Example website" />
</head>

Add an OpenSearch Description (OSD) file to the root of your web server and save it as “opensearch.xml” (any name will do as long as it matches the auto-discovery link)

<?xml version="1.0"?>
<!-- SPDX-License-Identifier: CC0-1.0 -->
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
  <ShortName>Example website</ShortName>
  <Description>Search Example website’s extensive archive of articles on Example topics.</Description>
  <Image width="16"
    height="16"
    type="image/x-icon">https://example.com/favicon.ico</Image>
  <Url method="get"
    rel="results"
    type="text/html"
    template="https://example.com/search?query={searchTerms}&amp;client=osd" />
  <Url rel="self"
    type="application/opensearchdescription+xml"
    template="https://example.com/opensearch.xml" />
  <Language>en</Language>
  <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

Reference my previous article on using the OpenSearch Description file as it will have more details if you need help adopting the above example to your website.

Finally you must also make sure that your site meets the extra requirements outlined below.

Drive-by installation protection

Like Safari, Edge has some extra measures in place to protect users from advertisers and random pages maliciously injecting themselves as search providers. The requirements for being included in the user’s auto-discovered search providers are as follows:

User must have visited the site using a path-less request, e.g. to https://www.example.com/

Redirects from the path-less extension to another path, like /index.html or something else is accepted, but only one redirect away from the path-less request is allowed even though the browser will follow more redirects.

The OpenSearch description link element must be included in the main frame of the site (no framesets, iframes, objects, or fragments)
Both the visited page and OSD file must be served over HTTPS

The last criteria differs from Safari’s criterion. Edge seem to be pushing for using encryption with every user search, but the referenced OSD can contain an unencrypted HTTP Url template — meaning every actual search performed by the user would still be unencrypted.

There’s no method for users to manually add a new search provider besides the OpenSearch auto-discovery method. Internet Explorer’s window.external.AddSearchProvider(osd) API that allowed users to add new search providers by clicking on a link hasn’t been removed from Microsoft Edge, but the API no longer does anything.

The retrieval of the OpenSearch Description file only happens at the point where the user chooses to add it to their list of search providers. The below shows the special User-Agent used to retrieve the OSD files:

Mozilla/5.0 (Windows NT 10.0; Win64; x64; ServiceUI 4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.10240

Note the “ServiceUI 4” component above. Here is the normal User-Agent of Edge for comparison:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.10240