How to use Proxy Automatic Configuration with Skyhigh Web Gateway

Technical Articles ID: KB67177
Last Modified: 2023-06-22 11:14:28 Etc/GMT

Environment

Skyhigh Web Gateway (SWG)

Summary

About PAC files
Proxy Automatic Configuration (PAC) is a proxy mode where the proxy configuration is described in a file using JavaScript. The file is called a PAC file and has .pac as the file extension. The network administrator maintains the file. The user doesn't need to update the file. As a browser user, you only need a URL provided by your administrator.

PAC has two advantages over normal configurations:

Network-based .pac files are centrally administered and easy to update. Network administrators usually share the .pac files using HTTP. If there are server changes or network outages, the .pac file can be changed, and your browser configuration is automatically updated when the new .pac file is loaded.
You can use complicated network environments with a single configuration. PAC has support for load balancing and failover.

All browsers can use .pac files. The JavaScript contained within a .pac file can perform tasks and make decisions based on the following:

The URL to which you're browsing
The IP address of your browser, and which proxy should service the traffic
Alternative proxies that should be used

The file defines the function FindProxyForURL(url, host). When you enter a URL into a browser, the URL and domain are sent as parameters to the function and a proxy setting is returned based on that data.

Using a PAC file with SWG
Browsers must retrieve a PAC file from a web server. SWG can host the PAC file, but that's the limit of its deployment participation. You still need some external method to tell the browser to use it. Web Proxy Autodiscovery Protocol (WPAD) or Group Policy Objects (GPOs) provide this function. Both these methods are discussed later in this article.

The PAC file is typically named proxy.pac. SWG uses this naming convention when hosting the PAC file. But, when used with WPAD, it's renamed to wpad.dat, which is the same file but with a different name.

Solution

This section discusses the following PAC file topics:

PAC Examples
PAC Considerations when used with S W G
Uploading a PAC File to SWG
Using GPOs to Tell Browsers to use the PAC File
Using Web Proxy Auto Discovery Protocol (WPAD) to Tell Browsers to use the PAC File

PAC Examples:

The contents of the PAC file vary depending on your environment and preferences. By putting more complexity in the PAC file logic, you can granularly regulate the behavior of the browser's proxy use. Below are some example PAC file contents. More documentation for PAC file options is available on the internet.

The following is the simplest example of a PAC file. It directs all requests to the proxy (SWG). In this example, the SWG IP address is 192.168.0.222.

function FindProxyForURL(url, host) {return "PROXY 192.168.0.222:9090";}

This PAC is identical to configuring the following Internet Explorer proxy settings:
This example directs all requests to SWG (192.168.0.222), and fails over to a second proxy (192.168.0.223) if SWG is unavailable. (This failover function can't be emulated directly within a browser's proxy settings.)

function FindProxyForURL(url, host) {return "PROXY 192.168.0.222:9090; PROXY 192.168.0.223:9090";}
This example tells the browser to make a direct connection, rather than using a proxy, if both proxies (192.168.0.222 and 192.168.0.223) are unavailable.

function FindProxyForURL(url, host) {return "PROXY 192.168.0.222:9090; PROXY 192.168.0.223:9090; DIRECT";}
This example tells the browser to use the proxy for all URLs except those URLs within the *.company.com domain.

function FindProxyForURL(url, host) { if (dnsDomainIs(host, ".company.com")) return "DIRECT"; else return "PROXY proxy01.company.com:9090"; }
This example tells the browser to use the proxy for all URLs, except those URLs with an IP address within the internal subnet 10.1.1.0/24.

function FindProxyForURL(url, host) { if (isInNet(host, "10.1.1.0", "255.255.255.0")) return "DIRECT"; else return "PROXY proxy01.company.com:9090"; }
This example is more complex. If your local address is in the subnet 10.1.1.0/24, use proxy01. Use proxy03 if you're anywhere else on the network. proxy02 is a standby if either proxy01 or proxy03 fails. If the destination is within the local subnets or *.company.com, don't use a proxy.

function FindProxyForURL(url, host) { if (dnsDomainIs(host, ".company.com") || isInNet(host, "10.1.1.0", "255.255.255.0") || isInNet(host, "192.168.1.0", "255.255.255.0")) return "DIRECT"; else if (isInNet(myIPAddress(), "10.1.1.0", "255.255.255.0")) return "PROXY proxy01.company.com:9090; proxy02.company.com:9090"; else return "PROXY proxy03.company.com:9090; proxy02.company.com:9090"; }

