Merge pull request #274211 from vhorne/waf-jsc

Start JavaScript challenge content

Author: ttorble

articles/web-application-firewall/afds/waf-front-door-monitor.md

@@ -30,6 +30,24 @@ You can create custom filters based on action types and rule names. Metrics incl
 
 :::image type="content" source="../media/waf-frontdoor-monitor/waf-frontdoor-metrics.png" alt-text="Screenshot that shows the metrics for an Azure Front Door WAF.":::
 
+## JavaScript challenge (preview) metrics
+
+To access your JavaScript challenge WAF metrics:
+
+- Add the Web Application Firewall `JS Challenge Request Count` metric to track the number of requests that match JavaScript challenge WAF rules.
+
+The following filters are provided as part of this metric:
+
+- **PolicyName**: This is the WAF policy name
+- **Rule**: This can be any custom rule or bot rule
+- **Action**: There are four possible values for JS Challenge action
+   - **Issued**:  JS Challenge is invoked the first time
+   - **Passed**: JS Challenge computation succeeded and an answer was received
+   - **Valid**: JS Challenge validity cookie was present
+   - **Blocked**: JS Challenge computation failed
+
+:::image type="content" source="../media/waf-frontdoor-monitor/javascript-challenge-metrics.png" alt-text="Screenshot showing the JavaScript challenge metrics.":::
+
 ## Logs and diagnostics
 
 The Azure Front Door WAF provides detailed reporting on each request and each threat that it detects. Logging is integrated with Azure's diagnostics logs and alerts by using [Azure Monitor logs](../../azure-monitor/insights/azure-networking-analytics.md).
@@ -68,7 +86,7 @@ The following table shows the values logged for each request.
 
 | Property  | Description |
 | ------------- | ------------- |
