Share via

Proxy Support in Microsoft Edge

This document establishes basic proxy terminology and describes Edge-specific proxy behaviors.

Contents

Proxy Server Identifiers

A proxy server is an intermediary used for network requests. A proxy server can be described using its address, along with the proxy scheme that should be used to communicate with it.

This Identifier can be written as a string using either the "PAC format" or the "URI format."

The PAC format is how one names a proxy server in Proxy autoconfig scripts. For example:

PROXY foo:2138 SOCKS5 foo:1080 DIRECT

The "URI format" instead encodes the information as a URL. For example:

foo:2138 http://foo:2138 socks5://foo:1080 direct://

The port number is optional in both formats. When omitted, a per-scheme default is used.

See the Proxy server schemes section for details on what schemes Edge supports, and how to write them in the PAC and URI formats.

Most UI surfaces in Edge (including command lines and policy) expect URI formatted proxy server identifiers. However outside of Edge, proxy servers are identified less precisely when using just an address -- the proxy scheme is assumed based on context.

In Windows' proxy settings, there are host and port fields for the "HTTP," "Secure," "FTP," and "SOCKS" proxy. Except for "SOCKS," those are all identifiers for insecure HTTP proxy servers (proxy scheme is assumed as HTTP).

Proxy Resolution

Proxying in Edge is done at the URL level.

When the browser is asked to fetch a URL, it needs to decide which IP endpoint to send the request to. This can be either a proxy server, or the target host.

This is called proxy resolution. The input to proxy resolution is a URL, and the output is an ordered list of proxy server identifiers.

What proxies to use can be described using either:

Manual proxy settings - proxy resolution is defined using a declarative set of rules. These rules are expressed as a mapping from URL scheme to proxy server identifiers, and a list of proxy bypass rules for when to go DIRECT instead of using the mapped proxy.

PAC script - proxy resolution is defined using a JavaScript program, that is invoked whenever fetching a URL to get the list of proxy server identifiers to use.

Autodetect - the WPAD protocol is used to probe the network (using DHCP/DNS) and possibly discover the URL of a PAC script.

Proxy Server Schemes

When using an explicit proxy in the browser, multiple layers of the network request are impacted, depending on the scheme that is used. Some implications of the proxy scheme are:

Is communication to the proxy done over a secure channel? Is name resolution (ex: DNS) done client side, or proxy side? What authentication schemes to the proxy server are supported? What network traffic can be sent through the proxy? Edge supports these proxy server schemes:

DIRECT Proxy Scheme

Default port: N/A (neither host nor port are applicable) Example identifier (PAC): DIRECT Example identifier (URI): direct:// This is a pseudo proxy scheme that indicates instead of using a proxy we're sending the request directly to the target server.

It's imprecise to call this a "proxy server," but it's a convenient abstraction.

HTTP Proxy Scheme