PAC Considerations when used with SWG

We recommend that you don't proxy the following types of connections:

Internal to internal
To SWG

Web proxies were originally used as a simple gateway mechanism to cache the flow of traffic to the internet. A request would be made to a proxy server, which would service that request and respond with the page. It's common practice to not proxy connections that are destined for an internal web server in your private network.

SWG performs many security functions using a single session from the client to the server. (For example, caching, content scanning, authentication, and SSL decryption.) This single session reduces network traffic.

Because SWG uses techniques like page redirection, session injection, and JavaScript insertion, it's important that traffic to SWG is not proxied. For example, don't proxy the administration session to the SWG user interface because it might intercept and filter important information out of the session.

You can define these exceptions in the PAC file the browser uses. You might need to specify the exceptions differently depending on browser because not all browsers interpret the PAC file in the same manner.

Suppose that you have the following network:

The local DNS domain of the network is company.local. Any host within this domain is resolved to an internal private IP address.
The domain company.com is contained within a DMZ that's accessible from the internet. But, when an internal user resolves that domain, the private DMZ addresses are returned, not the public addresses (common in a split-DNS environment).
The LAN IP addresses are split between two physical locations and subnets:
- Location A: 10.1.0.0/16
- Location B: 10.2.0.0/16
There are two SWGs, one at each location:
- Location A: proxy01.company.local = 10.1.0.222
- Location B: proxy02.company.local = 10.2.0.222
The DMZ IP addresses are 172.16.0.0/16.
There are some Guest Wireless networks with the IP addresses 192.168.0.0/16.
There's a third proxy, Squid proxy, used only by the Wireless network. It's in the DMZ with other servers. The DMZ Squid proxy is squid.company.com = 172.16.0.222.

Below are some examples of how to create the exceptions:

Excluding the local domains
Use these statements to exclude the local domain from being proxied.
For example, http://company.com, http://host.company.com, http://host.company.com:8888, http://company.local, http://host.company.local, and http://host.company.local:8888.

if (dnsDomainIs(host,"company.com")) {return "DIRECT";} if (dnsDomainIs(host,"company.local")) {return "DIRECT";}
Excluding all private subnets
Check whether the URL specified is an IP address that matches any of your private subnets. The following statement uses a shExpMatch to perform a string lookup of the address. If the subnets are on non-octet boundaries (not /8, /16, or /24), this function doesn’t work.

if ((shExpMatch(host,"127.0.0.1")) || (shExpMatch(host,"10.*.*.*")) || (shExpMatch(host,"172.16.*.*")) || (shExpMatch(host,"192.168.*.*")) ) {return "DIRECT";}

Or, you can use the isInNet function, but it tries to resolve everything that isn't an IP address. The browser performs a DNS lookup for every request. If your client can't resolve internet addresses, there's a long delay before it times out and a page is returned. So, it's not recommended to use this approach unless your internal DNS can resolve internet addresses.

if ((isInNet(host, "127.0.0.1", "255.255.255.255")) || (isInNet(host, "10.0.0.0", "255.0.0.0")) || (isInNet(host, "172.16.0.0", "255.240.0.0")) || (isInNet(host, "192.168.0.0", "255.255.0.0")) ) {return "DIRECT";}
Excluding plain host names
You might specify a short host name (a host with no dots in its name) instead of a fully qualified domain name (FQDN) in the URL. Examples of this include http://localhost, http://localhost:8888, http://intranet, http://webmail/, http://server:8888, and https://proxy01:10000. Although your local computer might resolve that name using DNS or WINS, it’s unlikely that SWG can. Use the following statement to exclude a short host name:

if (isPlainHostName(host)) {return "DIRECT";}

