diff --git a/microsoft-edge/webview2/concepts/security.md b/microsoft-edge/webview2/concepts/security.md index e64da9c59b..03fe33ca86 100644 --- a/microsoft-edge/webview2/concepts/security.md +++ b/microsoft-edge/webview2/concepts/security.md @@ -6,7 +6,7 @@ ms.author: msedgedevrel ms.topic: article ms.service: microsoft-edge ms.subservice: webview -ms.date: 06/27/2024 +ms.date: 07/14/2026 --- # Develop secure WebView2 apps @@ -88,3 +88,49 @@ When navigating to a new document, use the `ContentLoading` event and `RemoveHos ## WebView2 cannot be run as a system user WebView2 cannot be run as a system user. This restriction blocks scenarios such as building a Credential Provider. + + + +## Recommended privilege level for WebView2 host applications + +As a security best practice, we recommend hosting WebView2 in a process that runs at standard (non-elevated) user integrity. Following the principle of least privilege, applications should avoid running the WebView2-hosting component with elevated (administrator) privileges. + +If your application requires elevated privileges for certain operations, we recommend isolating that work in a separate, dedicated process and keeping the WebView2 host component de-elevated. This keeps the browser-hosting surface at the lowest privilege level necessary, and aligns with recommended Windows application security practices. + + + +#### For an elevated host app, use appropriate override flags + +For an elevated WebView2 host app process, use the appropriate type of override flags. An elevated process is a High Integrity Level (High IL) process. To help protect elevated processes from configuration that can be modified by standard users, WebView2 ignores certain user-scoped override mechanisms when the host process is running elevated. + +When the host process is running elevated: + +* `WEBVIEW2_*` environment variable overrides (flags) are ignored, including `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS`. See: + * [Setting browser flags in your local device environment](./webview-features-flags.md#setting-browser-flags-in-your-local-device-environment) in _WebView2 browser flags_. + +* Configuration flags that are specified within the WebView2 app via the WebView2 API are honored. See: + * [Setting browser flags programmatically through code](./webview-features-flags.md#setting-browser-flags-programmatically-through-code) in _WebView2 browser flags_. + +* `HKEY_CURRENT_USER` (`HKCU`) policy overrides are ignored. See: + * [Switching the channel search order (recommended)](../how-to/set-preview-channel.md#switching-the-channel-search-order-recommended) in _Test upcoming APIs and features_ - Select the **Registry key** tab, and then Find `HKCU`. + * [How to use `ChannelSearchKind` to ensure that a particular channel is used](../how-to/set-preview-channel.md#how-to-use-channelsearchkind-to-ensure-that-a-particular-channel-is-used) in _Test upcoming APIs and features_ - Select the **Registry key** tab, and then Find `HKCU`. + * [Setting the browser executable folder (for local testing)](../how-to/set-preview-channel.md#setting-the-browser-executable-folder-for-local-testing) in _Test upcoming APIs and features_ - Select the **Registry key** tab, and then Find `HKCU`. + * [Debug WebView2 apps with Visual Studio Code](../how-to/debug-visual-studio-code.md) - Find `HKEY_CURRENT_USER`. + +* `AdditionalBrowserArguments` registry overrides that are under `HKCU` are ignored. + +* `HKEY_LOCAL_MACHINE` (`HKLM`) policy overrides are honored. See: + * [Switching the channel search order (recommended)](../how-to/set-preview-channel.md#switching-the-channel-search-order-recommended) in _Test upcoming APIs and features_ - Select the **Registry key** tab, and then Find `HKLM`. + * [How to use `ChannelSearchKind` to ensure that a particular channel is used](../how-to/set-preview-channel.md#how-to-use-channelsearchkind-to-ensure-that-a-particular-channel-is-used) in _Test upcoming APIs and features_ - Select the **Registry key** tab, and then Find `HKLM`. + * [Setting the browser executable folder (for local testing)](../how-to/set-preview-channel.md#setting-the-browser-executable-folder-for-local-testing) in _Test upcoming APIs and features_ - Select the **Registry key** tab, and then Find `HKLM`. + +Non-elevated WebView2 apps honor all of the supported override mechanisms. + +See also: +* [Distribute your app and the WebView2 Runtime](./distribution.md) - Find "elevated". + + + +## See also + +* [Development best practices for WebView2 apps](./developer-guide.md) diff --git a/microsoft-edge/webview2/concepts/webview-features-flags.md b/microsoft-edge/webview2/concepts/webview-features-flags.md index abcdeb178a..d24460d18f 100644 --- a/microsoft-edge/webview2/concepts/webview-features-flags.md +++ b/microsoft-edge/webview2/concepts/webview-features-flags.md @@ -33,12 +33,16 @@ You can set browser flags in your local device environment, or set browser flags To test forthcoming features or to diagnose issues, we recommend using browser flags in your local device environment, via setting the `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` environment variable or via registry keys. For more information, see the following Win32 API Reference: [CreateCoreWebView2EnvironmentWithOptions](/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environmentwithoptions). +Elevated apps ignore flags that are set via the local device environment; see [For an elevated host app, use appropriate override flags](./security.md#for-an-elevated-host-app-use-appropriate-override-flags) in _Develop secure WebView2 apps_. + ## Setting browser flags programmatically through code Instead of setting browser flags in your local device environment, an alternative approach is to set browser flags programmatically, by passing the browser flags as the `AdditionalBrowserArguments` property of `CoreWebView2EnvironmentOptions`. If you set browser flags programmatically, be sure to remove the flags in code before shipping your app, to avoid accidentally shipping the flags in production. +Elevated apps honor flags that are set via code; see [For an elevated host app, use appropriate override flags](./security.md#for-an-elevated-host-app-use-appropriate-override-flags) in _Develop secure WebView2 apps_. + ##### [.NET/C#](#tab/dotnetcsharp) * `CoreWebView2EnvironmentOptions` Class: diff --git a/microsoft-edge/webview2/how-to/debug-visual-studio-code.md b/microsoft-edge/webview2/how-to/debug-visual-studio-code.md index dc0dfc121c..5ebcec0cdb 100644 --- a/microsoft-edge/webview2/how-to/debug-visual-studio-code.md +++ b/microsoft-edge/webview2/how-to/debug-visual-studio-code.md @@ -45,7 +45,7 @@ The following code demonstrates launching the app from Visual Studio Code (rathe #### Using a registry value -Instead of setting the `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` environment variable, you can add a new registry value named `` with data `--remote-debugging-port=9222` to the registry under registry key `Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments`, so that the debugger can find the proper port. For more information, see [WewbView2 browser flags](../concepts/webview-features-flags.md). +Instead of setting the `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` environment variable, you can add a new registry value named `` with data `--remote-debugging-port=9222` to the registry under registry key `Computer\HKEY_CURRENT_USER\Software\Policies\Microsoft\Edge\WebView2\AdditionalBrowserArguments`, so that the debugger can find the proper port. For more information, see [WebView2 browser flags](../concepts/webview-features-flags.md). @@ -155,7 +155,7 @@ You also need to add a new REGKEY ` = --remote-debugging-port=9222` u #### Using an environment variable -Instead of adding the above registry key, you can set the `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` environment variable to `--remote-debugging-port=9222`. Make sure that your application is started after the environment variable is set, and make sure that your application inherits the environment variable. For more information, see [WewbView2 browser flags](../concepts/webview-features-flags.md). +Instead of adding the above registry key, you can set the `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` environment variable to `--remote-debugging-port=9222`. Make sure that your application is started after the environment variable is set, and make sure that your application inherits the environment variable. For more information, see [WebView2 browser flags](../concepts/webview-features-flags.md). diff --git a/microsoft-edge/webview2/release-notes/index.md b/microsoft-edge/webview2/release-notes/index.md index eb90782a62..d62f4e9761 100644 --- a/microsoft-edge/webview2/release-notes/index.md +++ b/microsoft-edge/webview2/release-notes/index.md @@ -50,6 +50,12 @@ Starting with version 152 (Aug. 24, 2026), the WebView2 Runtime moves to a 2-wee See [[Announcement] WebView2 Runtime moves to a 2-week release cadence (starting v152)](https://github.com/MicrosoftEdge/WebView2Announcements/issues/137). + +###### Run your WebView2 host application at standard user integrity rather than elevated + +Run your WebView2 host application at standard user integrity rather than elevated. See [Recommended privilege level for WebView2 host applications](../concepts/security.md#recommended-privilege-level-for-webview2-host-applications) in _Develop secure WebView2 apps_. + + #### Experimental APIs (Phase 1: Experimental in Prerelease)