Default port: 80 Example identifier (PAC): PROXY proxy:8080, proxy (nonstandard; don't use) Example identifiers (URI): http://proxy:8080, proxy:8080 (can omit scheme) Generally when one refers to a "proxy server" or "web proxy," they're talking about an HTTP proxy.

When using an HTTP proxy in Edge, name resolution is always deferred to the proxy. HTTP proxies can proxy http://, https://, ws:// and wss:// URLs.

Communication to HTTP proxy servers is insecure, meaning proxied http:// requests are sent in the clear. When proxying https:// requests through an HTTP proxy, the TLS exchange is forwarded through the proxy using the CONNECT method, so end-to-end encryption isn't broken. However when establishing the tunnel, the hostname of the target URL is sent to the proxy server in the clear.

HTTP proxies in Edge support the same HTTP authentication schemes as for target servers: Basic, Digest, Negotiate, NTLM.

HTTPS Proxy Scheme

Default port: 443 Example identifier (PAC): HTTPS proxy:8080 Example identifier (URI): https://proxy:8080

This works like an HTTP proxy, except the communication to the proxy server is protected by TLS, and may negotiate HTTP/2 (but not QUIC).

Because the connection to the proxy server is secure, https:// requests sent through the proxy aren't sent in the clear as with an HTTP proxy. Similarly, since CONNECT requests are sent over a protected channel, the hostnames for proxied https:// URLs is also not revealed.

In addition to the usual HTTP authentication methods, HTTPS proxies also support client certificates.

HTTPS proxies using HTTP/2 can offer better performance in Edge than a regular HTTP proxy due to higher connection limits (HTTP/1.1 proxies in Edge are limited to 32 simultaneous connections across all domains).

Edge, Firefox, and Opera support HTTPS proxies; however, most older HTTP stacks don't.

Specifying an HTTPS proxy isn't possible through system proxy settings. Instead, one must use either a PAC script or an Edge proxy setting (command line, extension, or policy).

SOCKSv4 Proxy Scheme

Default port: 1080 Example identifiers (PAC): SOCKS4 proxy:8080, SOCKS proxy:8080 Example identifier (URI): socks4://proxy:8080 SOCKSv4 is a simple transport layer proxy that wraps a TCP socket. Its use is transparent to the rest of the protocol stack; after an initial handshake when connecting the TCP socket (to the proxy), the rest of the loading stack is unchanged.

No proxy authentication methods are supported for SOCKSv4.

When using a SOCKSv4 proxy, name resolution for target hosts is always done client side, and moreover must resolve to an IPv4 address (SOCKSv4 encodes target address as four octets, so IPv6 targets aren't possible).

There are extensions to SOCKSv4 that allow for proxy side name resolution, and IPv6, namely SOCKSv4a. However Edge doesn't allow configuring, or falling back to v4a.

A better alternative is to just use the newer version of the protocol, SOCKSv5 (which is still 20+ years old).

SOCKSv5 Proxy Scheme

Default port: 1080 Example identifier (PAC): SOCKS5 proxy:8080 Example identifiers (URI): socks://proxy:8080, socks5://proxy:8080

SOCKSv5 is a transport layer proxy that wraps a TCP socket, and allows for name resolution to be deferred to the proxy.

In Edge when a proxy's scheme is set to SOCKSv5, name resolution is always done proxy side (even though the protocol allows for client side as well). In Firefox client side vs proxy side name resolution can be configured with network.proxy.socks_remote_dns; Edge has no equivalent option and will always use proxy side resolution.

No authentication methods are supported for SOCKSv5 in Edge (although some do exist for the protocol).

A handy way to create a SOCKSv5 proxy is with ssh -D, which can be used to tunnel web traffic to a remote host over SSH.

In Edge SOCKSv5 is only used to proxy TCP-based URL requests. It can't be used to relay UDP traffic.

Manual Proxy Settings

The simplest way to configure proxy resolution is by providing a static list of rules comprised of:

A mapping of URL schemes to proxy server identifiers A list of proxy bypass rules We refer to this mode of configuration as "manual proxy settings".

Manual proxy settings can succinctly describe setups like:

Use proxy http://foo:8080 for all requests Use proxy http://foo:8080 for all requests except those to a contoso.com subdomain Use proxy http://foo:8080 for all https:// requests, and proxy socks5://mysocks:90 for everything else Although manual proxy settings are a ubiquitous way to configure proxies across platforms, there's no standard representation or feature set.

Edge's manual proxy settings most closely resembles that of WinInet. But it also supports idioms from other platforms -- for instance KDE's notion of reversing the bypass list, or Gnome's interpretation of bypass patterns as suffix matches.

When defining manual proxy settings in Edge, we specify three (possibly empty) lists of proxy server identifiers:

proxies for HTTP - A list of proxy server identifiers to use for http:// requests, if nonempty proxies for HTTPS - A list of proxy server identifiers to use for https:// requests, if nonempty other proxies - A list of proxy server identifiers to use for everything else (not matched by the other two lists) There are many ways to end up with manual proxy settings in Edge (discussed in other sections).

The following examples use the command line method. Launching Edge with --proxy-server=XXX (and optionally --proxy-bypass-list=YYY)

Example: To use proxy http://foo:8080 for all requests we can launch Edge with --proxy-server="http://foo:8080". This translates to:

proxies for HTTP - empty proxies for HTTPS - empty other proxies - http://foo:8080 With the above configuration, if the proxy server was unreachable all requests would fail with ERR_PROXY_CONNECTION_FAILED. To address this, we could add a fallback to DIRECT by launching using --proxy-server="http://foo:8080,direct://" (note the comma separated list). This command line means:

proxies for HTTP - empty proxies for HTTPS - empty other proxies - http://foo:8080, direct:// If instead we wanted to proxy only http:// URLs through the HTTPS proxy https://foo:443, and have everything else use the SOCKSv5 proxy socks5://mysocks:1080 we could launch Edge with --proxy-server="http=https://foo:443;socks=socks5://mysocks:1080". This now expands to:

proxies for HTTP - https://foo:443 proxies for HTTPS - empty other proxies - socks5://mysocks:1080 The command line above uses WinInet's proxy map format, with some extra features:

Instead of naming proxy servers by just a hostname:port, you can use Edge's URI format for proxy server identifiers. In other words, you can prefix the proxy scheme so it doesn't default to HTTP. The socks= mapping is understood more broadly as "other proxies". The subsequent proxy list can include proxies of any scheme, however if the scheme is omitted it will be understood as SOCKSv4 rather than HTTP.

Mapping WebSocket URLs to a Proxy

Manual proxy settings don't have mappings for ws:// or wss:// URLs.

Selecting a proxy for these URL schemes is a bit different from other URL schemes. The algorithm that Edge uses is:

If "other proxies" is nonempty use it If "proxies for HTTPS" is nonempty use it Otherwise use "proxies for HTTP" This is per the recommendation in section 4.1.3 of RFC 6455.

It's possible to route ws:// and wss:// separately using a PAC script.

Proxy Credentials in Manual Proxy Settings

Most platforms' manual proxy settings allow specifying a cleartext username/password for proxy sign in. Edge doesn't implement this, and won't use any credentials embedded in the proxy settings.

Proxy authentication will instead go through the ordinary flow to find credentials.

Proxy Bypass Rules

In addition to specifying three lists of proxy server identifiers, Edge's manual proxy settings lets you specify a list of "proxy bypass rules" using URL patterns.

This ruleset determines whether a given URL should skip use of a proxy all together, even when a proxy is otherwise defined for it.

This concept is also known by names like "exception list," "exclusion list" or "no proxy list".

Proxy bypass rules can be written as an ordered list of strings. Ordering generally doesn't matter, but may when using subtractive rules.

When manual proxy settings are specified from the command line, the --proxy-bypass-list="RULES" switch can be used, where RULES is a semicolon or comma separated list of bypass rules.

See proxy config URL patterns for the URL patterns format that Edge supports for proxy bypass rules.

When using system proxy settings, one should use the platform's rule format and not Edge's.

Proxy Config URL Patterns

This section describes string constructions that Edge supports for specifying URL patterns in the context of proxy configuration - for example, proxy bypass rules or for the DestinationMatchers value of the ProxyOverrideRules policy. These patterns can be used when defining a Edge manual proxy setting from command line flags, extensions, or policy.

Proxy Config URL Patterns: Hostname

[ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ]

Matches a hostname using a wildcard pattern, and an optional scheme and port restriction.

Examples:

foobar.com - Matches URL of any scheme and port, whose normalized host is foobar.com *foobar.com - Matches URL of any scheme and port, whose normalized host ends with foobar.com (for instance blahfoobar.com and foo.foobar.com) *.org:443 - Matches URLs of any scheme, using port 443 and whose top level domain is .org https://x.*.y.com:99 - Matches https:// URLs on port 99 whose normalized hostname matches x.*.y.com

Proxy Config URL Patterns: Subdomain

[ URL_SCHEME "://" ] "." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ]

Hostname patterns that start with a dot are special cased to mean a subdomain matches. .foo.com is effectively another way of writing *.foo.com.

Examples:

.contoso.com - Matches outlook.contoso.com and foo.bar.contoso.com, but not contoso.com http://.contoso.com - Matches only http:// URLs that are a subdomain of contoso.com

Proxy Config URL Patterns: IP Literal

[ SCHEME "://" ] IP_LITERAL [ ":" PORT ]

Matches URLs that are IP address literals, and optional scheme and port restrictions. This is a special case of hostname matching that takes into account IP literal canonicalization. For example the rules [0:0:0::1] and [::1] are equivalent (both represent the same IPv6 address).

Examples:

127.0.0.1 http://127.0.0.1 [::1] - Matches any URL to the IPv6 loopback address [0:0::1] - Same as above http://[::1]:99 - Matches any http:// URL to the IPv6 loopback on port 99

Proxy Config URL Patterns: IPv4 Address Range

IPV4_LITERAL "/" PREFIX_LENGTH_IN_BITS

Matches any URL whose hostname is an IPv4 literal, and falls between the given address range.

Note this only applies to URLs that are IP literals.

Examples:

192.168.1.1/16

Proxy Config URL Patterns: IPv6 Address Range

IPV6_LITERAL "/" PREFIX_LENGTH_IN_BITS

Matches any URL that is an IPv6 literal that falls between the given range. IPv6 literals must not be bracketed.

Note this only applies to URLs that are IP literals.

Examples:

fefe:13::abc/33 [fefe::]/40 -- WRONG! IPv6 literals must not be bracketed

Proxy Config URL Patterns: Simple Hostnames

<local>

Matches hostnames without a period in them, and that aren't IP literals. This is a naive string search -- meaning that periods appearing anywhere count (including trailing dots!).

This rule corresponds to the "Exclude simple hostnames" checkbox on macOS and the "Don't use proxy server for local (intranet) addresses" on Windows.

The rule name comes from WinInet, and can easily be confused with the concept of localhost. However the two concepts are orthogonal. In practice one wouldn't add rules to bypass localhost, as it's already done implicitly.

Proxy Config URL Patterns: Subtract Implicit Rules

<-loopback>

Subtracts the implicit proxy bypass rules (localhost and link local addresses). This is only needed for test setups. Beware of the security implications to proxying localhost.

Whereas regular bypass rules instruct the browser about URLs that shouldn't use the proxy, this rule has the opposite effect and tells the browser to instead use the proxy.

Ordering may matter when using a subtractive rule, as rules will be evaluated in a left-to-right order. <-loopback>;127.0.0.1 has a subtly different effect than 127.0.0.1;<-loopback>.

Meaning of IP Address Range Bypass Rules

The IP address range bypass rule in manual proxy settings applies only to URL literals. This isn't what one would intuitively expect.

Example:

Say we configured a proxy for all requests, but added a bypass rule for 192.168.0.0.1/16. If we now navigate to http://foo (which resolves to 192.168.1.5 in our setup) the browser connect directly (bypass proxy) because we indicated a bypass rule that includes this IP?

It goes through the proxy.

The bypass rule in this case isn't applicable, since the browser never actually does a name resolution for foo. Proxy resolution happens before name resolution, and depending on what proxy scheme is later chosen, client side name resolution may never be performed.

The usefulness of IP range proxy bypass rules is rather limited, as they only apply to requests whose URL was explicitly an IP literal.

If proxy decisions need to be made based on the resolved IP addresses of a URL's hostname, one must use a PAC script.

Implicit Bypass Rules

Requests to certain hosts won't be sent through a proxy, and will instead be sent directly.

We call these implicit bypass rules. The implicit bypass rules match URLs whose host portion is either a localhost name or a link-local IP literal. Essentially it matches:

localhost *.localhost [::1] 127.0.0.1/8 169.254/16 [FE80::]/10 The complete rules are slightly more complicated. For instance on Windows, we also recognize loopback.

This concept of implicit proxy bypass rules is consistent with the platform-level proxy support on Windows and macOS (albeit with some differences due to their implementation quirks - see compatibility notes in net::ProxyHostMatchingRules::MatchesImplicitRules)

Why apply implicit proxy bypass rules in the first place? Certainly there are considerations around ergonomics and user expectation, but the bigger problem is security. Since the web platform treats localhost as a secure origin, the ability to proxy it grants extra powers. This is especially problematic when proxy settings are externally controllable, as when using PAC scripts.

Overriding the Implicit Bypass Rules

If you want traffic to localhost to be sent through a proxy despite the security concerns, it can be done by adding the special proxy bypass rule <-loopback>. This rule has the effect of subtracting the implicit rules.

For instance, launch Edge with the command line flag:

--proxy-bypass-list="<-loopback>"

There currently is no mechanism to disable the implicit proxy bypass rules when using a PAC script. Proxy bypass rules only apply to manual settings, so this technique can't be used to let PAC scripts decide the proxy for localhost URLs.

Content license

Note

Portions of this page are modifications based on work created and shared by Chromium.org and used according to terms described in the Creative Commons Attribution 4.0 International License. The original Chromium page can be found here.

Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.

  • Last updated on