Web 應(yīng)用集成SDK

您必須在應(yīng)用中集成JSSDK，才能配置網(wǎng)頁防爬場景化規(guī)則。本文介紹了如何為Web應(yīng)用集成WAF防護(hù)JSSDK（以下簡稱JSSDK）。

組件

Web JSSDK集成包括JavaScript挑戰(zhàn)、異步接口響應(yīng)兩個組件。

JavaScript挑戰(zhàn)組件

JavaScript挑戰(zhàn)組件是JavaScript挑戰(zhàn)能力的Web集成模塊。當(dāng)在控制臺配置開啟了網(wǎng)頁防爬場景化的JavaScript挑戰(zhàn)能力之后，WAF會對訪問了該配置路徑的流量發(fā)起JavaScript挑戰(zhàn)，若客戶端未通過挑戰(zhàn)，則不會返回真實(shí)頁面，會對拒絕的請求并返回JavaScript挑戰(zhàn)驗(yàn)證頁。

JavaScript挑戰(zhàn)組件會在客戶端頁面的域名下植入cookie，以幫助客戶端完成JavaScript挑戰(zhàn)，站長可以通過自動集成或者手動集成的情況下接入該組件，在自動集成的情況下，WAF會為站點(diǎn)所有頁面在最前方注入該組件，而在手動集成的情況下，客戶需要手動將該組件寫在頁面最前方位置。

在客戶端中，若發(fā)起的頁面請求，WAF會返回一個可以執(zhí)行JavaScript代碼中間頁，并在中間頁中加載并執(zhí)行該組件種下cookie，之后刷新頁面。若客戶端發(fā)起的是異步請求，WAF會在該異步請求所在頁面的最前方注入并執(zhí)行該組件，以種下cookie。 JavaScript挑戰(zhàn)植入的cookie是有有效期的，在頁面集成該組件的情況下，定期刷新這個cookie，以保證cookie在有限期內(nèi)。

異步接口響應(yīng)組件

在防爬場景化配置頁面中，可以配置對指定條件下的接口開啟了動態(tài)簽名功能，以及滑塊驗(yàn)證碼功能，這兩個功能需要通過自動或者手動方式集成異步接口響應(yīng)組件來完成。 異步響應(yīng)組件包含兩個能力，客戶端簽名能力和驗(yàn)證碼彈出能力，自動集成了異步響應(yīng)組件之后，組件將接管Web應(yīng)用的異步請求，在請求發(fā)起與請求響應(yīng)時，完成指定挑戰(zhàn)任務(wù)（動態(tài)簽名挑戰(zhàn)與驗(yàn)證碼挑戰(zhàn)），待客戶端完成挑戰(zhàn)任務(wù)之后，客戶端才會執(zhí)行后續(xù)動作。

異步接口響應(yīng)組件自動集成工作原理：

1、Hook異步API：在自動集成異步接口響應(yīng)組件的情況下，組件會全局重寫XMLHttpRequest（xhr）、Fetch兩個異步請求的Web API，在API接口請求對象上額外封裝一層代碼，通常情況不會影響原始對象的各種特性。

2、動態(tài)簽名注入：對通過XMLHttpRequest、Fetch這兩個Web API發(fā)起的所有異步接口的請求URL中添加一個query參數(shù)作為動態(tài)簽名。

3、驗(yàn)證碼挑戰(zhàn)：當(dāng)異步請求響應(yīng)式，組件會通過Hook先判斷當(dāng)前response是否為WAF發(fā)起的驗(yàn)證碼挑戰(zhàn)標(biāo)識，若response為驗(yàn)證碼挑戰(zhàn)標(biāo)識，頁面會彈出驗(yàn)證碼進(jìn)行驗(yàn)證碼挑戰(zhàn)，待客戶端完成挑戰(zhàn)后，攜帶驗(yàn)證碼Token對請求進(jìn)行重試，若response并非為WAF返回的驗(yàn)證碼挑戰(zhàn)標(biāo)識，組件不會執(zhí)行任何動作，將結(jié)果傳遞給站點(diǎn)本身的JS代碼執(zhí)行。

說明：異步接口響應(yīng)組件Hook功能只會對XMLHttpRequest和fetch發(fā)起的異步請求添加動態(tài)簽名挑戰(zhàn)與驗(yàn)證碼挑戰(zhàn)，對于SSE（Server-Sent Events）、Form表單提交、Image、script標(biāo)簽發(fā)起的請求，不會自動完成異步接口響應(yīng)組件的挑戰(zhàn)。

自動集成異步接口響應(yīng)組件時：

會自動進(jìn)行XMLHttpRequest和fetch的hook，此時hook可能會產(chǎn)生兼容性沖突問題（詳情見下文兼容性說明章節(jié)），若無法處理產(chǎn)生的沖突，則可以選擇使用手動集成的形式，手動集成形式不會對XMLHttpRequest和fetch進(jìn)行hook，站長需要通過異步接口響應(yīng)組件提供的JSAPI，在防護(hù)場景的API接口上手動進(jìn)行動態(tài)簽名注入和驗(yàn)證碼挑戰(zhàn)。

