diff --git a/public/__redirects b/public/__redirects index 0c8913ba01dda37..cc6ba241d1e2bac 100644 --- a/public/__redirects +++ b/public/__redirects @@ -2301,6 +2301,7 @@ /cloudflare-one/team-and-resources/devices/warp/user-side-certificates/ /cloudflare-one/team-and-resources/devices/user-side-certificates/ 301 /cloudflare-one/traffic-policies/lists/ /cloudflare-one/reusable-components/lists/ 301 /cloudflare-one/traffic-policies/ids/ /cloudflare-one/traffic-policies/enable-ids/ 301 +/cloudflare-one/team-and-resources/devices/agentless/pac-files/ /cloudflare-one/team-and-resources/devices/agentless/pac-files/configure-pac-files/ 301 # Email Security new revamp (statics) /cloudflare-one/email-security/auto-moves/ /cloudflare-one/email-security/settings/auto-moves/ 301 diff --git a/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/best-practices.mdx b/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/best-practices.mdx new file mode 100644 index 000000000000000..837a1b63fd59e39 --- /dev/null +++ b/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/best-practices.mdx @@ -0,0 +1,201 @@ +--- +pcx_content_type: how-to +title: PAC file best practices +sidebar: + order: 2 +--- + +A PAC file is a text file that specifies which traffic should redirect to the proxy server. When a browser makes a web request, it consults the PAC file's `FindProxyForURL()` function, which evaluates the request and returns routing instructions, such as a direct connection, proxy server, or failover sequence. + +## Create a PAC file + +To create a PAC file: + +1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolvers & Proxies** > **Proxy endpoints**. +2. Create a proxy endpoint. +3. Once you create a proxy endpoint, select **Add PAC files**. +4. Here, you can add **PAC file details** and **Setup instructions**. + + In **PAC file details**: + - Enter the **Basic Information**. + - Enter the **PAC file configuration** > Select **Browse PAC file configuration templates** and choose a pre-configured template to customize. The only available outputs are Okta and Azure. Once you select the template, the **PAC file JavaScript** will be populated with the selected template. + + In **Setup instructions:** + - Choose a browser and follow the instructions. + +5. Select **Create**. + +Your PAC file is of the form: + +```txt +https://pac.cloudflare-gateway.com// +``` + +## PAC file format + +Below is the default Zero Trust PAC file. You can [customize the file](https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) and host it somewhere your browser can access, such as on an internal web server or on [Cloudflare Workers](/workers/). + +```js +function FindProxyForURL(url, host) { + // No proxy for private (RFC 1918) IP addresses (intranet sites) + if ( + isInNet(dnsResolve(host), "10.0.0.0", "255.0.0.0") || + isInNet(dnsResolve(host), "172.16.0.0", "255.240.0.0") || + isInNet(dnsResolve(host), "192.168.0.0", "255.255.0.0") + ) { + return "DIRECT"; + } + + // No proxy for localhost + if (isInNet(dnsResolve(host), "127.0.0.0", "255.0.0.0")) { + return "DIRECT"; + } + + // Proxy all + return "HTTPS 3ele0ss56t.proxy.cloudflare-gateway.com:443"; +} +``` + +:::note + +- Make sure the directive used for the endpoint is `HTTPS` and not `PROXY`. +- You must use a PAC file instead of configuring the endpoint directly in the proxy configuration of the browser. This is because modern browsers still do not support HTTPS proxies without PAC files. +- Use a proper text editor such as VS Code to avoid extra characters. + +::: + +## Performance optimization + +PAC files are evaluated for every request, so optimizing their performance is critical to avoid delays in web browsing. + +### Minimize DNS lookups + +Avoid or minimize the use of `isInNet()`, `isResolvable()`, and `dnsResolve()` functions, as these send queries to the DNS subsystem and can significantly slow down request processing. + +Instead of using `isInNet()` for IP range checks, use `shExpMatch()` for faster string comparison: + +```js +// Slower - requires DNS lookup +if (isInNet(hostIP, "10.0.0.0", "255.0.0.0")) return "DIRECT"; + +// Faster - string comparison only +if (shExpMatch(hostIP, "10.*")) return "DIRECT"; +``` + +### Use variables to cache DNS results + +If you must perform DNS resolution, store the result in a variable to avoid multiple lookups: + +```js +function FindProxyForURL(url, host) { + // Resolve once and reuse + var hostIP = dnsResolve(host); + + if (isInNet(hostIP, "10.0.0.0", "255.0.0.0")) { + return "DIRECT"; + } + + // Reuse hostIP for additional checks + if (isInNet(hostIP, "172.16.0.0", "255.240.0.0")) { + return "DIRECT"; + } + + return "HTTPS proxy.example.com:443"; +} +``` + +### Use string matching for domain checks + +For internal domain checks, use `shExpMatch()` instead of `dnsDomainIs()` when possible: + +```js +// Using shExpMatch for faster performance +if (shExpMatch(host, "*.internal.company.com")) return "DIRECT"; + +// Equivalent but slower +if (dnsDomainIs(host, ".internal.company.com")) return "DIRECT"; +``` + +### Check for plain hostnames first + +NetBIOS names (hostnames without periods) are typically internal and should bypass the proxy. Check for these first: + +```js +if (isPlainHostName(host)) return "DIRECT"; +``` + +## Advanced techniques + +### Protocol-based routing + +You can route traffic to different proxies based on the protocol: + +```js +function FindProxyForURL(url, host) { + // Extract protocol from URL + var protocol = url.substring(0, url.indexOf(":")); + + if (protocol === "https") { + return "HTTPS secure-proxy.example.com:443"; + } else if (protocol === "http") { + return "HTTPS proxy.example.com:443"; + } + + return "DIRECT"; +} +``` + +### Failover configuration + +Provide fallback proxies for high availability: + +```js +// Try primary proxy, then secondary, then direct connection +return "HTTPS primary.proxy.cloudflare-gateway.com:443; HTTPS secondary.proxy.cloudflare-gateway.com:443; DIRECT"; +``` + +### Case sensitivity handling + +JavaScript is case-sensitive. Convert hostnames to lowercase for consistent matching: + +```js +function FindProxyForURL(url, host) { + // Normalize to lowercase + host = host.toLowerCase(); + url = url.toLowerCase(); + + if (shExpMatch(host, "*.example.com")) { + return "DIRECT"; + } + + return "HTTPS proxy.cloudflare-gateway.com:443"; +} +``` + +## Troubleshooting + +### Validate syntax + +PAC files use JavaScript syntax. A single syntax error (such as a missing closing parenthesis or bracket) will cause the entire PAC file to fail. Use a JavaScript-aware text editor to catch syntax errors before deployment. + +### Test return values + +The `FindProxyForURL` function must return one of these formats: + +- `DIRECT`: Connect directly to the destination +- `HTTPS host:port`: Use an HTTPS proxy (required for Gateway) +- `PROXY host:port`: Use an HTTP proxy (not supported by Gateway) + +Multiple return values can be separated by semicolons for fallback: + +```js +return "HTTPS proxy1.example.com:443; HTTPS proxy2.example.com:443; DIRECT"; +``` + +### Common issues + +**PAC file not loading**: Ensure the PAC file is hosted on an accessible web server with the correct MIME type (`application/x-ns-proxy-autoconfig`). File-based PAC files (using `file://` protocol) are not supported in modern browsers. + +**Slow browsing**: Excessive DNS lookups in the PAC file can cause delays. Review your PAC file and optimize DNS-related functions. + +**Inconsistent behavior**: Different browsers may cache PAC files differently. Clear your browser cache and restart the browser after updating the PAC file. diff --git a/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files.mdx b/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/configure-pac-files.mdx similarity index 58% rename from src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files.mdx rename to src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/configure-pac-files.mdx index f6d65edc7c9860a..afb9a0ee065a9ad 100644 --- a/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files.mdx +++ b/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/configure-pac-files.mdx @@ -1,6 +1,6 @@ --- pcx_content_type: how-to -title: PAC files +title: Configure PAC files sidebar: order: 1 --- @@ -13,23 +13,31 @@ import { APIRequest, } from "~/components"; + + :::note -Only available on Enterprise plans. +PAC files are only available on Enterprise plans. ::: You can apply Gateway HTTP and DNS policies at the browser level by configuring a Proxy Auto-Configuration (PAC) file to connect to a proxy endpoint. - +When end users visit a website, their browser will send the request to a Cloudflare proxy server associated with your account to be filtered by Gateway. PAC files are evaluated by the browser for every request, determining whether traffic should go through the proxy or connect directly. Note that Gateway [cannot filter every type of HTTP traffic](#traffic-limitations) proxied using PAC files. If you want to use Gateway inspection policies, you will need to install a [Cloudflare certificate](/cloudflare-one/team-and-resources/devices/user-side-certificates/) on your devices. -When end users visit a website, their browser will send the request to a Cloudflare proxy server associated with your account to be filtered by Gateway. Note that Gateway [cannot filter every type of HTTP traffic](#limitations) proxied using PAC files. +PAC files offer several advantages: -## Prerequisites +- **Centralized management**: Update routing rules in one location without reconfiguring individual devices +- **Flexible routing**: Route different traffic types to different proxies or direct connections based on domain, IP range, or protocol +- **Load balancing**: Distribute traffic across multiple proxy servers with automatic failover -Install a [Cloudflare certificate](/cloudflare-one/team-and-resources/devices/user-side-certificates/) on your device. +:::note +PAC files require user interaction. Authorization endpoints require users to log in through [Cloudflare Access](/cloudflare-one/access-controls/policies/). PAC files do not support username/password or mTLS authorization. +::: ## 1. Generate a proxy endpoint -You can generate a proxy endpoint in Cloudflare One or through the Cloudflare API. +You can generate two types of proxy endpoint in Cloudflare One or through the Cloudflare API: IP and Authorization. + +Authorization endpoints require users to pass [Access policies](/cloudflare-one/access-controls/policies/policy-management/) to use the endpoint. Source IP endpoints only proxy traffic originating from a specific source IP. :::caution All devices you add to the proxy endpoint will be able to access your Cloudflare Tunnel applications and services. If you only want to proxy web traffic, you can build a network policy that blocks those source IPs from connecting to your internal resources. @@ -39,13 +47,53 @@ All devices you add to the proxy endpoint will be able to access your Cloudflare -1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolves & Proxies** > **Proxy endpoints**. +1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolvers & Proxies** > **Proxy endpoints**. 2. Select **Create proxy endpoint**. -3. Give your endpoint any name. +3. Select between **Add an authorization endpoint** or **Add a source IP endpoint**. + +:::note +Once you choose a type of proxy endpoint, you cannot revert this decision. +::: + +### Authorization endpoint + +Authorization endpoints support being associated with [Cloudflare Access](/cloudflare-one/access-controls/policies/) to provide full Zero Trust authorization capabilities. Authorization endpoints give you a comprehensive control of access policies to authorize traffic before it is sent for processing. + +Authorization endpoints offer a more flexible way to authorize traffic by leveraging Cloudflare Access. Authorization endpoints support associating a user identity with the connection. + +If you select **Add an authorization endpoint**: + +1. Enter your basic information. + +2. Add an existing policy, or [create a new policy](/cloudflare-one/access-controls/policies/). + +3. Add your login method. + +4. Once you have filled all the information, select **Save**. + +#### Edit authorization + +To edit an authorization endpoint: + +1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolvers & Proxies** > **Proxy endpoints**. +2. Select **Proxy endpoints**, and locate your authorization endpoint. The dashboard will display **Authorization** under **Type**. +3. Select the three dots, then select **Configure**. +4. Choose the information you want to edit: + - **Basic info**: Enter your basic info, then select **Save**. + - **Access policies**: Here, you can: + - Select existing policies or create a new policy. + - Select the three dots that allow you to + - **Login methods**: Select the [identity providers](/cloudflare-one/integrations/identity-providers/) you want to use to log in to this application. -4. Enter the public source IP address of your device(s) in CIDR notation. For example: +### Source IP endpoint + +When you configure a source IP endpoint, traffic authorization is determined by the source IP address of the incoming traffic. You configure the endpoint to allow traffic processing only from a specific pre-defined set of source IP addresses. + +If you select **Add a source IP endpoint**: + +1. Enter the public source IP address of your device(s) in CIDR notation. For example: - **IPv4**: `192.0.2.0/8` - **IPv6**: `2001:0db8:0000:0000:0000:1234:5678:0000/109` @@ -53,7 +101,7 @@ All devices you add to the proxy endpoint will be able to access your Cloudflare Gateway limits the prefix length of source networks for proxy endpoints to `/8` for IPv4 networks and `/32` for IPv6 networks. ::: -5. Select **Save endpoint** and confirm the endpoint creation. +2. Select **Save endpoint** and confirm the endpoint creation. Your Cloudflare proxy server domain is of the form: @@ -61,10 +109,22 @@ Your Cloudflare proxy server domain is of the form: https://.proxy.cloudflare-gateway.com ``` +#### Edit source IP endpoint + +To edit a source IP endpoint: + +1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolvers & Proxies** > **Proxy endpoints**. +2. Select **Proxy endpoints**, and locate your authorization endpoint. The dashboard will display **Source IP** under **Type**. +3. Select the three dots, then select **Configure**. +4. Edit the name and/or configure the source IPs that are allowed. +5. Select **Save**. + +### Source IP endpoint + 1. [Create a proxy endpoint](/api/resources/zero_trust/subresources/gateway/subresources/proxy_endpoints/methods/create/) with the following call: .proxy.cloudflare-gateway.com -## 2. Test your proxy server - -1. In [Cloudflare One](https://one.dash.cloudflare.com/), create an [HTTP policy](/cloudflare-one/traffic-policies/http-policies/) for testing purposes. For example: +## 2. Create a PAC file - | Selector | Operator | Value | Action | - | -------- | -------- | ------------- | ------ | - | Domain | in | `example.com` | Block | +A PAC file is a text file that specifies which traffic should redirect to the proxy server. You can create a PAC file in the Cloudflare dashboard or write your own custom PAC file. -2. Verify that nothing is returned by a `curl` command: - - ```sh - curl --ipv4 --proxytunnel --proxy https://3ele0ss56t.proxy.cloudflare-gateway.com https://example.com - ``` +For detailed instructions and examples for creating a PAC file, refer to [PAC file best practices](/cloudflare-one/team-and-resources/devices/agentless/pac-files/best-practices/). -If `curl` returns a `403` code, it means the public IP of your device does not match the one used to generate the proxy server. Make sure that WARP is turned off on your device and double-check that `curl` is not using IPv6 (use the `-4` option to force IPv4). +## 3. Configure your devices -## 3. Create a PAC file +### 3a. (Optional) Install Cloudflare certificate -A PAC file is a text file that specifies which traffic should redirect to the proxy server. +If you want to apply Gateway inspection policies or use features like the block page, [install a Cloudflare certificate](/cloudflare-one/team-and-resources/devices/user-side-certificates/) on your devices. -Below is the default PAC file. You can [customize the file](https://developer.mozilla.org/en-US/docs/Web/HTTP/Proxy_servers_and_tunneling/Proxy_Auto-Configuration_PAC_file) and host it somewhere your browser can access, such as on an internal web server or on [Cloudflare Workers](/workers/). - -```js -function FindProxyForURL(url, host) { - // No proxy for private (RFC 1918) IP addresses (intranet sites) - if ( - isInNet(dnsResolve(host), "10.0.0.0", "255.0.0.0") || - isInNet(dnsResolve(host), "172.16.0.0", "255.240.0.0") || - isInNet(dnsResolve(host), "192.168.0.0", "255.255.0.0") - ) { - return "DIRECT"; - } - - // No proxy for localhost - if (isInNet(dnsResolve(host), "127.0.0.0", "255.0.0.0")) { - return "DIRECT"; - } - - // Proxy all - return "HTTPS 3ele0ss56t.proxy.cloudflare-gateway.com:443"; -} -``` - -:::note - -- Make sure the directive used for the endpoint is `HTTPS` and not `PROXY`. -- You must use a PAC file instead of configuring the endpoint directly in the proxy configuration of the browser. This is because modern browsers still do not support HTTPS proxies without PAC files. -- Use a proper text editor such as VS Code to avoid added characters. - ::: - -## 4. Configure your devices +### 3b. Configure browser to use PAC file All major browsers support PAC files. You can configure individual browsers, or you can configure system settings that apply to all browsers on the device. Multiple devices can call the same PAC file as long as their source IP addresses were included in the proxy endpoint configuration. @@ -190,13 +212,13 @@ Safari relies on your operating system's proxy server settings. To configure you -## 5. Test your HTTP policy +## 4. Test your HTTP policy -To test your configuration, you can test any [supported HTTP policy](#limitations), such as the example policy created in [Step 2](#2-test-your-proxy-server). When you go to `https://example.com` in your browser, you should see the Gateway block page. +To test your configuration, create an [HTTP policy](/cloudflare-one/traffic-policies/http-policies/) to block a test domain. When you visit the blocked domain in your browser, you should see the Gateway block page (if you installed the Cloudflare certificate in Step 3a) or receive a connection error. You can now use the Proxy Endpoint selector in [network](/cloudflare-one/traffic-policies/network-policies/#proxy-endpoint) and [HTTP](/cloudflare-one/traffic-policies/http-policies/#proxy-endpoint) policies to filter traffic proxied via PAC files. -## Configure firewall +## 5. (Optional) Configure firewall You may need to configure your organization's firewall to allow your users to connect to a proxy endpoint. Depending on your firewall, you will need to create a rule using either your proxy endpoint's domain or IP addresses. @@ -206,7 +228,7 @@ To get the domain of a proxy endpoint: -1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolves & Proxies** > **Proxy endpoints**. +1. In [Cloudflare One](https://one.dash.cloudflare.com/), go to **Networks** > **Resolvers & Proxies** > **Proxy endpoints**. 2. Choose the proxy endpoint. Select **Edit**. 3. In **Proxy Endpoint**, copy the domain. @@ -312,10 +334,12 @@ To ensure responses are allowed through your firewall, add an inbound rule to al ### Traffic limitations -The agentless HTTP proxy does not support [identity-based policies](/cloudflare-one/traffic-policies/identity-selectors/) or mTLS authentication. +IP endpoints do not support [identity-based policies](/cloudflare-one/traffic-policies/identity-selectors/) or mTLS authentication. + +Both HTTP proxy endpoints only support proxying and filtering TCP traffic. -To enforce HTTP policies for UDP traffic, you must turn on the [Gateway proxy for UDP](/cloudflare-one/traffic-policies/http-policies/http3/#enable-http3-inspection). +Authorization endpoints do not support anything that is not HTTP/HTTPS. That means no other TCP or UDP protocol is supported, including [HTTP3](/cloudflare-one/traffic-policies/http-policies/http3/). ### Gateway DNS and resolver policies -Gateway DNS and resolver policies will always apply to traffic proxied via PAC files, regardless of device configuration. +Gateway DNS and resolver policies will always apply to traffic proxied with PAC files, regardless of device configuration. diff --git a/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/index.mdx b/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/index.mdx new file mode 100644 index 000000000000000..1198de0768d4005 --- /dev/null +++ b/src/content/docs/cloudflare-one/team-and-resources/devices/agentless/pac-files/index.mdx @@ -0,0 +1,9 @@ +--- +pcx_content_type: how-to +title: PAC files +sidebar: + order: 1 + group: + hideIndex: true +--- +