This topic aims to guide you in securely using the ArkWeb component under the Hybrid application development model. Hybrid development involves building dynamically loadable and renderable pages (for example, product promotions and privacy policies) using the Web/HTML5 technology, which are then displayed via the ArkWeb component embedded within the application. Furthermore, you can leverage the JSBridge capability to enable web pages to conveniently access native application features, such as geolocation services, camera, and mobile payment.

While this model enhances development flexibility and web interactivity, it also exposes a significant number of sensitive capabilities to the web side, markedly expanding the attack surface. Additionally, common web vulnerabilities like cross-site scripting (XSS), identity confusion, and plaintext data transmission further undermine the overall security of hybrid applications, increasing the likelihood of high-risk threats such as malicious code injection, privilege abuse, and sensitive information leakage.

Therefore, based on numerous real-world vulnerability cases, this topic provides you with several best practices for secure ArkWeb development, covering secure web resource access, appropriate permission control, and secure transmission of sensitive data, to systematically enhance the overall security posture of applications.

When to Use

This topic applies to applications using the ArkWeb component for hybrid development, including scenarios such as loading dynamic HTML5 pages and invoking native capabilities via JSBridge.

Note: Scenarios requiring access to the full web content, such as pure web browsing or resource search (for example, developing a browser application), are not subject to the guidelines in this topic.

Secure Web Resource Access

Following the best practices below when using ArkWeb for web resource access can enhance the trustworthiness of the web runtime environment and protect critical service operations and data.

Configuring an Allowlist to Restrict Web Content Loaded by the ArkWeb Component

[Description]

Restrict ArkWeb to loading only trusted service web pages, not pages from arbitrary sources. You are advised to use setUrlTrustList() to configure an allowlist for ArkWeb. Once configured, the ArkWeb component will automatically verify the target URL before loading or navigating to a page. Only URLs matching the allowlist will be permitted; others will be automatically blocked, with a warning page displayed.

[Risk]

