diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index e391b10cc7..767ab26e3d 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -2356,10 +2356,6 @@ - name: Distribute your app and the WebView2 Runtime href: ./webview2/concepts/distribution.md - - name: Enterprise management of WebView2 Runtimes - href: ./webview2/concepts/enterprise.md - displayName: Manage WebView2 applications # old title - - name: Distribute an app as a single executable file href: ./webview2/how-to/static.md displayName: Statically link the WebView2 loader library, single-file app # old title @@ -2378,9 +2374,6 @@ - name: Develop secure WebView2 apps href: ./webview2/concepts/security.md - - - name: Prevent security tools from blocking WebView2-hosted apps - href: ./webview2/concepts/measures.md # ----------------------------------------------------------------------------- - name: Test and automation for WebView2 apps items: diff --git a/microsoft-edge/webview2/concepts/distribution.md b/microsoft-edge/webview2/concepts/distribution.md index e92a47e46a..ed8367fe03 100644 --- a/microsoft-edge/webview2/concepts/distribution.md +++ b/microsoft-edge/webview2/concepts/distribution.md @@ -19,15 +19,28 @@ When distributing your WebView2 app, make sure that the WebView2 Runtime is pres For introductory information, see [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md). - - -#### Servicing the WebView2 Runtime through Windows Server Update Services (WSUS) - -See [Windows Server Update Services (WSUS)](./enterprise.md#windows-server-update-services-wsus) in _Enterprise management of WebView2 Runtimes_. +**Detailed contents:** +* [Runtime or browser support during development or production](#runtime-or-browser-support-during-development-or-production) + * [Microsoft Edge Stable channel isn't supported for WebView2](#microsoft-edge-stable-channel-isnt-supported-for-webview2) +* [The Evergreen Runtime distribution mode](#the-evergreen-runtime-distribution-mode) + * [Windows 11 devices and Windows 10 devices (details)](#windows-11-devices-and-windows-10-devices-details) + * [Deploying the Evergreen WebView2 Runtime](#deploying-the-evergreen-webview2-runtime) + * [Installing the Runtime as per-machine or per-user](#installing-the-runtime-as-per-machine-or-per-user) + * [Detect if a WebView2 Runtime is already installed](#detect-if-a-webview2-runtime-is-already-installed) + * [Online-only deployment](#online-only-deployment) + * [Offline deployment](#offline-deployment) + * [Handle Evergreen WebView2 Runtime updates](#handle-evergreen-webview2-runtime-updates) + * [Test your app for forward-compatibility](#test-your-app-for-forward-compatibility) + * [Feature-detect when using recent APIs](#feature-detect-when-using-recent-apis) +* [The Fixed Version runtime distribution mode](#the-fixed-version-runtime-distribution-mode) + * [Known issues for Fixed Version](#known-issues-for-fixed-version) +* [Files to ship with the app](#files-to-ship-with-the-app) +* [Servicing the WebView2 Runtime through Windows Server Update Services (WSUS)](#servicing-the-webview2-runtime-through-windows-server-update-services-wsus) +* [See also](#see-also) - -#### Runtime or browser support during development or production + +## Runtime or browser support during development or production During development and testing, a WebView2 app can use either option as the backing web platform: @@ -38,14 +51,14 @@ During development and testing, a WebView2 app can use either option as the back A production release of a WebView2 app can only use the WebView2 Runtime as the backing web platform, not Microsoft Edge. - -###### Microsoft Edge Stable channel isn't supported for WebView2 + +#### Microsoft Edge Stable channel isn't supported for WebView2 WebView2 apps aren't permitted to use the Stable channel of Microsoft Edge as the backing web platform. This restriction prevents a production release of a WebView2 app from taking a dependency on the browser. A WebView2 app cannot take a dependency on the browser during production, for the following reasons: * Microsoft Edge isn't guaranteed to be present on all user devices. Many devices in enterprises and in education are disconnected from Windows Update or aren't managed by Microsoft directly. Such devices might not have Microsoft Edge installed. Requiring the production version of WebView2 apps to use the WebView2 Runtime rather than Microsoft Edge avoids making Microsoft Edge a prerequisite for running a WebView2 app. -* Browsers and apps have different use cases. If a WebView2 app required the presence of Microsoft Edge on the client, that would potentially have unintended side-effects on the WebView2 app. For example, an IT admin can prevent the browser from being updated from a specific version, to keep the browser compatible with an internal website. Requiring the production version of a WebView2 app to use the WebView2 Runtime rather than the browser allows the WebView2 app to stay evergreen even if browser updates are prevented by the clients' admin. +* Browsers and apps have different use cases. If a WebView2 app required the presence of Microsoft Edge on the client, that would potentially have unintended side-effects on the WebView2 app. For example, an IT Admin can prevent the browser from being updated from a specific version, to keep the browser compatible with an internal website. Requiring the production version of a WebView2 app to use the WebView2 Runtime rather than the browser allows the WebView2 app to stay evergreen even if browser updates are prevented by the clients' admin. * As opposed to the browser, the WebView2 Runtime is developed and tested for app scenarios, and in some cases the WebView2 Runtime might include bug fixes that aren't yet available in the browser. @@ -350,6 +363,12 @@ Example managed app folder structure: ``` + +## Servicing the WebView2 Runtime through Windows Server Update Services (WSUS) + +See [Windows Server Update Services (WSUS)](/deployedge/webview2-enterprise#windows-server-update-services-wsus) in _Enterprise management of WebView2_. + + ## See also @@ -359,16 +378,16 @@ Example managed app folder structure: * [Prerelease and Release SDKs for WebView2](./versioning.md) * [Feature-detecting to test whether the installed Runtime supports recently added APIs](./versioning.md#feature-detecting-to-test-whether-the-installed-runtime-supports-recently-added-apis) in _Prerelease and Release SDKs for WebView2_. * [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) -* [Windows Server Update Services (WSUS)](./enterprise.md#windows-server-update-services-wsus) in _Enterprise management of WebView2 Runtimes_. * [Test upcoming APIs and features](../how-to/set-preview-channel.md) * [Prerelease testing using preview channels](../how-to/prerelease-testing.md) * [Self-host by deploying preview channels](../how-to/self-hosting.md) * [Distribute a WebView2 app as a single executable file](../how-to/static.md) - statically linking the WebView2 loader library. -Enterprise docs: +Microsoft Edge Enterprise documentation: * [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) * [Release notes for Microsoft Edge Stable Channel](/deployedge/microsoft-edge-relnote-stable-channel) * [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security) +* [Windows Server Update Services (WSUS)](/deployedge/webview2-enterprise#windows-server-update-services-wsus) in _Enterprise management of WebView2_. developer.microsoft.com: * [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download) - Developers. diff --git a/microsoft-edge/webview2/concepts/enterprise.md b/microsoft-edge/webview2/concepts/enterprise.md deleted file mode 100644 index 4f33d5e009..0000000000 --- a/microsoft-edge/webview2/concepts/enterprise.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Enterprise management of WebView2 Runtimes -description: How IT admins can manage WebView2 applications and the WebView2 Runtime. -author: MSEdgeTeam -ms.author: msedgedevrel -ms.topic: article -ms.service: microsoft-edge -ms.subservice: webview -ms.date: 11/12/2021 ---- -# Enterprise management of WebView2 Runtimes - - -This article discusses how IT admins can manage WebView2 applications and the WebView2 Runtime. A developer can integrate the WebView2 component into their app, and then deploy the self-updating Evergreen WebView2 Runtime (along with the app) onto user devices, to power the latest WebView2 features of the app and get the latest security improvements. - -Feedback from IT admins and developers is welcome, through the [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. - - - -## Group policies for WebView2 - -IT admins can use group policy objects (GPO) to configure policy settings for WebView2. The following policies are relevant to WebView2. - - - -#### Update policies - -[Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) are available for IT admins to manage the installing and updating aspects of the WebView2 Runtime. The Microsoft Edge browser and WebView2 Runtime are updated using the same update mechanism. The policy applies to both Microsoft Edge and the WebView2 Runtime, unless the policy is channel-specific, such as [Update](/deployedge/microsoft-edge-update-policies#update) and [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview). - -To configure update policies for Microsoft Edge (and the WebView2 Runtime), see [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge), in the Microsoft Edge Enterprise documentation. - - - -#### Suppressing WebView2 Runtime updates - -An IT admin can suppress updating of the WebView2 Runtime, if auto-updating needs to be suppressed for a short time. After the time period, updating of the WebView2 Runtime resumes. The [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) policy allows an IT admin to set the time during each day at which to suppress auto-update for both Microsoft Edge and the WebView2 Runtime. This enables an IT admin to configure preferences and proxies once for both the browser and the WebView2 Runtime, to control their network bandwidth and traffic, or for other purposes. - -However, users should not stop updating their WebView2 Runtime; users should not remain on an older version of the WebView2 Runtime. Using older versions of the WebView2 Runtime isn't recommended. Security updates and servicing updates are only available on the latest Stable channel release (Edge Stable) and the latest Beta channel release (Edge Beta). If you use older releases of the Microsoft WebView2 Runtime, you won't receive the latest quality and security updates. - - - -###### Evergreen Runtime is recommended, rather than a fixed version - -Using the Evergreen WebView2 Runtime is recommended, unless business-critical requirements necessitate using a fixed version of the WebView2 Runtime. Using the Evergreen WebView2 Runtime: -* Helps minimize exposure to known vulnerabilities. -* Ensures timely security improvements. -* Ensures that WebView2 benefits from continuous security updates that are delivered through Microsoft Edge releases. - -For details about security fixes in Microsoft Edge (which apply to WebView2 as well), see [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security), in the Microsoft Edge Enterprise documentation. - -See also: -* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) - - - -###### Rapid Response to Chromium vulnerabilities - -To help maintain a secure browsing environment, Microsoft Edge addresses Chromium engine-level vulnerabilities soon after the vulnerabilities are disclosed. - -Security fixes address vulnerabilities such as: - -* **Remote code execution** – Mitigates risks of arbitrary code execution via malicious content. -* **Privilege escalation** – Reduces chances of unauthorized system access. -* **Information disclosure and spoofing** – Protects sensitive data, and helps prevent phishing attacks. - - - -###### Microsoft Edge Lifecycle Policy - -Microsoft WebView2 follows the Modern Lifecycle Policy. - -See: -* [Modern Lifecycle Policy](/lifecycle/policies/modern), in the Modern Lifecycle Policy documentation. -* [Microsoft Edge Lifecycle Policy](/deployedge/microsoft-edge-support-lifecycle), in the Microsoft Edge Enterprise documentation. - - - -#### Browser policies - -[Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) doesn't apply to WebView2 applications. This is by design, because apps and browsers have different use cases, and IT admins might not be aware of what applications use WebView2. - -Applying browser policies on WebView2 would have unintended consequences. For example, IT admins can block JavaScript in the browser, and that would break WebView2 apps that use JavaScript. To prevent that, browser policies are separate from WebView2 policies. - - - -#### WebView2-specific policies - -[Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) are available to for you to manage WebView2 directly. However, we recommend that WebView2 app developers implement their own group policies to manage the use of WebView2, because it's easier for administrators to manage the app instead of managing WebView2 directly. - - - -## Windows Server Update Services (WSUS) - -Windows Server Update Services (WSUS) enables IT admins to deploy the latest Microsoft product updates. You can use WSUS to fully manage the distribution of updates of WebView2 that are released through Microsoft Update to computers on your network. - -See [Windows Server Update Services (WSUS) overview](/windows-server/administration/windows-server-update-services/get-started/windows-server-update-services-wsus). - -The recommended way of receiving WebView2 updates is by using the default Microsoft Edge updater. Any modification of update and servicing paths should be done with caution. - - - -#### WebView2 deployment and update using Configuration Manager - - -In Configuration Manager, WebView2 options exist under the **Microsoft Edge Management** node. - -See [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update-microsoft-edge) in _Microsoft Edge Management_, in the App management documentation. - - - -## See also - - -* [Distribute your app and the WebView2 Runtime](./distribution.md) - Evergreen vs. fixed version of the WebView2 Runtime. - - -Microsoft Edge Enterprise documentation: -* [Microsoft Edge Lifecycle Policy](/deployedge/microsoft-edge-support-lifecycle) -* [Microsoft Edge release schedule](/deployedge/microsoft-edge-release-schedule) -* [Release notes for Microsoft Edge Security Updates](/deployedge/microsoft-edge-relnotes-security) -* [Configure Microsoft Edge policy settings on Windows devices](/deployedge/configure-microsoft-edge) -* [Microsoft Edge - Policies](/deployedge/microsoft-edge-policies) -* [Microsoft Edge - Update policies](/deployedge/microsoft-edge-update-policies) - * [Update](/deployedge/microsoft-edge-update-policies#update) - * [UpdatesSuppressed](/deployedge/microsoft-edge-update-policies#updatessuppressed) - * [Update (WebView)](/deployedge/microsoft-edge-update-policies#update-webview) -* [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies) - -Modern Lifecycle Policy documentation: -* [Modern Lifecycle Policy](/lifecycle/policies/modern) - -App management documentation: -* [Update Microsoft Edge](/intune/configmgr/apps/deploy-use/deploy-edge#update-microsoft-edge) in _Microsoft Edge Management_. - -Windows Server Management documentation: -* [Windows Server Update Services (WSUS) overview](/windows-server/administration/windows-server-update-services/get-started/windows-server-update-services-wsus) - -GitHub: -* [WebView2Feedback](https://github.com/MicrosoftEdge/WebViewFeedback) repo. diff --git a/microsoft-edge/webview2/concepts/measures.md b/microsoft-edge/webview2/concepts/measures.md deleted file mode 100644 index aa0523b020..0000000000 --- a/microsoft-edge/webview2/concepts/measures.md +++ /dev/null @@ -1,698 +0,0 @@ ---- -title: Prevent security tools from blocking WebView2-hosted apps -description: Prevent antivirus, Endpoint Detection and Response (EDR), or Data Loss Prevention (DLP) tools from blocking or crashing WebView2-hosted apps. -author: MSEdgeTeam -ms.author: msedgedevrel -ms.topic: article -ms.service: microsoft-edge -ms.subservice: webview -ms.date: 02/26/2026 ---- -# Prevent security tools from blocking WebView2-hosted apps - - -These are best practices for IT administrators and security software vendors, to ensure that security tools are not blocking WebView2 App functionality or crashing WebView2-hosted apps. - -IT administrators and security software vendors should use the practices and procedures below to configure their environments and security tools to avoid breaking WebView2's multi-process architecture. - -**Detailed contents:** -* [Security tools to configure](#security-tools-to-configure) - * [Symptoms of Enterprise configuration problems](#symptoms-of-enterprise-configuration-problems) -* [Update Enterprise security policies if needed](#update-enterprise-security-policies-if-needed) -* [Allowlist the WebView2 Runtime and app's host executables](#allowlist-the-webview2-runtime-and-apps-host-executables) - * [Runtime initialization is blocked](#runtime-initialization-is-blocked) - * [Symptoms](#symptoms) - * [Solutions](#solutions) -* [Preserve default Access Control Lists (ACLs) on Runtime folders](#preserve-default-access-control-lists-acls-on-runtime-folders) -* [Preserve Low Integrity Level (LowIL) on Runtime folders](#preserve-low-integrity-level-lowil-on-runtime-folders) -* [Preserve default Access Control Lists (ACLs) on the app's user data folder (UDF)](#preserve-default-access-control-lists-acls-on-the-apps-user-data-folder-udf) -* [Grant permission to write to the user data folder (UDF)](#grant-permission-to-write-to-the-user-data-folder-udf) - * [Sign-in loop; state not persisted; settings don't persist; blank initial page](#sign-in-loop-state-not-persisted-settings-dont-persist-blank-initial-page) - * [Solutions](#solutions-1) -* [Allow Runtime folder access, child processes, and child process creation](#allow-runtime-folder-access-child-processes-and-child-process-creation) -* [Don't inject DLLs into WebView2 processes](#dont-inject-dlls-into-webview2-processes) - * [Crashes or freezing](#crashes-or-freezing) - * [Content never loads](#content-never-loads) - * [Solutions](#solutions-2) -* [Avoid broad, global exclusions](#avoid-broad-global-exclusions) - * [Slow startup](#slow-startup) - * [Solutions](#solutions-3) -* [Trust internal proxy Certificate Authorities (CAs), and allow essential sign-in or Content Delivery Network (CDN) endpoints](#trust-internal-proxy-certificate-authorities-cas-and-allow-essential-sign-in-or-content-delivery-network-cdn-endpoints) -* [Trust the WebView2 Runtime by signature](#trust-the-webview2-runtime-by-signature) -* [Don't modify WebView2 Runtime files that Windows components load from C:\Windows\System32](#dont-modify-webview2-runtime-files-that-windows-components-load-from-cwindowssystem32) -* [Align Transport Layer Security (TLS) inspection and proxy configuration](#align-transport-layer-security-tls-inspection-and-proxy-configuration) - * [SSL decryption by a firewall or proxy](#ssl-decryption-by-a-firewall-or-proxy) - * [ERR_CERT_* error](#err_cert_-error) - * [Solutions](#solutions-4) -* [Allow updates of the Evergreen WebView2 Runtime](#allow-updates-of-the-evergreen-webview2-runtime) - * [App only works with higher privilege](#app-only-works-with-higher-privilege) - * [Solutions](#solutions-5) -* [Don't apply Edge browser–only group policies](#dont-apply-edge-browseronly-group-policies) -* [Tools in which to check for the symptoms and causes](#tools-in-which-to-check-for-the-symptoms-and-causes) - * [Task Manager](#task-manager) - * [Blank or white embedded window](#blank-or-white-embedded-window) - * [Event Viewer](#event-viewer) - * [Security logs](#security-logs) - * [Diagnostics, crash reports, and process events](#diagnostics-crash-reports-and-process-events) - * [Reliability Monitor](#reliability-monitor) -* [Applicability to tools](#applicability-to-tools) -* [Resolving performance issues](#resolving-performance-issues) -* [Why WebView2 appears in enterprise workloads](#why-webview2-appears-in-enterprise-workloads) -* [See also](#see-also) - - - -## Security tools to configure - -Security tools to configure appropriately include: - -* Antivirus (AV) tools. -* Data Loss Prevention (DLP) tools. -* Endpoint Detection and Response (EDR) tools. - -Enterprise security tools also include: - -* Transport Layer Security (TLS) inspection. - - - -#### Symptoms of Enterprise configuration problems - -Enterprise security tools, if not following the best practices below, can disrupt WebView2's multi-process architecture by: - -* Blocking child processes. -* Tightening folder Access Control Lists (ACLs). -* Injecting dynamic-link libraries (DLLs). - -When such disruption occurs, WebView2-hosted experiences might blank-screen, freeze, or fail to initialize. - -See: -* [Process model for WebView2 apps](./process-model.md) - - - -## Update Enterprise security policies if needed - -WebView2 honors all Enterprise security policies. - -If any tools or policies don't allow some of the WebView2 DLLs to load, the Enterprise IT administrator needs to update the Enterprise security policies. - -WebView2 doesn't implement app-specific logic. - - - -## Allowlist the WebView2 Runtime and app's host executables - -Allowlist the WebView2 Runtime (`msedgewebview2.exe`) and the app's host executables. - -See: -* [Prevent antivirus and DLP tools from blocking or crashing Microsoft Teams](/troubleshoot/microsoftteams/teams-administration/include-exclude-teams-from-antivirus-dlp) - in Microsoft Teams troubleshooting. - -Prefer publisher rules. - -See: -* [Understanding the publisher rule condition in AppLocker](/windows/security/application-security/application-control/app-control-for-business/applocker/understanding-the-publisher-rule-condition-in-applocker) - in Windows Security (Application Control for Windows). - - - -#### Runtime initialization is blocked - -Issues: - -* There might be an initialization error, such as `E_FAIL`. In this case, the WebView2 control fails to initialize, and the app content never loads. - -* Runtime initialization is blocked, for any of the following tools: - - * Windows Defender Application Control (WDAC). - - * AppLocker deny rules; policies that explicitly block execution. - - * Access Control Lists (ACLs) that have been tightened beyond the default settings; permissions that have been made more restrictive than the OS defaults. - - - -###### Symptoms - -* Transport Layer Security (TLS) errors, such as `ERR_CERT_*`. - -* Login redirect failures that occur when Transport Layer Security (TLS) inspection is enabled. - -* An immediate initialization error. - -* There are no child processes. - -* The view is blank. - - - -###### Solutions - -Allowlist the WebView2 Runtime (`msedgewebview2.exe`) and host executables. - -See: -* [Prevent antivirus and DLP tools from blocking or crashing Microsoft Teams](/troubleshoot/microsoftteams/teams-administration/include-exclude-teams-from-antivirus-dlp) - in Microsoft Teams troubleshooting. - -Use publisher rules. - -See: -* [Understanding the publisher rule condition in AppLocker](/windows/security/application-security/application-control/app-control-for-business/applocker/understanding-the-publisher-rule-condition-in-applocker) - in Windows Security (Application Control for Windows). - -Restore default Access Control Lists (ACLs). - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) - - - -## Preserve default Access Control Lists (ACLs) on Runtime folders - -Don't modify the default Access Control Lists (ACLs) that Windows sets on the WebView2 Runtime folders. - -If security tools modify the ACLs on WebView2 Runtime folders, these sandboxed processes might lose the permissions they need to read and execute the Runtime binaries, which can cause blank screens, initialization failures, or crashes. - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) - - - -## Preserve Low Integrity Level (LowIL) on Runtime folders - -Don't modify the Low Integrity Level (LowIL) settings on WebView2 Runtime folders. WebView2 runs renderer processes at a Low Integrity Level, to limit their access to system resources. - -A Low Integrity Level process (LowIL) must be able to Read and Execute the WebView2 Runtime binaries. - -_Low Integrity Level (LowIL)_ is a Windows security mechanism that restricts a process's ability to write to higher-integrity objects (such as most user-profile and system locations). WebView2 renderer processes run at Low IL to reduce the impact of a compromised process. - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) - - - -## Preserve default Access Control Lists (ACLs) on the app's user data folder (UDF) - -Don't modify the default Access Control Lists (ACLs) that Windows sets on the app's user data folder (UDF). Modifying these ACLs can prevent LowIL and AppContainer processes from functioning correctly. - -`AppContainer` is a more restrictive Windows sandbox that limits a process's access to only explicitly granted resources. On supported OS versions, WebView2 might run renderer processes inside an `AppContainer`, for additional isolation. - -The `LowIL/AppContainer` must have the permission to: - -* Read and execute the WebView2 Runtime. - -* Write to the user data folder (UDF). - -WebView2 runs certain child processes at a Low Integrity Level (`LowIL`) or inside an `AppContainer` sandbox to limit their access to system resources. - -These sandboxed processes must still be able to: - -* Read and execute the WebView2 Runtime binaries. - -* Write to the app's user data folder (UDF). - -If security tools tighten the Access Control Lists (ACLs) on the app's user data folder (UDF), sandboxed processes might lose the access they need, which can cause blank screens, initialization failures, or crashes. - -System locations that are managed by the operating system (OS) are handled entirely by Windows, and must not be modified. - -See: -* [Manage user data folders](./user-data-folder.md) - - - -## Grant permission to write to the user data folder (UDF) - -Give write permission to allow the WebView2 app to write to the user data folder (UDF). - -These writes to the UDF can be from: - -* Per-app Controlled Folder Access (CFA) exceptions. - -* Per-app Data Loss Prevention (DLP) exceptions. - -Web content state lives in the app's user data folder (UDF). Web content state includes: -* Cookies. -* Cache. -* Local storage. - -See: -* [Manage user data folders](./user-data-folder.md) - - - -#### Sign-in loop; state not persisted; settings don't persist; blank initial page - -In the case of a sign-in loop, state is not persisted when user data folder (UDF) writes are blocked. - - - -###### Solutions - -Allow writes to the app's user data folder; use per-app Controlled Folder Access (CFA) exceptions or Data Loss Prevention (DLP) exceptions. - -Avoid placing the WebView2 user data folder (UDF) on a network share. - -Ensure that Data Loss Prevention (DLP) policies do not misclassify normal browser data (such as cookies, cache, or local storage) as exfiltration attempts. _Exfiltration_ is the unauthorized transfer of data from a system, network, or cloud environment to an external destination without permission. - -See: -* [Manage user data folders](./user-data-folder.md) - - - -## Allow Runtime folder access, child processes, and child process creation - -Audience: Security software vendors. - -Keep WebView2 Runtime folder access unrestricted. - -Permit child processes and don't terminate them. The child processes include: - -* Renderer -* Graphics Processing Unit (GPU) -* Network -* Crashpad - -Keep WebView2 Runtime child process creation unrestricted; permit Crashpad. - -See: -* [Handling process-related events in WebView2](./process-related-events.md) -* [Crash Dumps](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/diagnostics/crash.md) - WebView2Feedback repo. - - - -## Don't inject DLLs into WebView2 processes - -Use Microsoft Edge security connectors. - -Avoid dynamic-link library (DLL) injection. - -Don't inject dynamic-link libraries (DLLs) into WebView2 processes. Use Microsoft Edge security connectors instead. - -Prefer Microsoft Edge security connectors for Data Loss Prevention (DLP), reporting, or device trust. - -Dynamic-link library (DLL) injection into renderer or Graphics Processing Unit (GPU) processes breaks Chromium's sandboxing model, and commonly causes renderer crashes. - -Security software vendors should use supported Edge security connectors instead of low-level hooks. - -See: -* [Microsoft Edge for Business Security Connectors](/deployedge/microsoft-edge-connectors-overview) - in Microsoft Edge Enterprise documentation. - - - -#### Crashes or freezing - -Crash or freeze tied to dynamic-link library (DLL) injection or blocked renderer, Graphics Processing Unit (GPU), or Crashpad. - -See: -* [Handling process-related events in WebView2](./process-related-events.md) -* [Crash Dumps](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/diagnostics/crash.md) - WebView2Feedback repo. - - - -#### Content never loads - -Issue: The main process starts, but content never loads, and the app freezes. - -Spawning of child processes is blocked or hooked. - - - -###### Solutions - -Permit WebView2 child processes: -* Renderer. -* Graphics Processing Unit (GPU). -* Network. -* Crashpad. - -These are the child processes that WebView2 instantiates. - -Avoid dynamic-link library (DLL) injection. - -Prefer Edge connectors. - -See: -* [Microsoft Edge for Business Security Connectors](/deployedge/microsoft-edge-connectors-overview) - in Microsoft Edge Enterprise documentation. -* [Handling process-related events in WebView2](./process-related-events.md) -* [Crash Dumps](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/diagnostics/crash.md) - WebView2Feedback repo. - - - -## Avoid broad, global exclusions - - - -#### Slow startup - -Issues: -* Slow startup due to deep real-time scanning of the WebView2 Runtime and the user data folder (UDF). -* A transient white screen, when perform a navigation. -* Aggressive real-time scanning. - - - -###### Solutions - -Configure **scoped exclusions** for WebView2 Runtime binaries and user data folder (UDF); avoid broad exclusions. - -Tune scanning with scoped exclusions for the WebView2 Runtime directory and user data folder (UDF). - -Avoid broad, global exclusions. - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) -* [Manage user data folders](./user-data-folder.md) - - - -## Trust internal proxy Certificate Authorities (CAs), and allow essential sign-in or Content Delivery Network (CDN) endpoints - -Align Transport Layer Security (TLS) policies with Chromium: - -* Trust internal proxy Certificate Authorities (CAs); install trusted Certificate Authorities (CAs). - -* Allow essential sign-in endpoints, or other required endpoints. - -* Allow essential Content Delivery Network (CDN) endpoints. - -Preserve the default Access Control Lists (ACLs) and Low Integrity Level (LowIL) settings on WebView2 Runtime folders. - -* A Low Integrity Level process (LowIL) must be able to Read and Execute the WebView2 Runtime binaries. - -* Don't modify the default ACLs that the operating system sets on the Runtime folders. WebView2's sandboxed renderer processes run at Low Integrity Level, and require these permissions, to function correctly. - - - -## Trust the WebView2 Runtime by signature - -Recognize and trust the WebView2 Runtime (`msedgewebview2.exe`) by signature; allow child processes. - - - -## Don't modify WebView2 Runtime files that Windows components load from `C:\Windows\System32` - -Don't modify, quarantine, or replace WebView2 Runtime binary files that Windows components load directly from `C:\Windows\System32`. - -Some Windows components might load WebView2 Runtime binary files directly from `C:\Windows\System32`. These binary files are owned by the operating system. - -These OS-owned WebView2 Runtime binary files: - -* Might not match the Evergreen WebView2 Runtime version that's used by desktop apps. - -* Are serviced exclusively through Windows Update, not through WebView2 installers. - - - -## Align Transport Layer Security (TLS) inspection and proxy configuration - -Symptoms: - -* Transport Layer Security (TLS) errors (such as `ERR_CERT_*`). - -* Login redirect failures that occur when TLS inspection is enabled. - -Align Transport Layer Security (TLS) inspection and proxy configuration with Chromium-based browser requirements. - -If your environment uses TLS inspection, ensure that the inspection certificates are trusted by the operating system's certificate store. - - - -#### SSL decryption by a firewall or proxy - -An example of using TLS inspection is SSL decryption by a firewall or proxy. - -If your environment routes traffic through a proxy server, ensure that WebView2 processes can reach the required endpoints through the proxy. - - - -#### `ERR_CERT_*` error - -Issues: - -* `ERR_CERT_*` errors. - -* Sign-in loops (login loops). - -* Service workers failing. - -Network inspection vs. Transport Layer Security (TLS) inspection is misaligned. - - - -###### Solutions - -Install the enterprise proxy's root Certificate Authority (CA) so that WebView2 trusts intercepted HTTPS traffic. - -Ensure that authentication endpoints and Content Delivery Network (CDN) endpoints that are used by the WebView2 app are explicitly allowed. - -Validate authentication endpoints and Content Delivery Network (CDN) endpoints. - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) - - - -## Allow updates of the Evergreen WebView2 Runtime - -Do not block updates of the Evergreen WebView2 Runtime. - -Allow updates of the Evergreen WebView2 Runtime; don't block servicing. - -Microsoft Edge servicing updates the following versioned subfolders: - -`C:\Program Files (x86)\Microsoft\EdgeWebView\Application\\` - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) -* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) -* [Distribute your app and the WebView2 Runtime](./distribution.md) - - - -#### App only works with higher privilege - -There's an Access Control List (ACL) mismatch with the Integrity Level. - -Issue: The app works only at higher privilege. The app fails in the following environments: - -* **Universal Windows Platform (UWP)** — Apps that run inside the Windows app sandbox with restricted permissions. - -* **AppContainer** — A Windows security sandbox that limits a process's access to only explicitly granted resources. - - - -###### Solutions - -Keep default `ALL APPLICATION PACKAGES` permissions on WebView2 Runtime directories; a Low integrity level process (LowIL) must **read/execute**. - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) - -This includes the Evergreen WebView2 Runtime path under `C:\Program Files (x86)\Microsoft\EdgeWebView\Application\\`, which must retain `ALL APPLICATION PACKAGES` Read/Execute permissions. - -The System32-based WebView2 Runtime is owned and serviced by Windows. - -The System32-based WebView2 Runtime must not be modified, replaced, quarantined, or cleaned by Antivirus (AV), Endpoint Detection and Response (EDR), or Data Loss Prevention (DLP) tools. - -The System32-based WebView2 Runtime's default Access Control Lists (ACLs) must be preserved exactly as shipped. - - - -## Don't apply Edge browser–only group policies - -Most group policies that apply to Microsoft Edge don't affect WebView2, and unsupported policies can break WebView2 features. - -Don't use Microsoft Edge–only group policies to affect WebView2. - - - -## Tools in which to check for the symptoms and causes - -Audience: IT administrators. - -IT administrators can use standard Windows tools to determine whether the listed symptoms are caused by: -* WebView2 being blocked. -* WebView2 failing to initialize. -* WebView2 crashing. - - - -#### Task Manager - -Under the host application, verify that the WebView2 Runtime (`msedgewebview2.exe`) and its child processes appear. - -The child processes include: - -* Renderer. -* Graphics Processing Unit (GPU). -* Network. -* Crashpad. - -If no WebView2 child processes appear, the WebView2 Runtime or child process spawning is blocked, due to one of the following being enabled on the machine: - -* Windows Defender Application Control (WDAC). - -* Endpoint Detection and Response (EDR). - -* Dynamic-link library (DLL) injection. - -If renderer (or Graphics Processing Unit (GPU)) processes appear briefly and then disappear, the following might be terminating the renderer (or Graphics Processing Unit (GPU)) processes: - -* Endpoint Detection and Response (EDR) hooking. - -* Antivirus (AV) hooking. - -* Dynamic-link library (DLL) injection. - - - -#### Blank or white embedded window - -If there is a blank or white embedded window, make sure WebView2 processes are present in Task Manager. - -See: -* [Process model for WebView2 apps](./process-model.md) - - - -#### Event Viewer - -Event Viewer (Windows Logs > Application / System). - -Look for: - -* App or WebView2 initialization failures. - -* Windows Defender Application Control (WDAC) or AppLocker _blocked execution_ events. - -* Controlled Folder Access (CFA) or Data Loss Prevention (DLP) _file write denial_ events that affect the user data folder (UDF). - -* Transport Layer Security (TLS), certificate, or network policy failures that affect sign-in flows. - - - -#### Security logs - -* Controlled Folder Access (CFA) blocks. - -* Data Loss Prevention (DLP) policy blocks. - -* AppLocker or Application Control denials. These typically map to symptoms like sign-in loops, blank screens, or settings not persisting. - - - -#### Diagnostics, crash reports, and process events - -Crash reports are saved under the app's user data folder (UDF) at `EBWebView\Crashpad\reports\`. - -Use crash diagnostics together with process events to triage repeated failures. - -See: -* [Handling process-related events in WebView2](./process-related-events.md) -* [Crash Dumps](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/diagnostics/crash.md) - WebView2Feedback repo. - - - -#### Reliability Monitor - -Identify repeated crashes of renderer, Graphics Processing Unit (GPU), or Crashpad processes. - -These process crashes are correlated with: - -* Freezing problems. - -* Blank screen problems. - -* WebView2 Runtime instability. - - - -## Applicability to tools - -Audience: IT administrators and security software vendors. - -Various types of apps can interact with WebView2. The following are the applicability to different forms of WebView2. - -This article applies to the following tools or software: - -* The Microsoft Edge WebView2 Runtime (Evergreen and fixed-version). - -* Windows desktop applications that embed the WebView2 control. - -* Windows components that use WebView2 for the web-based portion of the UI. - -* Non-Microsoft antivirus, Endpoint Detection and Response (EDR), Data Loss Prevention (DLP), and proxy or Transport Layer Security (TLS) interception products that might interfere with WebView2 processes. - -See: -* [Microsoft Edge WebView2 and Microsoft 365 Apps](/microsoft-365-apps/deploy/webview2-install) - in Deployment guide for Microsoft 365 Apps. - - - -## Resolving performance issues - -Audience: IT administrators and security software vendors. - - - - -To use this section: - -1. The IT administrator uses this information to identify an issue that the IT administrator is seeing with launching or using WebView2 in their app, and figure out which security software is causing the issue. - -1. The IT administrator contacts the security software vendor. - -1. The security software vendor uses this content to figure out what they need to do to ensure that WebView2 is not blocked. - -Extensive scanning or hooking into processes can slow down startup and page loading times. - -Instead, use scoped exclusions for WebView2 Runtime binaries and user data folder (UDF), rather than opting for wide-ranging, high-risk disables. - -Treat child processes like browser processes; avoid terminating such child processes. - -Child processes include: -* Renderer. -* Graphics Processing Unit (GPU). -* Network. -* Crashpad. - -Do not end Crashpad or Graphics Processing Unit (GPU) processes, because they're crucial for stability and rendering. - -See: -* [Enterprise management of WebView2 Runtimes](./enterprise.md) -* [Handling process-related events in WebView2](./process-related-events.md) - - - -## Why WebView2 appears in enterprise workloads - -Audience: IT administrators and security software vendors. - -Many **Microsoft 365 Apps** and **Windows features** use WebView2 to deliver a modern, consistent UI. - -For example, Outlook features rely on the WebView2 Runtime to function. - -Windows Search uses WebView2 for parts of its UI. - -See: -* [WebView2 documentation](../landing/index.yml) -* [Microsoft Edge WebView2 and Microsoft 365 Apps](/microsoft-365-apps/deploy/webview2-install) - in Deployment guide for Microsoft 365 Apps. - - - -## See also - - -* [WebView2 documentation](../landing/index.yml) -* [Handling process-related events in WebView2](./process-related-events.md) -* [Evergreen vs. fixed version of the WebView2 Runtime](./evergreen-vs-fixed-version.md) -* [Distribute your app and the WebView2 Runtime](./distribution.md) -* [Enterprise management of WebView2 Runtimes](./enterprise.md) -* [Process model for WebView2 apps](./process-model.md) -* [Manage user data folders](./user-data-folder.md) - -Learn.microsoft.com: -* [Microsoft Edge for Business Security Connectors](/deployedge/microsoft-edge-connectors-overview) - in Microsoft Edge Enterprise documentation. -* [Microsoft Edge WebView2 and Microsoft 365 Apps](/microsoft-365-apps/deploy/webview2-install) - in Deployment guide for Microsoft 365 Apps. -* [Understanding the publisher rule condition in AppLocker](/windows/security/application-security/application-control/app-control-for-business/applocker/understanding-the-publisher-rule-condition-in-applocker) - in Windows Security (Application Control for Windows). -* [Prevent antivirus and DLP tools from blocking or crashing Microsoft Teams](/troubleshoot/microsoftteams/teams-administration/include-exclude-teams-from-antivirus-dlp) - in Microsoft Teams troubleshooting. - -External: -* [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2) - Developer.microsoft.com. -* [Crash Dumps](https://github.com/MicrosoftEdge/WebView2Feedback/blob/main/diagnostics/crash.md) - WebView2Feedback repo. diff --git a/microsoft-edge/webview2/concepts/security.md b/microsoft-edge/webview2/concepts/security.md index 03fe33ca86..7940027581 100644 --- a/microsoft-edge/webview2/concepts/security.md +++ b/microsoft-edge/webview2/concepts/security.md @@ -134,3 +134,6 @@ See also: ## See also * [Development best practices for WebView2 apps](./developer-guide.md) + +Microsoft Edge Enterprise documentation: +* [Prevent security tools from blocking WebView2 apps](/deployedge/webview2-security-tools) diff --git a/microsoft-edge/webview2/concepts/versioning.md b/microsoft-edge/webview2/concepts/versioning.md index d5d7bd4646..4ab2d77643 100644 --- a/microsoft-edge/webview2/concepts/versioning.md +++ b/microsoft-edge/webview2/concepts/versioning.md @@ -168,7 +168,7 @@ Once an API has been moved from Experimental to Stable status, you need to move ## Matching the Runtime version with the SDK version -In the Evergreen distribution approach, the client's WebView2 Runtime automatically updates to the latest version available. However, a user or IT admin might choose to prevent automatic updating of the WebView2 Runtime. The resulting outdated Runtime on the client might cause compatibility issues with your updated WebView2 app that uses new APIs from a recent SDK. +In the Evergreen distribution approach, the client's WebView2 Runtime automatically updates to the latest version available. However, a user or IT Admin might choose to prevent automatic updating of the WebView2 Runtime. The resulting outdated Runtime on the client might cause compatibility issues with your updated WebView2 app that uses new APIs from a recent SDK. In case updating the WebView2 Runtime is prevented on the client, make sure that you know the minimum build number of the WebView2 Runtime that is required by your app. To view or get the latest WebView2 Runtime versions, see [Download the WebView2 Runtime](https://developer.microsoft.com/microsoft-edge/webview2#download-the-webview2-runtime) in the _Microsoft Edge WebView2_ page at developer.microsoft.com. The minimum required Runtime version to support the General Availability release of the SDK (build 616) is older than for the latest Runtime. The latest Runtime supports all APIs that are in the latest Release SDK. diff --git a/microsoft-edge/webview2/landing/index.yml b/microsoft-edge/webview2/landing/index.yml index 355207a3b5..d517879369 100644 --- a/microsoft-edge/webview2/landing/index.yml +++ b/microsoft-edge/webview2/landing/index.yml @@ -245,9 +245,6 @@ landingContent: - text: Distribute your app and the WebView2 Runtime url: ../concepts/distribution.md - - text: Enterprise management of WebView2 Runtimes - url: ../concepts/enterprise.md - - text: Distribute an app as a single executable file url: ../how-to/static.md diff --git a/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md b/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md index dcb55cce80..d6220e94b8 100644 --- a/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md +++ b/microsoft-edge/webview2/release-notes/sdk/1-0-721-prerelease.md @@ -16,6 +16,15 @@ Release notes for Microsoft Edge WebView2 Prerelease SDK, release date: Dec. 8, This Prerelease version of the WebView2 SDK requires Microsoft Edge version 86.0.616.0 or later; see [Runtime 86.0.705.50 (Jan. 25, 2021)](../runtime/86.md). +**Detailed contents:** +* [Breaking changes](#breaking-changes) + * [Features](#features) +* [Promotions to Phase 2 (Stable in Prerelease)](#promotions-to-phase-2-stable-in-prerelease) + * [.NET](#net) + * [Features](#features-1) + * [Bug fixes](#bug-fixes) +* [See also](#see-also) + ## Breaking changes @@ -27,7 +36,7 @@ This Prerelease version of the WebView2 SDK requires Microsoft Edge version 86.0 #### Features -* Added [WebView2 Group Policies](/deployedge/microsoft-edge-webview-policies). For best practices, see [group policies for WebView2](../../concepts/enterprise.md#group-policies-for-webview2). +* Added [Microsoft Edge WebView2 - Policies](/deployedge/microsoft-edge-webview-policies). For best practices, see [Enterprise management of WebView2](/deployedge/webview2-enterprise), in the Microsoft Edge Enterprise documentation. * > [!IMPORTANT] > **Breaking Change**: Deprecated the old registry location. diff --git a/redirects/.openpublishing.redirection.webview2.json b/redirects/.openpublishing.redirection.webview2.json index 72b4868ea5..08c6e04df5 100644 --- a/redirects/.openpublishing.redirection.webview2.json +++ b/redirects/.openpublishing.redirection.webview2.json @@ -36,6 +36,16 @@ "redirect_url": "/microsoft-edge/webview2/concepts/user-data-folder", "redirect_document_id": false }, + { + "source_path": "../microsoft-edge/webview2/concepts/enterprise.md", + "redirect_url": "/deployedge/webview2-enterprise", + "redirect_document_id": false + }, + { + "source_path": "../microsoft-edge/webview2/concepts/measures.md", + "redirect_url": "/deployedge/webview2-security-tools", + "redirect_document_id": false + }, // /Concepts // ====================================================================== // Getting started