Integrate the Web SDK into web applications - Web Application Firewall

Before you can configure anti-crawler rules for web applications, you must integrate the Web SDK into the web applications. This topic describes how to integrate the Web SDK into web applications. In this topic, the Web SDK is referred to as the SDK.

Component

The SDK includes a web collector and an asynchronous API response component.

Web collector

The web collector integrates the characteristics of client browsers into the overall anti-bot attack and defense system to identify the attacks that cannot be identified by using the characteristics of networks. This helps improve the protection effect.

After the characteristics that are collected by the web collector are obfuscated and encrypted, cookies are implanted into root domain names and sent with requests. This causes less impact on the performance of browsers.

The web collector collects the following information:

Browser information: including the browser type and version, screen resolution, time zone, and timestamp
Specific attack and defense probes: including the probes for common browser-level bot scripts and drivers
User operations: including keyboard, mouse, and touch events
Note
To protect your privacy, the keyboard events include only the points in time when keys are pressed, but not which keys are pressed.

Asynchronous API response component

The asynchronous API response component enables web applications to respond to challenge responses that are sent to APIs by the anti-bot attack and defense system. The challenges include JavaScript validation and CAPTCHA verification. After the asynchronous API response component is used, if Web Application Firewall (WAF) sends a challenge response to an API, the component responds when it detects the challenge.

The asynchronous API response component does not provide security features or perform data collection or reporting.

The following list describes how the asynchronous API response component works:

The component globally rewrites common API request objects, such as xmlHttpRequest(XHR), Fetch, and Form, that are included in the requested page, and encapsulates an additional layer of code for the objects. This does not affect the functionality of the original objects.
The component, instead of the JavaScript code of the requested page, checks whether a response is returned by WAF. WAF can send a challenge response to instruct the client to perform JavaScript validation or CAPTCHA verification.
If the response is returned by the origin server, the component does not perform operations on the response and passes the response to the JavaScript code of the requested page. If the response is returned by WAF, the component parses the response, performs the required calculations by using JavaScript, and then sends the request that contains the JavaScript validation signature to WAF. WAF verifies the JavaScript validation signature and sends the request to the origin server.

Compatibility

Environment compatibility: The SDK is compatible with browsers that use the rendering engine in Internet Explorer 8 or a later version.
Compatibility dependency: Client browsers must support cookies. If client browsers do not support cookies, the web collector cannot work as expected.
Hook compatibility: For some special services, hook-native objects that are used in synchronous API requests conflict with the asynchronous API response component. The objects include XHR, form, and Fetch.

Deployment methods

Automatic integration

You can use automatic integration only if the requests that are submitted to HTML pages pass through WAF. Automatic integration eliminates the need for code modification on HTML pages. The HTML pages can be updated at runtime without the need for a full refresh.

If you select Automatic Integration in the Configure Scenarios step when you create a scenario-specific protection template, the bot management module parses HTML data, inserts the web collector and the asynchronous API response component into Document Object Model (DOM), and then returns the modified response to clients when the module handles responses from HTML pages. For more information, see Configure anti-crawler rules for websites.

Note

If you want to integrate the SDK into compressed HTML pages, automatic integration supports only the content-encoding:gzip compression method. Brotli compression and deflate compression are not supported.

Manual integration

For example, if requests that are sent to HTML pages do not pass through WAF, or the used compression methods are not supported, you cannot use manual integration. To perform manual integration, make sure that the following conditions are met:

The SDK is integrated into the HTML pages on which asynchronous calls are initiated.
The SDK is obtained. To obtain the required scripts, perform the following steps: Go to the Bot Management page. On the Scenario-specific Protection tab, click Create Template. In the Configure Scenarios step, set the Web SDK Integration parameter to Manual Integration. Then, click Obtain SDK.
- If you want to enable Dynamic Token-based Authentication, place the following scripts <script> before other scripts <script> to ensure that the following scripts are loaded first:
```
<script src="//g.alicdn.com/frontend-lib/frontend-lib/2.3.40/jquery_231213.min.js"></script>
<script src="//g.alicdn.com/frontend-lib/frontend-lib/2.3.42/interfaceacting240113.js"></script>
<script src="//aeu.alicdn.com/waf/antidomxss_v702.js"></script>
```
- If you do not want to enable Dynamic Token-based Authentication, place the following scripts <script> before other scripts <script> to ensure that the following scripts are loaded first:
```
<script src="//g.alicdn.com/frontend-lib/frontend-lib/2.3.42/interfaceacting240113.js"></script>
<script src="//aeu.alicdn.com/waf/antidomxss_v702.js"></script>
```

On-premises deployment

This deployment method is suitable only for some cases. For example, Content Security Policy (CSP) does not allow resources to be loaded from alicdn, or all components must be deployed in on-premises environments. We recommend that you do not use this method.

To deploy the SDK in an on-premises environment, you must create two copies of JavaScript resources in the on-premises environment, copy all JavaScript code on Alibaba Cloud CDN (CDN) to the on-premises environment, and then place the preceding copies of JavaScript resources and code prior to other resources. This ensures that the preceding JavaScript resources and code are loaded first.