Attackers may attempt to load malicious URLs into the application's ArkWeb component. The specific impact varies depending on the ArkWeb's usage context but can lead to severe consequences such as account hijacking, privacy leakage, or arbitrary code execution.

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  urlTrustList: string =
    '{\'UrlPermissionList\':[{\'scheme\':\'https\', \'host\':\'trust.example.com\', \'port\':80, \'path\':\'test\'}]}'

  build() {
    Column() {
      Button('Setting the trustList')
        .onClick(() => {
          try {
            // Set up an allowlist to allow access only to trusted web pages.
            this.controller.setUrlTrustList(this.urlTrustList);
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
      Button('Access the trust web')
        .onClick(() => {
          try {
            // Allowlist activated, access to trusted web pages is permitted.
            this.controller.loadUrl('https://trust.example.com/test');
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
      Button('Access the untrusted web')
        .onClick(() => {
          try {
            // Allowlist activated, blocking access to untrusted web and displaying an alarm page.
            this.controller.loadUrl('http://untrust.example.com/test');
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
    }
  }
}
SetURLTrustList.ets

Avoiding Configuring Untrusted Domains to the Allowlist

[Description]

Avoid adding domains not exclusively owned by the service, such as public CDN domains (for example, cdn.example.com), to the allowlist.

[Risk]

Attackers may bypass the allowlist and load malicious URLs.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  webviewController: webview.WebviewController = new webview.WebviewController();
  urlTrustList: string = '{\'UrlPermissionList\':'
    + '[{\'scheme\':\'https\', \'host\':\'cdnjs.cloudflare.com\'},' // Public CDN domains are untrusted.
    + '{\'scheme\':\'https\', \'host\':\'cdn.ampproject.org\'}]}' // Public service domains are at risk of being abused.
  urlStr: string = '' // Any URL to be loaded.

  build() {
    Column() {
      Web({ src: this.urlStr, controller: this.webviewController })
        .javaScriptAccess(true)
        .onControllerAttached(() => {
          try {
            this.webviewController.setUrlTrustList(this.urlTrustList);
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
    }
  }
}
SetURLTrustList.ets

Always Validating or Filtering Untrusted Content When Loading Scripts or Resources from External Sources

[Description]

WebviewController provides the loadData() method for loading resources, and the runJavaScript() and runJavaScriptExt() methods for executing scripts, which return execution results via callbacks.

If the JavaScript scripts or resources to be loaded originate from external, controllable, and untrusted sources (for example, passed via Want), their content must be inspected and filtered prior to loading.

[Risk]

Loading untrusted resources or scripts can lead to malicious code injection, resulting in XSS attacks. Additionally, if the ArkWeb component has registered sensitive JavaScriptProxy APIs, these APIs could be maliciously invoked, compromising the security of the Hybrid application.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
Web({ src: $rawfile('index.html'), controller: this.controller })
  .javaScriptAccess(true)
  .onPageEnd(error => {
    try {
      let jsMethod: string = 'alert("xss")' // External controlled string
      this.controller.runJavaScript(jsMethod)
        .then((result) => {
          hilog.info(0x0000, 'ArkWebSecurity', 'result: ' + result);
        })
        .catch((error: BusinessError) => {
          hilog.error(0x0000, 'ArkWebSecurity', 'error: ' + error);
        })
      if (error) {
        hilog.error(0x0000, 'ArkWebSecurity', 'url: ', error.url);
      }
    } catch (error) {
      hilog.error(0x0000, 'ArkWebSecurity', `ErrorCode: ${error.code}, Message: ${error.message}`);
    }
  })
LoadURL.ets

The index.html file contains the following content:

Collapse
Word wrap
Dark theme
Copy code
<html>
<meta charset="UTF-8">
<body>
Hello world!
</body>
<script type="text/javascript">
    function test() {
        console.log('Ark WebComponent')
        return "This value is from index.html"
    }
</script>
</html>
index.html

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
Web({ src: $rawfile('index.html'), controller: this.controller })
  .javaScriptAccess(true)
  .onPageEnd(event => {
    try {
      let whiteMethods = ['test()']
      let jsMethod: string = 'alert("xss")' // External controlled string
      if (whiteMethods.indexOf(jsMethod) === -1) {
        hilog.error(0x0000, 'ArkWebSecurity', 'input method not in whiteList')
        return;
      }
      this.controller.runJavaScript(jsMethod)
        .then((result) => {
          hilog.info(0x0000, 'ArkWebSecurity', 'result: ' + result);
        })
        .catch((error: BusinessError) => {
          hilog.error(0x0000, 'ArkWebSecurity', 'error: ' + error);
        })
      if (event) {
        hilog.info(0x0000, 'ArkWebSecurity', 'url: ', event.url);
      }
    } catch (error) {
      let e: BusinessError = error;
      hilog.error(0x0000, 'ArkWebSecurity', `ErrorCode: ${e.code}, Message: ${e.message}`);
    }
  })
LoadURL.ets

Always Validating File URLs When Loading Local Files in onInterceptRequest to Prevent Local Data Theft

[Description]

The onInterceptRequest() method can intercept URL resource access, allowing customization of the response status and content. If the application needs to open a local file via getRequestUrl(), the URL must be checked for path traversal sequences (../) to prevent path traversal attacks.

[Risk]

Path traversal occurs when an attacker can use path traversal sequences to access files in directories they should not be able to read. This could lead to theft of sensitive files within the application or even severe consequences like remote code execution.

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { fileIo } from '@kit.CoreFileKit';
import { util } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  responseWeb: WebResourceResponse = new WebResourceResponse();
  heads: Header[] = [];

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
      // Intercept URL resource access through onInterceptRequest and customize the response message.
        .onInterceptRequest((event) => {
          // The URL passed by event.request.getRequestUrl() should be restricted to a specific path,
          // and the presence of '../' should be checked.
          if (event.request.getRequestUrl().startsWith('file:///data/trusted_path') &&
            event.request.getRequestUrl().includes('../') !== true) {
            try {
              let file =
                fileIo.openSync(event.request.getRequestUrl(), fileIo.OpenMode.READ_ONLY | fileIo.OpenMode.CREATE);
              let arrayBuffer: ArrayBuffer = new ArrayBuffer(6);
              fileIo.readSync(file.fd, arrayBuffer, { offset: 0, length: arrayBuffer.byteLength });
              fileIo.closeSync(file);
              let decoder = util.TextDecoder.create('utf-8');
              let stringData = decoder.decodeToString(new Uint8Array(arrayBuffer));
              let head1: Header = {
                headerKey: 'Connection',
                headerValue: 'keep-alive'
              }
              let head2: Header = {
                headerKey: 'Cache-Control',
                headerValue: 'no-cache'
              }
              this.heads.push(head1);
              this.heads.push(head2);

              const promise: Promise<String> = new Promise((resolve: Function) => {
                this.responseWeb.setResponseHeader(this.heads);
                // After the file is read, it will be encapsulated and the response will be called back to the web page.
                this.responseWeb.setResponseData(stringData);
                this.responseWeb.setResponseEncoding('utf-8');
                this.responseWeb.setResponseMimeType('text/html');
                this.responseWeb.setResponseCode(200);
                this.responseWeb.setReasonMessage('OK');
                resolve('success');
              })
              promise.then(() => {
                hilog.info(0x0000, 'ArkWebSecurity', 'prepare response ready');
                this.responseWeb.setResponseIsReady(true);
              })
              this.responseWeb.setResponseIsReady(false);
            } catch (error) {
              hilog.error(0x0000, 'ArkWebSecurity', `ErrorCode: ${error.code}, Message: ${error.message}`);
            }
          }
          return this.responseWeb;
        })
    }
  }
}
OnInterceptRequest.ets

Avoiding Storing Sensitive Resources in Local File Directories Allowed for Cross-Origin Access

[Description]

By default, ArkWeb does not allow cross-origin access to local file resources unless setPathAllowingUniversalAccess() is used to specify the local directories allowed for cross-origin access. In such cases, minimize the scope of accessible directories and ensure that they do not contain sensitive resources such as user data, cookies, or tokens.

Note: HarmonyOS only allows setting cross-origin access for specific directories like the application files directory (Context.filesDir) and the application resource directory (Context.resourceDir). If the specified path list does not meet requirements, the setting will fail.

[Risk]

Configuring directories for cross-origin access may allow attackers to access local files, leading to sensitive resource leakage and application cloning attacks.

Avoiding Mixed HTTP and HTTPS Content Loading

[Description]

The mixedMode() setting controls whether loading mixed HTTP and HTTPS content is allowed. ArkWeb defaults to disallowing mixed content (mixedMode is set to None by default). Avoid setting it to All. If accessing HTTP is necessary during debugging, mixedMode must be reset to None after debugging.

[Risk]

Allowing ArkWeb to load mixed HTTP and HTTPS content introduces the risk of man-in-the-middle (MitM) attacks.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
Web({ src: 'www.huawei.com', controller: this.controller })
  .mixedMode(MixedMode.All)
MixedMode.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
Web({ src: 'www.huawei.com', controller: this.controller })
  .mixedMode(MixedMode.None)
MixedMode.ets

Avoiding Continuing Page Load When the SSL Verification Fails

[Description]

When an SSL verification error occurs for a web resource being loaded (for example, certificate or protocol verification error for the target website), the ArkWeb component notifies the application via onSslErrorEvent(). By default, ArkWeb cancels loading the resource causing the error. If the service scenario requires proceeding, you must perform explicit validation or provide a clear explanation before calling confirm. You are advised to use onSslErrorEvent to capture all resource errors, rather than onSslErrorEventReceive().

[Risk]

Ignoring SSL errors and continuing to load resources can easily lead to risks such as MitM attacks.

Exception: Applications used to load URLs, such as browsers, can be excluded. However, users must be explicitly notified of security risks on the page to be loaded.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onSslErrorEvent((event: SslErrorEvent) => {
          console.log('ssl check failed, error is: ' + event.error.toString());
          event.handler.handleConfirm();
        })
    }
  }
}
OnSslErrorEventReceive.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .onSslErrorEvent((event: SslErrorEvent) => {
          hilog.info(0x0000, 'ArkWebSecurity', 'onSslErrorEvent url: ' + event.url);
          hilog.info(0x0000, 'ArkWebSecurity', 'onSslErrorEvent error: ' + event.error);
          hilog.info(0x0000, 'ArkWebSecurity', 'onSslErrorEvent originalUrl: ' + event.originalUrl);
          hilog.info(0x0000, 'ArkWebSecurity', 'onSslErrorEvent referrer: ' + event.referrer);
          hilog.info(0x0000, 'ArkWebSecurity', 'onSslErrorEvent isFatalError: ' + event.isFatalError);
          hilog.info(0x0000, 'ArkWebSecurity', 'onSslErrorEvent isMainFrame: ' + event.isMainFrame);
          this.getUIContext().showAlertDialog({
            title: 'onSslErrorEvent',
            message: 'text',
            primaryButton: {
              value: 'Confirm',
              action: () => {
                event.handler.handleConfirm();
              }
            },
            secondaryButton: {
              value: 'cancel',
              action: () => {
                event.handler.handleCancel();
              }
            },
            cancel: () => {
              event.handler.handleCancel();
            }
          })
        })
    }
  }
}
OnSslErrorEventReceive.ets

Ensuring that ArkWeb Web Debugging is Disabled in Official Release Versions

[Description]

setWebDebuggingAccess() can be used to enable web debugging for ArkWeb. By default, debugging is disabled. This feature must remain disabled in official release versions.

[Risk]

Enabling debugging increases the risk of service APIs being maliciously exploited.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
try {
  webview.WebviewController.setWebDebuggingAccess(true);
} catch (error) {
  hilog.error(0x0000, 'ArkWebSecurity', `ErrorCode: ${error.code}`);
}
WebDebug.ets

Appropriate Permission Control

Follow the best practices below to ensure the ArkWeb runtime adheres to the principle of least privilege, granting only the necessary permissions to trusted web pages.

Configuring an Allowlist for Calling Page Identity Verification During JavaScriptProxy API Registration

[Description]

For JavaScriptProxy APIs, especially those accessing sensitive resources, an allowlist must be used to verify the legitimacy of the calling page before invocation, adhering to the principle of least privilege. You are advised to configure an invocation allowlist via the permission parameter when registering the JavaScriptProxy API. After configuration, when the web side calls this API, ArkWeb checks the URL of the calling page. Only requests from URLs matching the allowlist are permitted; others are intercepted.

NOTE

Avoid implementing custom allowlist checks using lifecycle functions like onPageBegin(). Uniform control must be exercised through the permission parameter.

[Risk]

Methods registered via the JavaScriptProxy API can be exploited by attackers, enabling threats such as loading malicious content, executing malicious code, or abusing sensitive resources.

For details, see Establishing an Interaction Channel Between the Application Side and the HTML5 Page.

Applying the Least Privilege Principle to JavaScriptProxy API Registration

[Description]

Only register JavaScriptProxy APIs that are strictly necessary for services with web pages. Avoid directly exposing debugging APIs or internal logic APIs to web pages. Additionally, implement access control (for example, an invocation allowlist) to verify the caller's legitimacy.

[Risk]

If exposed APIs involve returning sensitive information or performing sensitive operations, invocation by an attacker could lead to risks like account impersonation attacks or malicious code execution.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

class InsecureObj {
  executeSQL(cmd: string) {
    // Do something dangerous here
    hilog.info(0x0000, 'ArkWebSecurity', 'Execute: ' + cmd);
  }
}

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  testObj = new InsecureObj();

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        .javaScriptProxy({
          object: this.testObj,
          name: 'objName',
          methodList: ['executeSQL'],
          controller: this.controller,
        })
    }
  }
}
JavaScriptProxy.ets

