PAC files for web targets

• Back to the WebView main page

A policy can route the web traffic of its sessions with a PAC file.
The PAC file picks the exit of each address the page opens: a direct connection or one of your upstream proxies.
Use it when one application needs several exits.

A typical case: an internal application loads scripts from a public CDN, or sends the user to an external identity provider during the sign-in.
The application itself must be reached directly.
The external sites must go through the corporate proxy.
A single upstream proxy per policy cannot give both exits, and a PAC file can.

How the bastion applies the PAC file

The browser of the session never reads the PAC file.
The filtering proxy of the session evaluates it, so the PAC file cannot bypass the allowed sites or the protection of the bastion.

1. The page asks for an address.
2. The filtering proxy checks the allowed sites of the target.
   An address outside the list is blocked, whatever the PAC file says.
3. The filtering proxy calls FindProxyForURL(url, host).
   For an HTTPS address, the URL holds only the scheme and the host, without path or query, like in Chromium.
4. It tries the answers in their order: DIRECT, or PROXY host:port.
   An answer such as PROXY a:8080; PROXY b:3128; DIRECT gives three attempts.
5. A DIRECT answer still goes through the refusals of the filtering proxy.
   The addresses of the bastion and its local addresses stay out of reach.

Only declared proxies are used

A PROXY host:port answer is followed only when host:port matches an enabled proxy of the Web target proxies list.
That entry also gives the account sent to the proxy.
Any other proxy is skipped and the next answer is tried.
The bridge logs the skipped proxy once per session.
No credential is ever sent to a proxy you did not declare.

SOCKS, SOCKS4, SOCKS5 and HTTPS host:port answers are skipped the same way.

When the PAC file fails

The PAC file fails when it raises an error, runs too long or returns no usable answer.
An answer that names only undeclared or disabled proxies counts as no usable answer.

• By default, the request is refused.
  The traffic never leaves directly because of an error.
• With the policy option Direct Exit If The PAC File Fails, the request leaves directly instead.

Limits of the evaluation

The standard PAC functions are available: isPlainHostName, dnsDomainIs, localHostOrDomainIs, isResolvable, isInNet, dnsResolve, myIpAddress, dnsDomainLevels, shExpMatch, weekdayRange, dateRange, timeRange.
dnsResolve and isResolvable use the DNS of the session, so the network namespace of the policy when it has one.

Requirements

When one of them is older, the policy window shows a warning as soon as you choose a PAC file.
The sessions of that policy are then refused with the reason web_engine_outdated.
They never leave directly.

1. Declare the upstream proxies

Declare first every proxy the PAC file can name, in RDP Proxy > Web target proxies.
The host and the port must be the ones written in the PAC file.
See Upstream proxy.

2. Add the PAC file

The PAC files section is below the upstream proxies, in the same tab.

The Corporate routing PAC file is used by one policy.
It names the Corporate proxy.

Click New PAC file.
Give a name, then choose the source.

Upload a file

Pick the file, or paste its content in the text area.

The browser reads the file and copies it into the text area.
The file must define FindProxyForURL(url, host), in UTF-8, 256 KiB at most.
The bastion runs it once before saving it.
A file with a syntax error, or without FindProxyForURL, is refused.

Download from a URL

The bastion downloads the file when you save, then every hour.

• The URL starts with http:// or https://.
• A URL with a user name or a password (user:password@) is refused.
  Publish the file without authentication.
• The download goes through the outgoing proxy of the appliance when one is set.
  It stops after 5 seconds or 256 KiB.
• The certificate of the server is verified.
  With an internal certificate authority, add it to the trust store of the appliance first.
• At most 5 redirections are followed.
  A redirection from HTTPS to HTTP is refused.
• If the URL cannot be reached when you save, nothing is saved.
• If a later download fails, the bastion keeps the last good version.
  The list shows Last error under the source.

A new version applies to the web sessions opened afterwards.
Open sessions keep the version they started with.

3. Test the PAC file

Click the test button of the PAC file, type a URL and click Launch test.
The bastion runs FindProxyForURL and opens no connection.
Leave the host empty to use the host of the URL.

The first proxy is not declared and is skipped.
The session will use Corporate proxy.

The eye button shows the content of the file, its SHA-256 and the number of policies that use it.

Preview of the Corporate routing PAC file.

4. Choose the PAC file in the policy

Open the policy.
In Route Of Web Targets, choose the PAC file.
This list holds three kinds of choice: None (direct connection), an upstream proxy or a PAC file.
A policy uses one of them, never a proxy and a PAC file together.

The policy Plant applications routes its web targets with Corporate routing.

Direct Exit If The PAC File Fails appears only when a PAC file is chosen.
Leave it off unless a direct exit is acceptable for this policy.

A PAC file whose last download failed stays in the list with the mark failing.
The policy keeps using its last good version.

Example

function FindProxyForURL(url, host) {
  // Intranet: no proxy
  if (isPlainHostName(host) || shExpMatch(host, "192.168.1.*") || dnsDomainIs(host, ".corp.local"))
    return "DIRECT";
  // Accounting application and its external identity provider: corporate proxy
  if (dnsDomainIs(host, "artica.work") || dnsDomainIs(host, ".microsoftonline.com"))
    return "PROXY 10.20.0.5:8080; PROXY 192.168.1.29:3128";
  // Supplier portals in plain HTTP: corporate proxy
  if (dnsDomainIs(host, "neverssl.com"))
    return "PROXY 192.168.1.29:3128";
  return "DIRECT";
}

Every host used here must also be in the allowed sites of the target.
The PAC file only chooses the exit of a site the target already allows.

Check the targets

The Status column of the Targets tab evaluates the PAC file of the policy for each web target.
It then tries the chosen exit like a session would.
See Read the status column.

Delete a PAC file

A PAC file used by a policy cannot be deleted.
The bastion answers pac_in_use.
Choose another route in these policies first.

While a policy uses this PAC file, the upstream proxies it cites cannot be deleted.
The bastion answers proxy_in_pac.

Refused sessions

A request refused by the PAC file does not close the session.
Only that request fails.
See also Events and troubleshooting.

REST API

Creating, replacing and deleting a PAC file are written to the security audit trail.