-| Action |Action taken on the request. Logs include requests with all actions. Actions are:<ul> <li>`Allow` and `allow`: The request was allowed to continue processing.</li> <li>`Block` and `block`: The request matched a WAF rule configured to block the request. Alternatively, the [anomaly scoring](waf-front-door-drs.md#anomaly-scoring-mode) threshold was reached and the request was blocked.</li> <li>`Log` and `log`: The request matched a WAF rule configured to use the `Log` action.</li> <li> `AnomalyScoring` and `logandscore`: The request matched a WAF rule. The rule contributes to the [anomaly score](waf-front-door-drs.md#anomaly-scoring-mode). The request might or might not be blocked depending on other rules that run on the same request.</li> </ul> |
+| Action |Action taken on the request. Logs include requests with all actions. Actions are:<ul> <li>`Allow` and `allow`: The request was allowed to continue processing.</li> <li>`Block` and `block`: The request matched a WAF rule configured to block the request. Alternatively, the [anomaly scoring](waf-front-door-drs.md#anomaly-scoring-mode) threshold was reached and the request was blocked.</li> <li>`Log` and `log`: The request matched a WAF rule configured to use the `Log` action.</li> <li> `AnomalyScoring` and `logandscore`: The request matched a WAF rule. The rule contributes to the [anomaly score](waf-front-door-drs.md#anomaly-scoring-mode). The request might or might not be blocked depending on other rules that run on the same request.</li> <li> `JS Challenge` and `JSChallengeIssued`: Issued due to missing/invalid challenge clearance, missing answer.<br><br>The log is created when a client requests access to a web application for the first time and has not been challenged previously. This client receives the JS challenge  page and proceeds to compute the JS challenge. Upon successful computation, the client is granted the validity cookie.</li> <li>`JS Challenge` and `JSChallengePass`:  Passed due to valid challenge answer.<br><br>This log is created when a client solves the JS challenge and resubmits the request with the correct answer. In this case, Azure WAF validates the cookie and proceeds to process the remaining rules without generating another JS challenge.</li> <li> `JS Challenge` and `JSChallengeValid`: Logged/passthrough due to valid challenge.<br><br>This log is created when a client has previously solved a challenge. In this case, Azure WAF logs the request and proceeds to process the remaining rules.</li><li>`JS Challenge` and `JSChallengeBlock`: Blocked<br><br>This log is created when a JS challenge computation fails.</ul> |
 | ClientIP | The IP address of the client that made the request. If there was an `X-Forwarded-For` header in the request, the client IP address is taken from that header field instead. |
 | ClientPort | The IP port of the client that made the request. |
 | Details | More details on the request, including any threats that were detected. <br />`matchVariableName`: HTTP parameter name of the request matched, for example, header names (up to 100 characters maximum).<br /> `matchVariableValue`: Values that triggered the match (up to 100 characters maximum). |

articles/web-application-firewall/media/waf-frontdoor-monitor/javascript-challenge-metrics.png

@@ -101,6 +101,8 @@ items:
       href: waf-copilot.md
   - name: WAF and Azure Policy
     href: ./shared/waf-azure-policy.md
+  - name: JavaScript challenge
+    href: waf-javascript-challenge.md
 - name: How-to guides
   items:
   - name: Application Gateway

articles/web-application-firewall/media/waf-javascript-challenge/javascript-challenge-page.png

@@ -0,0 +1,45 @@
+---
+title: Azure Web Application Firewall JavaScript challenge (preview) overview
+description: This article is an overview of the Azure Web Application Firewall JavaScript challenge feature.
+services: web-application-firewall
+author: sowmyam2019
+ms.service: web-application-firewall
+ms.date: 05/20/2024
+ms.author: victorh
+ms.topic: concept-article
+
+#customer intent: As a cloud network architect, I want to understand the Azure Web Application Firewall JavaScript challenge feature to determine if I want to deploy it.
+---
+
+# Azure Web Application Firewall JavaScript challenge (preview) overview
+
+> [!IMPORTANT]
+> Azure Web Application Firewall JavaScript challenge is currently in PREVIEW.
+> See the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.
+
+Azure Web Application Firewall (WAF) on Azure Front Door offers a JavaScript challenge feature as one of the mitigation options for advanced bot protection. It's available on the Azure Front Door premium version as an action in the custom rule set and the Bot Manager 1.x ruleset.
+
+The JavaScript challenge is an invisible web challenge used to distinguish between legitimate users and bots. Malicious bots fail the challenge, which protects web applications. In addition, the JavaScript challenge is beneficial as it reduces friction for legitimate users. This is because it doesn't require any human intervention.
+
+## How it works
+
+ When the JS Challenge is active on Azure WAF and a client's HTTP(s) request matches a specific rule, the client is shown a Microsoft JS challenge page. The user sees this page for a few seconds while the user’s browser computes the challenge. The client's browser must successfully compute a JavaScript challenge on this page to receive validation from Azure WAF. When the computation succeeds, WAF validates the request as a nonbot client and runs the rest of the WAF rules. Requests that fail to successfully compute the challenge are blocked.
+
+Here's an example JavaScript challenge page:
+
+:::image type="content" source="media/waf-javascript-challenge/javascript-challenge-page.png" alt-text="Screenshot showing the JavaScript challenge page.":::
+
+## Expiration
+
+The WAF policy setting defines the JavaScript challenge cookie validity lifetime in minutes. The user is challenged after the lifetime expires. The lifetime is an integer between 5 and 1440 and the default is 30 minutes. The JavaScript challenge cookie name is `afd_azwaf_jsclearance`.
+
+> [!NOTE]
+> The JavaScript challenge expiration cookie is injected into the user’s browser after successfully completing the challenge.
+
+## Limitations
+
+- AJAX and API calls aren't supported.
+- If the first call that receives a JavaScript challenge has a POST body size greater than 128 KB, it blocks it. Additionally, challenges for non-HTML resources embedded in a page aren't supported. For example images, css, js, and so on. However, if there's a prior successful JavaScript challenge request, then the previous limitations are removed.
+- The challenge isn't supported on Microsoft Internet Explorer. The challenge is supported on the latest versions of the Microsoft Edge, Chrome, Firefox, and Safari web browsers.
+- Cross-origin resource sharing (CORS) requests result in a challenge loop. If you visit a page that triggers the JavaScript challenge action from a domain that isn't the same as the domain running the JavaScript challenge, you're challenged regardless of prior challenge passes.
+- If one IP address receives the JavaScript challenge and a different IP address solves it, the computation result becomes invalid, potentially causing a challenge loop.