Avoiding Page Loading Within onOverrideUrlLoading

[Description]

When a URL is about to be loaded into the Web component, the hybrid application can receive a notification via onOverrideUrlLoading() to take control of the loading process. onOverrideUrlLoading() is an untrusted lifecycle method; executing any service logic within it is not recommended. Avoid calling loadUrl() to load pages within the onOverrideUrlLoading() implementation.

[Risk]

This operation may not only unexpectedly terminate the current loading flow but also bypass ArkWeb's security model, introducing additional security risks. (Note: onOverrideUrlLoading() is triggered by the page, while loadUrl() is called by the hybrid application. The ArkWeb kernel applies different security checks for these two flows, and thus they must not be mixed).

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: $rawfile('index.html'), controller: this.controller })
        .onOverrideUrlLoading((webResourceRequest: WebResourceRequest) => {
          if (webResourceRequest && webResourceRequest.getRequestUrl() === 'http://www.example.com') {
            try {
              this.controller.loadUrl('www.example.com');
              return true;
            } catch (error) {
              hilog.error(0x0000, 'ArkWebSecurity', `ErrorCode: ${error.code}, Message: ${error.message}`);
            }
          }
          return false;
        })
    }
  }
}
OnOverrideUrlLoading.ets

Avoiding Using getUrl/getOriginalUrl Functions to Obtain URLs for Invocation Allowlist Validation