This function is the same as selecting Bypass proxy server for local addresses in the browser. You can have DNS search suffixes appended to a host name in SWG. So, if you sometimes want SWG to resolve short names, you can edit file /etc/resolv.conf and change the search entry.
Excluding SWG itself from being proxied
This exclusion is the most important part of a PAC file when used with SWG. Because SWG has many techniques to manipulate traffic for security and authentication, it's imperative that any session directed to SWG, under any port number, is excluded. When it isn't, unpredictable results might be seen due to proxy loop conditions occurring. The above statements might cover the conditions in which local traffic is excluded from being proxied.
You can, as a last resort, explicitly exclude the proxies by IP address, host, and FQDN to make sure that they're covered. If the Squid proxy is using some filtering too, include it in this list to make sure that block pages are displayed properly.

To achieve this exclusion in the above described network:

if (shExpMatch(host,"10.1.0.222")) {return "DIRECT";} //proxy01's IP address if (shExpMatch(host,"10.2.0.222")) {return "DIRECT";} //proxy02's IP address if (shExpMatch(host,"172.16.0.222")) {return "DIRECT";} //squids's IP address if (shExpMatch(host,"proxy01")) {return "DIRECT";} //proxy01's host name if (shExpMatch(host,"proxy02")) {return "DIRECT";} //proxy02's host name if (shExpMatch(host,"squid")) {return "DIRECT";} //sqids's host name if (shExpMatch(host,"proxy01.company.local")) {return "DIRECT";} //proxy01's FQDN if (shExpMatch(host,"proxy02.company.local")) {return "DIRECT";} //proxy02's FQDN if (shExpMatch(host,"squid.company.com")) {return "DIRECT";} //squid's FQDN

Deciding which proxy to use
The statements above determine which conditions bypass the proxy entirely. Now, you need to determine which proxy to use for other traffic. You can use conditional statements to determine which proxy based on the destination host, URL, and the source IP address of the user. For localization of proxy use according to your IP address, you can include statements like these:

if(isInNet(myIpAddress(),"10.1.0.0","255.255.0.0")) {return "PROXY proxy01.company.local:9090";} if(isInNet(myIpAddress(),"10.2.0.0","255.255.0.0")) {return "PROXY proxy02.company.local:9090";} if(isInNet(myIpAddress(),"192.168.0.0","255.255.0.0")) {return "PROXY squid.company.com:3128";}

This statement specifies that if you're in the 10.1.0.0/16 subnet, use proxy01. If you're in the 10.2.0.0/16 subnet, use proxy02. And, if you're using wireless on 192.168.0.0/16, use Squid. This method tells the browser to use the closest proxy according to subnet.
Redundancy/Failover
Specifying a single proxy as above doesn't allow for an alternative when the proxy isn't online. The return PROXY results are allowed to specify multiple proxies to fail over to if the first one isn't available. If you want to try proxy01, proxy02, and then Squid, use return statements like this:

{return "PROXY proxy01.company.local:9090; PROXY proxy02.company.local:9090; PROXY squid.company.com:3128";}

Each returned list of proxies can be unique. The local proxy is used first, the other remote proxy is tried second, and as a last resort, the Squid proxy is used.

Complete PAC file example
Using all components described above, the full PAC file might look like this:

