[Gateway] HTTP + custom block page redirect (#20687)

Co-authored-by: ranbel <[email protected]>
Co-authored-by: Kody Jackson <[email protected]>

Author: 3 people

src/content/changelog/gateway/2025-03-21-pdns-user-locations-role.mdx

@@ -2,20 +2,19 @@
 title: Secure DNS Locations Management User Role
 description: Create secure DNS locations using the new Cloudflare Zero Trust Locations Write role.
 date: 2025-03-21T13:50:40Z
-products: []
+products:
+  - gateway
 hidden: false
 ---
 
-We’re excited to introduce the [**Cloudflare Zero Trust Secure DNS Locations Write role**](/cloudflare-one/connections/connect-devices/agentless/dns/locations/#secure-dns-locations), designed to provide DNS filtering customers with granular control over third-party access when configuring their Protective DNS (PDNS) solutions.​
+We're excited to introduce the [**Cloudflare Zero Trust Secure DNS Locations Write role**](/cloudflare-one/connections/connect-devices/agentless/dns/locations/#secure-dns-locations), designed to provide DNS filtering customers with granular control over third-party access when configuring their Protective DNS (PDNS) solutions.
 
-Many DNS filtering customers rely on external service partners to manage their DNS location endpoints. This role allows you to grant access to external parties to administer DNS locations without overprovisioning their permissions.​
+Many DNS filtering customers rely on external service partners to manage their DNS location endpoints. This role allows you to grant access to external parties to administer DNS locations without overprovisioning their permissions.
 
 **Secure DNS Location Requirements:**
 
-- Mandate usage of [Bring your own DNS resolver IP addresses](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/agentless/dns/locations/dns-resolver-ips/#bring-your-own-dns-resolver-ip) if available on the account.​
+- Mandate usage of [Bring your own DNS resolver IP addresses](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/agentless/dns/locations/dns-resolver-ips/#bring-your-own-dns-resolver-ip) if available on the account.
 
-- Require source network filtering for IPv4/IPv6/DoT endpoints; token authentication or source network filtering for the DoH endpoint.​
+- Require source network filtering for IPv4/IPv6/DoT endpoints; token authentication or source network filtering for the DoH endpoint.
 
 You can assign the new role via Cloudflare Dashboard (`Manage Accounts > Members`) or via API. For more information, refer to the [Secure DNS Locations documentation](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/agentless/dns/locations/#secure-dns-locations).
-
-

src/content/changelog/gateway/2025-04-11-http-redirect-custom-block-page-redirect.mdx

@@ -0,0 +1,15 @@
+---
+title: HTTP redirect and custom block page redirect
+description: Redirect traffic with a Gateway HTTP Redirect policy, or with the block page in an HTTP or DNS Block policy.
+date: 2025-04-11T16:30:00Z
+products:
+  - gateway
+hidden: false
+---
+
+You can now use more flexible redirect capabilities in Cloudflare One with Gateway.
+
+- A new **Redirect** action is available in the HTTP policy builder, allowing admins to redirect users to any URL when their request matches a policy. You can choose to preserve the original URL and query string, and optionally include policy context via query parameters.
+- For **Block** actions, admins can now configure a custom URL to display when access is denied. This block page redirect is set at the account level and can be overridden in DNS or HTTP policies. Policy context can also be passed along in the URL.
+
+Learn more in our documentation for [HTTP Redirect](/cloudflare-one/policies/gateway/http-policies/#redirect) and [Block page redirect](/cloudflare-one/policies/gateway/block-page/#redirect-to-a-block-page).

src/content/docs/cloudflare-one/connections/connect-devices/agentless/dns/dns-over-https.mdx

@@ -269,7 +269,7 @@ curl --silent "https://<ACCOUNT_ID>.cloudflare-gateway.com/dns-query?name=exampl
 --header "CF-Authorization: <USER_DOH_TOKEN>" | jq
 ```
 
-If the site is blocked and you have enabled [**Display block page**](/cloudflare-one/policies/gateway/block-page/#turn-on-the-block-page) for the policy, the query will return `162.159.36.12` (the IP address of the Gateway block page). If the block page is disabled, the response will be `0.0.0.0`.
+If the site is blocked and you have turned on the [block page](/cloudflare-one/policies/gateway/block-page/#configure-policy-block-behavior) for the policy, the query will return `162.159.36.12` (the IP address of the Gateway block page). If the block page is disabled, the response will be `0.0.0.0`.
 
 <Details header="Example response">
 

src/content/docs/cloudflare-one/faq/getting-started-faq.mdx

@@ -36,10 +36,10 @@ After changing your team name, you will need to check your Block page, Login pag
 To verify that your team name change is successfully rendering on the Block page, Login page and App Launcher:
 
 1. In [Zero Trust](https://one.dash.cloudflare.com/), go to **Settings** > **Custom Pages**.
-2. Find the **Block page** and **Login page** > select **Customize** next to the page you would like to review first.
+2. Find the **Account Gateway block page** and **Login page** sections, then select **Customize** next to the page you would like to review first.
 3. Review that the value in **Your Organization's name** matches your new team name.
 4. If the desired name is not already displayed, change the value to your desired team name and select **Save**.
-5. Check both pages (**Block page** and **Login page**) to set **Your Organization's name** as your desired team name.
+5. Check both pages (**Account Gateway block page** and **Login page**) to set **Your Organization's name** as your desired team name.
 
 The App Launcher will display the same team name set on the Login page, so you do not need to update the **Your Organization's name** field in the App Launcher page.
 

src/content/docs/cloudflare-one/policies/gateway/block-page.mdx

@@ -5,47 +5,67 @@ sidebar:
   order: 14
 ---
 
-import { Render } from "~/components";
+import { Render, Tabs, TabItem } from "~/components";
 
-Gateway responds to any domain blocked at the DNS level with `0.0.0.0` for IPv4 queries or `::` for IPv6 queries, and does not return that blocked domain's IP address. As a result, the browser will show a browser default error page, and users will not be able to reach that website. This may cause confusion and lead some users to think that their Internet connection is not working.
+When Gateway blocks traffic with a [DNS](/cloudflare-one/policies/gateway/dns-policies/#block) or [HTTP Block policy](/cloudflare-one/policies/gateway/http-policies/#block), you can configure a block page to display in your users' browsers. You can provide a descriptive reason for blocking traffic and contact information, or you can redirect your users' browsers to another page. You can apply these customizations globally for every Block policy, or override the settings on a per-policy basis.
 
-Configuring a custom block page in Zero Trust helps avoid this confusion. Your block page will display information such as the rule ID of the policy blocking the website, a policy-specific block message, your organization's name, and a global message you may want to show — for example, a message explaining that the website has been blocked by Gateway and providing any points of contact for support within the organization.
+## Prerequisites
 
-Gateway supports custom block pages for DNS and HTTP policies.
+In order to display the block page as the URL of the blocked domain, your organization's devices must have a [Cloudflare certificate](/cloudflare-one/connections/connect-devices/user-side-certificates/manual-deployment/) installed. Enterprise users can also [deploy their own root CA certificate](/cloudflare-one/connections/connect-devices/user-side-certificates/custom-certificate/). If you do not install a certificate, the block page [will not display correctly](#certificate-error).
 
-:::caution[Default Cloudflare certificate expiring]
-The default Cloudflare root certificate expires on 2025-02-02.
+## Configure the block page
 
-If your organization is still using the default Cloudflare certificate, you will need to use a new certificate to display the block page. For more information, refer to [User-side certificates](/cloudflare-one/connections/connect-devices/user-side-certificates/) or [Troubleshooting](/cloudflare-one/faq/troubleshooting/#as-of-february-2-2025-my-end-user-devices-browser-is-returning-a-your-connection-is-not-private-warning).
-:::
+Gateway will display a global block page in the browser of any user whose traffic is blocked. By default, Gateway will display the block page for any DNS Block policies you turn it on for and all HTTP Block policies. You can [turn on or override the global setting](#configure-policy-block-behavior) on a per-policy basis.
 
-## Prerequisites
+To configure the global block page:
 
-In order to display the block page as the URL of the blocked domain, your devices must have a [Cloudflare certificate](/cloudflare-one/connections/connect-devices/user-side-certificates/manual-deployment/) installed. Enterprise users can also [deploy their own root CA certificate](/cloudflare-one/connections/connect-devices/user-side-certificates/custom-certificate/). If you do not install a certificate, the block page [will not display correctly](#certificate-error).
+1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **Custom Pages**.
+2. Under **Account Gateway block page**, Gateway will display the current block page setting. Select **Customize**.
+3. Choose whether to use the [default Gateway block page](#use-the-default-block-page), a [URL redirect](#redirect-to-a-block-page), or a [custom Gateway block page](#customize-the-block-page).
+4. Select **Save**.
 
-## Turn on the block page
+### Use the default block page
 
-For all HTTP Block policies, Gateway automatically displays a generic Cloudflare block page. For DNS Block policies, you will need to turn on the block page on a per-policy basis.
+When you choose **Default Gateway block page**, Gateway will display a [block page hosted by Cloudflare](https://blocked.teams.cloudflare.com/). This is the default option for all traffic blocked by Gateway.
 
-To turn on the block page and specify a custom block message:
+### Redirect to a block page
 
-<Render
-	file="gateway/add-block-page"
-	params={{
-		firewallPolicyPath:
-			"**Gateway** > **Firewall policies** > **DNS** or **Gateway** > **Firewall policies** > **HTTP**",
-	}}
-/>
+Instead of displaying the Cloudflare block page, you can configure Gateway to return a `307` (Temporary Redirect) HTTP response code and redirect to a custom URL.
+
+To redirect users to a non-Cloudflare block page:
+
+1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **Custom Pages**.
+2. Under **Account Gateway block page**, select **Customize**.
+3. Choose **URL redirect**
+4. Enter the URL you want to redirect blocked traffic to.
+5. (Optional) Turn on **Send policy context** to send [additional policy context](#policy-context) to the redirected URL.
+6. Select **Save**.
 
-## Customize the block page
+Gateway will now redirect users to a custom page when user traffic matches a Block policy with the block page configured.
+
+To create an HTTP policy to redirect URLs, refer to the [Redirect action](/cloudflare-one/policies/gateway/http-policies/#redirect).
+
+#### Policy context
+
+<Render file="gateway/policy-context" />
+
+#### Redirect precedence
+
+Paths and queries in the redirect URL take precedence over the original URL. When you turn on **Send policy context**, Gateway will append context to the end of the redirected URL. For example, if the original URL is `example.com/path/to/page?querystring=X&k=1` and the redirect URL is `cloudflare.com/redirect-path?querystring=Y`, Gateway will redirect requests to:
+
+```txt ins="&[email protected]"
+cloudflare.com/redirect-path?querystring=Y&[email protected]
+```
+
+### Customize the block page
 
 <Render file="gateway/customize-block-page" />
 
-### Add a logo image
+#### Add a logo image
 
 <Render file="gateway/add-logo-image" />
 
-### Allow users to email an administrator
+#### Allow users to email an administrator
 
 You can add a Mailto link to your custom block page, which allows users to directly email you about the blocked site. When users select **Contact your Administrator** on your block page, an email template opens with the email address and subject line you configure, as well as the following diagnostic information:
 
@@ -59,6 +79,39 @@ You can add a Mailto link to your custom block page, which allows users to direc
 | Device ID    | The ID of the device that visited the page. This is generated by the WARP client.                                                                                                                                           |
 | Block Reason | Your policy-specific block message.                                                                                                                                                                                         |
 
+## Configure policy block behavior
+
+For DNS Block policies, you will need to turn on the block page for each policy you want to display it. For HTTP Block policies, Gateway automatically displays your global block page setting by default. You can override your global block page setting for both policy types within each policy's settings.
+
+To turn on the block page or override your global block page setting for an individual policy:
+
+<Tabs>
+
+<TabItem label="DNS policy">
+
+<Render
+	file="gateway/add-block-page"
+	params={{
+		firewallPolicyPath: "**Gateway** > **Firewall policies** > **DNS**",
+		blockBehaviorAction: "turn on",
+	}}
+/>
+
+</TabItem>
+<TabItem label="HTTP policy">
+
+<Render
+	file="gateway/add-block-page"
+	params={{
+		firewallPolicyPath: "**Gateway** > **Firewall policies** > **HTTP**",
+		blockBehaviorAction: "go to",
+	}}
+/>
+
+</TabItem>
+
+</Tabs>
+
 ## Limitations
 
 ### Certificate error

src/content/docs/cloudflare-one/policies/gateway/dns-policies/common-policies.mdx

@@ -82,8 +82,8 @@ With the [Request Context Categories](/cloudflare-one/policies/gateway/dns-polic
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
-| Selector                 | Operator | Value   | Action |
-| ------------------------ | -------- | ------- | ------ |
+| Selector                 | Operator | Value     | Action |
+| ------------------------ | -------- | --------- | ------ |
 | Request Context Category | is       | _Present_ | Block  |
 
 </TabItem>
@@ -485,7 +485,7 @@ Enterprise users can pair these policies with an [egress policy](/cloudflare-one
 Optionally, you can use the Domain selector to control the IP version for specific sites.
 
 :::note
-To ensure traffic routes through your preferred IP version, disable **Display block page**.
+To ensure traffic routes through your preferred IP version, turn off **Modify Gateway block behavior**.
 :::
 
 ### Force IPv4

src/content/docs/cloudflare-one/policies/gateway/dns-policies/index.mdx

@@ -140,11 +140,17 @@ Policies with Block actions block DNS queries to reach destinations you specify
 
 #### Custom block page
 
-When choosing the Block action, turn on **Display custom block page** to respond to queries with a block page and to specify the message you want to display to users who go to blocked websites. If the block page is disabled, Gateway will respond to blocked queries with an `A` record of `0.0.0.0` for IPv4 destinations, or with an `AAAA` record of `::` for IPv6 destinations. For more information, refer to the dedicated documentation on [customizing the block page](/cloudflare-one/policies/gateway/block-page/).
+When choosing the Block action, turn on **Modify Gateway block behavior** to respond to queries with a block page to display to users who go to blocked websites. Optionally, you can override your global block page setting with a URL redirect for the specific DNS policy. For more information, refer to [Block page](/cloudflare-one/policies/gateway/block-page/).
+
+If the block page is turned off for a policy, Gateway will respond to queries blocked at the DNS level with an `A` record of `0.0.0.0` for IPv4 destinations, or with an `AAAA` record of `::` for IPv6 destinations. The browser will display its default connection error page.
 
 #### WARP client block notifications
 
-<Render file="gateway/client-notifications-os" product="cloudflare-one" />
+<Render
+	file="gateway/client-notifications"
+	product="cloudflare-one"
+	params={{ toggleName: "**Display block notification for WARP Client**" }}
+/>
 
 ### Override
 

src/content/docs/cloudflare-one/policies/gateway/dns-policies/test-dns-filtering.mdx

@@ -23,7 +23,7 @@ For example, if you created a policy to block `example.com`, you can do the foll
 
 2. Type `dig example.com` (`nslookup example.com` if you are using Windows) and press **Enter**.
 
-3. If the [block page](/cloudflare-one/policies/gateway/block-page/) is disabled for the policy, you should see `REFUSED` in the answer section:
+3. If the [block page](/cloudflare-one/policies/gateway/block-page/) is turned off for the policy, you should see `REFUSED` in the answer section:
 
    ```sh
    dig example.com

src/content/docs/cloudflare-one/policies/gateway/http-policies/antivirus-scanning.mdx

@@ -18,9 +18,18 @@ To turn on AV scanning:
 1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **Network**.
 2. In **Firewall**, turn on **AV inspection**.
 3. Choose whether to scan files for malicious payloads during uploads, downloads, or both. You can also block requests containing [non-scannable files](#non-scannable-files).
+4. (Optional) Turn on **Display AV block notification for WARP Client** to send [block notifications](#warp-client-block-notifications) to users connected to Gateway with the WARP Client when AV inspection blocks a file.
 
 When a request is blocked due to the presence of malware, Gateway will log the match as a Block decision in your [HTTP logs](/cloudflare-one/insights/logs/gateway-logs/#http-logs).
 
+### WARP client block notifications
+
+<Render
+	file="gateway/client-notifications"
+	product="cloudflare-one"
+	params={{ toggleName: "**Display AV block notification for WARP Client**" }}
+/>
+
 ## File scan criteria
 
 If AV scanning is turned on, Gateway will use the following criteria to determine whether a file is present in a request or response, and whether to scan that file. The first match will result in the file being scanned.