[Description]

During a JavaScriptProxy call, getUrl() or getOriginalUrl() may retrieve an inaccurate page URL. Using such URLs for validation could lead to erroneous judgments, introducing security risks. You are advised to use the getLastJavascriptProxyCallingFrameUrl() function to obtain the accurate URL of the page that initiated the call.

Note: getLastJavascriptProxyCallingFrameUrl should only be used within JavaScriptProxy. Do not use this function to obtain URLs in other contexts, as it may return incorrect values.

[Risk]

Performing security validation based on an inaccurate page URL renders the validation ineffective, potentially enabling privilege escalation attacks.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
let url: string = this.controller.getUrl();
if (url === 'https://www.huawei.com') {
  hilog.info(0x0000, 'ArkWebSecurity', 'Pass the check');
  // do some native invoke
} else {
  hilog.error(0x0000, 'ArkWebSecurity', 'Not allowed to execute: ' + cmd);
}
GetURL.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
let url: string = this.controller.getLastJavascriptProxyCallingFrameUrl();
if (url === 'https://www.huawei.com') {
  hilog.info(0x0000, 'ArkWebSecurity', 'Pass the check');
  // do some native invoke
} else {
  hilog.error(0x0000, 'ArkWebSecurity', 'Not allowed to execute: ' + cmd);
}
GetURL.ets