function FindProxyForURL(url, host) { if (dnsDomainIs(host,"company.com")) {return "DIRECT";} //check for local domains if (dnsDomainIs(host,"company.local")) {return "DIRECT";} //check for local IP addresses if ((shExpMatch(host,"127.0.0.1")) || (shExpMatch(host,"10.*.*.*")) || (shExpMatch(host,"172.16.*.*")) || (shExpMatch(host,"192.168.*.*")) ) {return "DIRECT";} if (isPlainHostName(host)) {return "DIRECT";} //check for short host names //make absolutely sure the sessions to theses servers are in no way proxied if (shExpMatch(host,"10.1.0.222")) {return "DIRECT";} //proxy01's IP address if (shExpMatch(host,"10.2.0.222")) {return "DIRECT";} //proxy02's IP address if (shExpMatch(host,"172.16.0.222")) {return "DIRECT";} //squids's IP address if (shExpMatch(host,"proxy01")) {return "DIRECT";} //proxy01's host name if (shExpMatch(host,"proxy02")) {return "DIRECT";} //proxy02's host name if (shExpMatch(host,"squid")) {return "DIRECT";} //sqids's host name if (shExpMatch(host,"proxy01.company.local")) {return "DIRECT";} //proxy01's FQDN if (shExpMatch(host,"proxy02.company.local")) {return "DIRECT";} //proxy02's FQDN if (shExpMatch(host,"squid.company.com")) {return "DIRECT";} //squid's FQDN//if you get this far, then decide which proxy to use//use proxy01, proxy02, squid if in the 10.1.0.0 subnetif(isInNet(myIpAddress(),"10.1.0.0","255.255.0.0")) {return "PROXY proxy01.company.local:9090; PROXY proxy02.company.local:9090; PROXY squid.company.com:3128";}//use proxy02, proxy01, squid if in the 10.2.0.0 subnetif(isInNet(myIpAddress(),"10.2.0.0","255.255.0.0")) {return "PROXY proxy02.company.local:9090";} {return "PROXY proxy02.company.local:9090; PROXY proxy01.company.local:9090; PROXY squid.company.com:3128";}//only try squid. if on wireless network.if(isInNet(myIpAddress(),"192.168.0.0","255.255.0.0")) {return "PROXY squid.company.com:3128";}//as a last resort if no other conditions apply, use proxy01, proxy02, squidreturn "PROXY proxy01.company.local:9090; PROXY proxy02.company.local:9090; PROXY squid.company.com:3128";}

Uploading a PAC File to SWG

To host the PAC file on SWG:

Log on to the SWG user interface.
Go to Troubleshooting, Files, Upload.
Browse to and select the PAC file.

Now, you can configure the browsers to use the PAC file.

Example Internet Explorer setting:
Select Use automatic configuration script.
Address: http://10.1.0.222:4713/files/proxy.pac
Example Firefox setting:
Select Automatic proxy configuration URL and specify http://10.1.0.222:4713/files/proxy.pac.

Using GPOs to Tell Browsers to use the PAC File

The challenge most network administrators face is how to configure the browser settings to use a proxy without having to touch each desktop. In a Microsoft Active Directory environment, you can use the Group Policy feature to make this managed change. GPOs permit you to propagate centralized settings to individual systems or users. A comprehensive guide to GPO is beyond the scope of this article. See Microsoft documentation for planning and implementation of GPO. In its simplest terms, the Group Policy Editor creates GPOs and these objects are assigned to Active Directory containers.

Internet Explorer
The browser settings are maintained in the Internet Explorer Maintenance\Connection menu. A typical setting for use with a PAC file is in the Automatic Browser Configuration menu:

Group Policy Object Editor showing the Internet Explorer objects

Group Policy Object Editor showing the Internet Explorer objects

Automatic Browser Configuration tab showing settings

When using PAC files, Internet Explorer internally caches the proxy server's relationship with the destination website that's being viewed.

SWG hosts the injected files on its own interface on port 9999 (or others). SWG delivers the proxied content using port 9090 when performing the following:

Inserting block pages
Inserting coaching pages
Advertising image replacements
Performing proactive scanning script mitigation
Using Transparent Authentication with the built-in Authentication server

Internet Explorer always uses the proxy server through which the first connection to a specific host name is made, regardless of the settings in the PAC file.
The response from the destination website might have port 9999 coded within the contents, or a transparent authentication performing a redirect to 9094.
In these scenarios, subsequent requests for that site attempt use that alternative port instead of the proxy port of 9090.

When this condition occurs, the user sees symptoms of broken pages with graphics and style sheets not being loaded and error messages that state "Invalid Proxy Request." Other browsers don't exhibit these symptoms.

You can correct this condition by turning off the automatic proxy caching feature using one of the following options:

Update the following registry entry:

HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\CurrentVersion\Internet Settings

Value: EnableAutoproxyResultCache
Type: REG_DWORD
Data value: <0 = disable caching; 1 (or key not present) = enable automatic proxy caching (the default behavior)>
Use Group Policy at Console Root\Local Computer Policy\User Configuration\Administrative Templates\Windows Components\Internet Explorer\Disable caching of Auto-Proxy scripts.

You can find more information about this issue in this Microsoft article.

Mozilla Firefox
Third-party browsers such as Firefox usually don't have the mechanisms built-in to support Active Directory Group Policies. A special version of Firefox is packaged with a GPO administrative template to help in the deployment and management of Firefox. Get this version of Firefox from the FrontMotion Firefox page.

Here's an example of the template and settings that you can deploy:
GPO screen showing the location of the Proxy Settings policy

GPO screen showing the location of the Proxy Settings policy

Proxy Settings Properties with proxy.pac file location configured

Using Web Proxy Auto Discovery Protocol (WPAD) to Tell Browsers to use the PAC File

You can use WPAD to configure browser settings to use a proxy. Most standard browsers support this feature using auto-detect settings (Internet Explorer: Automatically detect settings / Firefox: Auto-detect proxy settings for this network).

WPAD is most useful for laptop users where a different proxy setting is needed depending on location. While in an office location, one PAC file is used. In a different location, a different PAC file is used, but while at home or on the road proxy settings aren’t needed. This configuration reduces the need for a user to constantly change proxy settings at different locations.

The WPAD protocol tries to discover proxy settings in the following order:

Use DHCP Option 252.
Use DNS to find wpad.dat.
Connect directly.

DHCP Option 252
If your client uses a DHCP server to assign its IP address before fetching its first page, the web browser makes a DHCPINFORM query to the DHCP server.
The browser asks for option 252, but Microsoft reserves Option 252 for a string value containing the URL for a PAC file.

See the Microsoft documentation for instructions to set up this option in a Microsoft DHCP server. Here are the basic steps:

Create a Predefined Option for the server.
Add the definition for option 252.
Example:
Name: WPAD
Data type: String
Code: 252
Description: URL for Proxy Autodiscovery
Define the URL to use.
Example:
Option Class: DHCP Standard Options
Option name: 252 WPAD
String: http://10.1.0.222:4713/files/proxy.pac
Assign the option to a DHCP scope.

If the DHCP server doesn't supply the needed information, WPAD continues to the DNS method.

NOTE: Firefox doesn't support proxy auto discover using DHCP. For more information, see this Bugzilla page.

DNS for WPAD
The WPAD protocol defines a method in which a specific URL is used to locate the WPAD file. This URL is on a web server within the internal domain of the network. This web server is typically an IIS server, but can be any server type.

The hardcoded URL used is in the form of http://wpad.company.local:80/wpad.dat

Below is an explanation of each element of this URL:

http:// -This must reside on an HTTP server, not an HTTPS-only server.
wpad - The host name of the server hosting the file must have a DNS A record or CNAME aliasing it to the name of wpad.
company.local - The operating system must provide the correct domain name (domain suffix) to append to the host name (WPAD) before sending a query to the WPAD server. By default, the domain used is the client's primary domain suffix (the domain in which the client is located, or is configured to use). If the primary domain suffix doesn't work, the connection-specific DNS suffix is tried. If the WPAD server isn't found in the domain name, subdomains are removed from the domain until a WPAD server is located, or until the third-level domain is reached. For example, in the a.b.company.local domain, the following searches are made:
- wpad.a.b.company.local
- wpad.b.company.local
- wpad.company.local
If a WPAD server isn't located by the third-level domain, automatic discovery fails.

To determine what domain name is in use, check the Primary DNS suffix from a command prompt.

C:\>ipconfig /all

Windows IP Configuration
Host Name . . . . . . . . . . . . : mycomputer
Primary Dns Suffix . . . . . . . : company.local
:80 - The web server must be published on port 80.
wpad.dat - The wpad.dat file must be in the root folder; don’t modify the file name. The wpad.dat file contains the same information as the proxy.pac file described above but with a different name. When hosting the wpad.dat file on a web server, the MIME type must be set as application/x-ns-proxy-autoconfig.

You must host a wpad.dat file on a web server. The server must use port 80 with a DNS name of wpad.domain.local. It’s common to use one or more existing intranet servers to support this method. But a technique of hosting the wpad.dat file on the SWG appliance is described below.

Direct Connection
If the two previous methods fail to produce a PAC file for use by the browser, the browser connects directly to the destination site. This connection is the wanted behavior when a laptop is connected to a home or remote network that doesn't provide any proxy information.

Affected Products

Languages:

This article is available in the following languages:

Knowledge Center

How to use Proxy Automatic Configuration with Skyhigh Web Gateway

Environment

Summary

Solution

Affected Products

Languages:

Title

Title

Knowledge Center

How to use Proxy Automatic Configuration with Skyhigh Web Gateway

Environment

Summary

Solution

Affected Products

Languages:

Choose your region

Title

Title