手動集成異步接口響應(yīng)組件時：

• 對于動態(tài)簽名能力，需要確保配置并開啟了動態(tài)簽名場景化保護(hù)的接口一定要攜帶上動態(tài)簽名，否則WAF將會拒絕訪問
• 對于滑塊驗(yàn)證碼能力，需要確保配置并開啟了異常流量處置的場景化保護(hù)接口在被WAF返回驗(yàn)證碼挑戰(zhàn)標(biāo)識之后，若要對接口進(jìn)行重試，必須攜帶上驗(yàn)證碼驗(yàn)證通過之后的token，否則waf會再次返回驗(yàn)證碼挑戰(zhàn)標(biāo)識

部署方式

1、自動集成

可在配置網(wǎng)頁防爬場景化的防護(hù)場景定義時，選擇自動集成，此時網(wǎng)站HTML頁面由WAF接管，WAF會在頁面請求響應(yīng)時，向頁面注入組件script標(biāo)簽，客戶網(wǎng)頁無需進(jìn)行代碼改造即可完成部署，同時享受線上組件的熱更新。

2、手動集成 適合于無法滿足自動集成的場景，或者當(dāng)前站點(diǎn)與組件產(chǎn)生沖突的情況，手動集成必須滿足以下條件

• 所有依賴配置了防護(hù)場景的 API 接口所在的頁面，都必須接入特定組件
• 在頁面使用組件功能之前，必須先完成組件script代碼的注入

JavaScript挑戰(zhàn)組件

<script>window.__noxImd = 1</script>
<script src="https//sec-captcha-waf.cdn.bcebos.com/static/wb/1.0/nox_20241230.js"></script>

異步接口響應(yīng)組件

<script src="https//sec-captcha-waf.cdn.bcebos.com/static/wb/1.0/tox_20241230.js"></script>

如內(nèi)容安全策略csp不允許從sec-captcha-waf.cdn.bcebos.com加載資源，可將組件資源下載至服務(wù)本地進(jìn)行本地化部署

3、JSAPI

在手動集成了異步接口響應(yīng)組件之后，可通過一下JSAPI生成動態(tài)簽名和驗(yàn)證碼挑戰(zhàn)。

動態(tài)簽名生成：

1、通過Tox.getToken獲取動態(tài)簽名，若網(wǎng)絡(luò)波動導(dǎo)致異步接口響應(yīng)組件加載失敗，可以使用錯誤碼 499 作為降級簽名

var toxToken = typeof Tox !== 'undefined' ? Tox.getToken() : '499';

2、將toxToken添加到防護(hù)場景的API接口的URL Query參數(shù)中，query的key為tox_token，value為toxToken，如下

/path/to/request?query1=value1&tox_token={toxToken}

驗(yàn)證碼挑戰(zhàn)：

1、通過 Tox.isCaptchaResponse 先判斷當(dāng)前response是否為WAF發(fā)起的驗(yàn)證碼挑戰(zhàn)標(biāo)識。

// 傳入響應(yīng)狀態(tài)碼status、響應(yīng)類型content-type、響應(yīng)體body

const isWafCaptchaFlag = Tox.isCaptchaResponse(status, contentType, responseBody);

2、然后通過 Tox.getCaptchaToken 發(fā)起驗(yàn)證碼挑戰(zhàn)，并通過回調(diào)獲取驗(yàn)證碼通過之后的token。

// 傳入響應(yīng)體body、回調(diào)函數(shù)callback
Tox.getCaptchaToken(responseBody, function (captchaToken) {
    // 處理captchaToken
});

3. 將captchaToken添加到防護(hù)場景的API接口的URL Query參數(shù)中，query的key為svcp_stk，value為captchaToken，如下：

/path/to/request?query1=value1&svcp_stk={captchaToken}

常見問題

兼容性說明

1.瀏覽器環(huán)境兼容性：兼容IE10內(nèi)核以上各類瀏覽器與客戶端容器。

2.兼容性依賴：客戶端需要支持cookie功能。容器或請求本身不支持cookie，則JavaScript挑戰(zhàn)組件功能會被影響。

3.Hook兼容。

第三方組件沖突：異步接口響應(yīng)組件會對所有異步請求的query中添加參數(shù)，這會與不支持多余query參數(shù)的第三方組件產(chǎn)生沖突

非標(biāo)異步請求沖突：異步接口響應(yīng)組件在添加query參數(shù)過程中，會按照標(biāo)準(zhǔn)對請求的URL進(jìn)行解析并編碼，若服務(wù)器接口解析URL的方式不標(biāo)準(zhǔn)，則會產(chǎn)生沖突

關(guān)于Hook兼容沖突問題，可通過手動接入的形式避免沖突的產(chǎn)生。

組件副作用說明

性能增加

1、自動集成情況下，會在頁面head標(biāo)簽中注入組件script，若網(wǎng)絡(luò)波動導(dǎo)致組件加載過慢，會導(dǎo)致頁面出現(xiàn)白屏。

2、自動集成情況下，異步接口響應(yīng)組件會為頁面接口無差別添加動態(tài)簽名tox_token，這會消耗部分計(jì)算資源