Avoiding Providing the Page Loading Functionality Within JavaScriptProxy

[Description]

Avoid calling loadUrl() within JavaScriptProxy to load pages. If the service requires page loading, it should be implemented via HTML navigation.

[Risk]

Improper operations may not only terminate the current page lifecycle unexpectedly but also bypass ArkWeb's security model, introducing additional security risks.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { hilog } from '@kit.PerformanceAnalysisKit';

class TestObj {
  controller: webview.WebviewController

  constructor(webview_controller: webview.WebviewController) {
    this.controller = webview_controller
  }

  goto(uri: string) {
    try {
      this.controller.loadUrl(uri);
    } catch (error) {
      hilog.error(0x0000, 'ArkWebSecurity', `ErrorCode: ${error.code}, Message: ${error.message}`);
    }
  }
}

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  testObj = new TestObj(this.controller);

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        .javaScriptProxy({
          object: this.testObj,
          name: 'objName',
          methodList: ['goto'],
          controller: this.controller,
        })
    }
  }
}
Redirection.ets

Avoiding Providing the Script Execution Functionality Within JavaScriptProxy

[Description]

Avoid providing code execution functionalities such as runJavaScript() and runJavaScriptExt() within JavaScriptProxy.

[Risk]

Since JavaScriptProxy is registered on the Web component, JavaScript scripts executed via it can affect all pages running within that component. This capability allows attackers to execute code on the parent page using a controlled subpage, resulting in cross-origin code execution.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

class TestObj {
  controller: webview.WebviewController

  constructor(webview_controller: webview.WebviewController) {
    this.controller = webview_controller
  }

  eval(uri: string) {
    this.controller.runJavaScript(uri, (error) => {
      if (error) {
        hilog.error(0x0000, 'ArkWebSecurity',
          `run JavaScript error, ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
        return;
      }
    });
    return 'AceString';
  }
}

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  testObj: TestObj = new TestObj(this.controller);

  build() {
    Column() {
      Web({ src: 'www.example.com', controller: this.controller })
        .javaScriptAccess(true)
        .javaScriptProxy({
          object: this.testObj,
          name: 'objName',
          methodList: ['eval'],
          controller: this.controller,
        })
    }
  }
}
RunJavaScript.ets

Explicitly Notifying the User for Authorization in onPermissionRequest

[Description]

Web pages can access device cameras/microphones via the standard getUserMedia() API. The ArkWeb component triggers the onPermissionRequest() function to manage authorization for the current web page. An explicit dialog (for example, using AlertDialog) should be created to obtain user authorization. Avoid directly granting page permissions. By default, the ArkWeb component denies permission requests.

[Risk]

Unauthorized access may lead to privacy leakage and compliance violations.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { abilityAccessCtrl, common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear(): void {
    let atManager = abilityAccessCtrl.createAtManager();
    let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA', 'ohos.permission.MICROPHONE'])
      .then((data) => {
        hilog.info(0x0000, 'ArkWebSecurity', 'data: ' + JSON.stringify(data));
        hilog.info(0x0000, 'ArkWebSecurity', 'data permission: ' + data.permissions);
        hilog.info(0x0000, 'ArkWebSecurity', 'data authResults: ' + data.authResults);
      }).catch((error: BusinessError) => {
      hilog.error(0x0000, 'ArkWebSecurity',
        `Failed to request permissions from user. Code is ${error.code}, message is ${error.message}`);
    })
  }

  build() {
    Column() {
      Web({ src: 'https://example.com/index.html', controller: this.controller })
        .onPermissionRequest((event) => {
          // Directly granting page permissions is a wrong approach.
          event.request.grant(event.request.getAccessibleResource());
        })
    }
  }
}
PermissionRequest.ets

The index.html file contains the following content:

Collapse
Word wrap
Dark theme
Copy code
<html>
<head>
    <meta charset="UTF-8">
</head>
<body>
<video id="video" width="500px" height="500px" autoplay="autoplay"></video>
<canvas id="canvas" width="500px" height="500px"></canvas>
<br>
<input type="button" title="HTML5 Camera" value="Open Camera" onclick="getMedia()">
<script>
    function getMedia() {
        let constraints = {
            video: {width: 500, height: 500},
            audio: true
        };
        // Get video
        let video = document.getElementById("video");
        // Return Promise object
        let promise = navigator.mediaDevices.getUserMedia(constraints);
        // then() sync, invoke MediaStream as param
        promise.then(function (MediaStream) {
            video.srcObject = MediaStream;
            video.play();
        });
    }
</script>
</body>
</html>
index.html

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { abilityAccessCtrl, common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear(): void {
    let atManager = abilityAccessCtrl.createAtManager();
    let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    atManager.requestPermissionsFromUser(context, ['ohos.permission.CAMERA', 'ohos.permission.MICROPHONE'])
      .then((data) => {
        hilog.info(0x0000, 'ArkWebSecurity', 'data: ' + JSON.stringify(data));
        hilog.info(0x0000, 'ArkWebSecurity', 'data permission: ' + data.permissions);
        hilog.info(0x0000, 'ArkWebSecurity', 'data authResults: ' + data.authResults);
      }).catch((error: BusinessError) => {
        hilog.error(0x0000, 'ArkWebSecurity',
        `Failed to request permissions from user. Code is ${error.code}, message is ${error.message}`);
    })
  }

  build() {
    Column() {
      Web({ src: 'https://example.com/index.html', controller: this.controller })
        .onPermissionRequest((event) => {
          if (event) {
            this.getUIContext().showAlertDialog({
              title: 'title',
              message: 'text',
              primaryButton: {
                value: 'deny',
                action: () => {
                  event.request.deny();
                }
              },
              secondaryButton: {
                value: 'onConfirm',
                action: () => {
                  // Explicit pop-ups that ask user for authorization, e.g., using AlertDialog, is the correct approach.
                  event.request.grant(event.request.getAccessibleResource());
                }
              },
              cancel: () => {
                event.request.deny();
              }
            })
          }
        })
    }
  }
}
PermissionRequest.ets

Explicitly Notifying the User for Authorization in onGeolocationShow

[Description]

When a web page requests access to the device's geographical location, an explicit dialog must be initiated within the onGeolocationShow() callback to clearly inform the user and obtain authorization. Since the geolocationAccess property defaults to true, ArkWeb permits web pages to request location access by default. Therefore, you must only return location information after obtaining user confirmation and consent; otherwise, geolocationAccess should be set to false to prohibit web pages from obtaining location data.

[Risk]

Unauthorized access may lead to privacy leakage and compliance violations.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: $rawfile('index.html'), controller: this.controller })
        .geolocationAccess(true)
        .onGeolocationShow((event) => {
          event.geolocation.invoke(event.origin, true, true);
        })
    }
  }
}
GeolocationShow.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();

  build() {
    Column() {
      Web({ src: $rawfile('index.html'), controller: this.controller })
        .geolocationAccess(true)
        .onGeolocationShow((event) => {
          if (event) {
            this.getUIContext().showAlertDialog({
              title: 'title',
              message: 'text',
              confirm: {
                value: 'onConfirm',
                action: () => {
                  event.geolocation.invoke(event.origin, true, true);
                }
              },
              cancel: () => {
                event.geolocation.invoke(event.origin, false, true);
              }
            })
          }
        })
    }
  }
}
GeolocationShow.ets

Avoiding Concatenating and Executing the JavaScript Content Passed from the Web Side Without Validation

[Description]

The application side (ArkTS) may receive data passed from web pages (HTML+JS) through open APIs or lifecycle interception, and then asynchronously execute JavaScript via runJavaScript() or runJavaScriptExt(), returning the execution result. You must apply security filtering to the passed data before executing the asynchronous callback.

[Risk]

Content passed from the web page to the application side (ArkTS) is untrusted. If controlled by an attacker, it could lead to universal cross-site scripting (UXSS) attacks.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
this.controller.runJavaScript(
  // Trusting data_from_H5 passed through web pages will result in the execution of arbitrary JS code,
  // e.g., enclose the alert and execute other JS code through data_from_H5.
  'javascript:alert(' + this.dataFromH5 + ')',
  (error, result) => {
    if (error) {
      hilog.error(0x0000, 'ArkWebSecurity',
        `run JavaScript error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
      return;
    }
    if (result) {
      this.webResult = result;
      hilog.info(0x0000, 'ArkWebSecurity', `The test() return value is: ${result}`);
    }
  });
RunJavaScript2.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  dataFromH5: string = '' // Messages passed from web pages
  @State webResult: string = '';

  build() {
    Column() {
      Text(this.webResult).fontSize(20)
      Web({ src: $rawfile('index.html'), controller: this.controller })
        .javaScriptAccess(true)
        .onPageEnd(event => {
          try {
            // Use regular expressions to match all single and double quotes.
            const regex = /['"\(\)]/g;
            // Use the replace method to replace all matched characters with an empty string.
            let sanitizedStr = this.dataFromH5.replace(regex, '');
            this.controller.runJavaScript(
              // Perform security filtering on the data_from_H5 passed through the web page before calling back.
              'javascript:alert(' + sanitizedStr + ')',
              (error, result) => {
                if (error) {
                  hilog.error(0x0000, 'ArkWebSecurity',
                    `run JavaScript error, ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
                  return;
                }
                if (result) {
                  this.webResult = result;
                  hilog.info(0x0000, 'ArkWebSecurity', `The test() return value is: ${result}`);
                }
              });
            if (event) {
              hilog.info(0x0000, 'ArkWebSecurity', 'url: ', event.url);
            }
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
    }
  }
}
RunJavaScript2.ets

The index.html file contains the following content:

Collapse
Word wrap
Dark theme
Copy code
<html>
<meta charset="UTF-8">
<body>
Hello world!
</body>
<script type="text/javascript">
    function test() {
        console.log('Ark WebComponent')
        return "This value is from index.html"
    }
</script>
</html>
index.html

Ensuring Secure Transmission of Sensitive Data

Follow the best practices below to ensure secure data transfer between the application and web pages, enhancing application security and providing privacy protection for users.

Validating URLs Before Appending Authentication Cookies to Web Pages

[Description]

To synchronize user state for service needs, WebCookieManager can be used to pass cookies to pages of a specified URL.

Before using configCookieSync() to append an authentication cookie, always verify that the target URL matches service expectations. You are advised to perform an additional legitimacy check on the target URL after configuring a loading allowlist with setUrlTrustList().

[Risk]

Directly appending authentication cookies to unvalidated URLs is highly dangerous and may lead to authentication cookie theft.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  unknownUrl: string = ''; // unknownUrl from external source

  build() {
    Column() {
      Button('configCookieSync')
        .onClick(() => {
          try {
            // unknownUrl is not verified.
            webview.WebCookieManager.configCookieSync(this.unknownUrl, 'a=b');
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: this.unknownUrl, controller: this.controller })
    }
  }
}
SetCookies.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct WebComponent {
  controller: webview.WebviewController = new webview.WebviewController();
  unknownUrl: string = ''; // unknownUrl from external source
  urlTrustList: string =
    '{\'UrlPermissionList\':[{\'scheme\':\'http\', \'host\':\'trust.example.com\', \'port\':80, \'path\':\'test\'}]}'

  build() {
    Column() {
      Button('configCookieSync')
        .onClick(() => {
          try {
            // Set up an allowlist to allow access only to trusted web pages.
            this.controller.setUrlTrustList(this.urlTrustList);
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
          try {
            // Perform another validity check on unknown_url to implement more granular control.
            if (this.unknownUrl === 'https://www.example.com') {
              webview.WebCookieManager.configCookieSync(this.unknownUrl, 'a=b');
            }
          } catch (error) {
            hilog.error(0x0000, 'ArkWebSecurity',
              `ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`);
          }
        })
      Web({ src: this.unknownUrl, controller: this.controller })
    }
  }
}
SetCookies.ets

Avoiding Directly Concatenating User Sensitive Information into URLs for Loading

[Description]

Avoid directly concatenating user-sensitive information, such as OAuth tokens, session IDs, or phone numbers, into URLs and accessing/loading them (for example, via loadUrl()).

[Risk]

When the URL is externally controllable, this practice leads to sensitive information leakage.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct WebComponent {
  @State message: string = 'Hello World';
  webviewController: webview.WebviewController = new webview.WebviewController();
  accessToken: string = 'xxxx'; // After the user completes the login operation, the token returned by the server.
  untrustedURL: string = '' // Any URL to be loaded

  build() {
    Column() {
      Web({ src: this.untrustedURL + '?token=' + this.accessToken, controller: this.webviewController })
    }
  }
}
LoadURLWithSensitiveData.ets

Specifying the Authorized Receiver URI When Sending Sensitive Data to a Web Page via postMessage

[Description]

When establishing a connection with a web page using WebMessagePort, ensure that the peer web page is trusted.

[Risk]

Lack of access control may accidentally expose application-side (ArkTS) code to the web page's JavaScript, leading to sensitive resource leakage.

[Non-compliant Example]

Collapse
Word wrap
Dark theme
Copy code
this.ports = this.controller.createWebMessagePorts();
this.controller.postMessage('__init_port__', [this.ports[0]], '*');
this.ports[1].postMessageEvent('Post message event to html');
PostMessage.ets

[Recommended Practice]

Collapse
Word wrap
Dark theme
Copy code
this.ports = this.controller.createWebMessagePorts();
this.controller.postMessage('__init_port__', [this.ports[0]], this.url_in_whitelist);
PostMessage.ets

Usage of Device Identifiers

Send feedback

Was this page helpful?

Send feedback

Reach out to us through the community for any other questions.

Community Q&A Intelligent Assistant