Many WebView2 applications need to apply different security and feature policies depending on the origin of the content they host. In some scenarios, applications must enable advanced capabilities for specific origins while enforcing stricter protections for other origins.
By default, WebView2 enforces a single, uniform security model across all origins. This creates two primary limitations:
-
Feature Access Control: Applications cannot selectively enable privileged features—such as specific APIs or advanced capabilities—for certain origins only. As a result, developers must either expose these features to all content or disable them entirely.
-
Performance and Security Trade-offs: Security mechanisms such as Enhanced Security Mode are essential for external content but may introduce unnecessary overhead when applied to first‑party experiences.
For example, a content management system may need to grant full feature access and relax certain security restrictions for its administrative interface, while still applying strict security policies to user‑generated or external content displayed within the same WebView2 instance.
The Origin Configuration API enables these scenarios by allowing applications to configure origin-specific settings for different features. Applications can define feature policies for specific origins or origin patterns, giving developers fine‑grained control over how features and security mechanisms are applied to content from various sources.
This specification introduces the following interfaces:
-
ICoreWebView2Profile3:The ICoreWebView2Profile3 interface provides APIs for defining, applying, and retrieving origin feature settings. It introduces the following members:
-
CreateOriginFeatureSetting: Creates a new CoreWebView2OriginFeatureSetting object. The returned object can be added to the collection passed to SetOriginFeatures to configure feature behavior for origins.
-
SetOriginFeatures: Applies the specified origin feature settings to one or more origins associated with this profile.
-
GetEffectiveFeaturesForOrigin: Asynchronously retrieves the origin feature settings—both the feature identifier and its enabled/disabled state—for a specified origin.
-
-
ICoreWebView2OriginFeatureSetting:The ICoreWebView2OriginFeatureSetting interface represents a simple pairing of a feature enumeration value and its corresponding feature state (enabled or disabled). Currently, the feature enumeration supports the following values:
- AccentColor
- EnhancedSecurityMode
void SetOriginFeatures()
{
auto stagingProfile3 =
m_webviewProfile.try_query<ICoreWebView2StagingProfile3>();
// Create feature settings
wil::com_ptr<ICoreWebView2StagingOriginFeatureSetting> accentColorSetting;
CHECK_FAILURE(stagingProfile3->CreateOriginFeatureSetting(
COREWEBVIEW2_ORIGIN_FEATURE_ACCENT_COLOR,
COREWEBVIEW2_ORIGIN_FEATURE_STATE_ENABLED,
&accentColorSetting));
wil::com_ptr<ICoreWebView2StagingOriginFeatureSetting> enhancedSecuritySetting;
CHECK_FAILURE(stagingProfile3->CreateOriginFeatureSetting(
COREWEBVIEW2_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE,
COREWEBVIEW2_ORIGIN_FEATURE_STATE_ENABLED,
&enhancedSecuritySetting));
// Set features for origin patterns
ICoreWebView2StagingOriginFeatureSetting* features[] = {
accentColorSetting.get(),
enhancedSecuritySetting.get()
};
LPCWSTR origins[] = { L"https://*.contoso.com" };
CHECK_FAILURE(stagingProfile3->SetOriginFeatures(
ARRAYSIZE(origins),
origins,
ARRAYSIZE(features),
features));
}
void GetFeatureSettingsForOrigin()
{
auto stagingProfile3 =
m_webviewProfile.try_query<ICoreWebView2StagingProfile3>();
std::wstring origin = L"https://www.microsoft.com";
CHECK_FAILURE(
stagingProfile3->GetEffectiveFeaturesForOrigin(
origin.c_str(),
Callback<ICoreWebView2StagingGetEffectiveFeaturesForOriginCompletedHandler>(
[this, origin](HRESULT errorCode,
ICoreWebView2StagingOriginFeatureSettingCollectionView* result) -> HRESULT
{
if (SUCCEEDED(errorCode))
{
UINT32 count = 0;
CHECK_FAILURE(result->get_Count(&count));
std::wstring message = L"Features for origin: " + origin + L"\n";
for (UINT32 i = 0; i < count; i++)
{
wil::com_ptr<ICoreWebView2StagingOriginFeatureSetting> setting;
CHECK_FAILURE(result->GetValueAtIndex(i, &setting));
COREWEBVIEW2_ORIGIN_FEATURE feature;
COREWEBVIEW2_ORIGIN_FEATURE_STATE State;
CHECK_FAILURE(setting->get_Feature(&feature));
CHECK_FAILURE(setting->get_State(&State));
message += L"Feature: " + std::to_wstring(static_cast<int>(feature)) +
L", Enabled: " + (State ? L"True" : L"False") + L"\n";
}
MessageBoxW(m_appWindow->GetMainWindow(), message.c_str(), L"Origin Features", MB_OK);
}
return S_OK;
}).Get()));
}public void SetOriginFeatures()
{
// Create feature settings collection
var features = new Dictionary<CoreWebView2OriginFeature, CoreWebView2OriginFeatureState>
{
{ CoreWebView2OriginFeature.AccentColor, CoreWebView2OriginFeatureState.Enabled },
{ CoreWebView2OriginFeature.EnhancedSecurityMode, CoreWebView2OriginFeatureState.Enabled },
};
// Set features for origin patterns
var origins = new[] { "https://*.contoso.com" };
m_webviewProfile.SetOriginFeatures(origins, features);
}
private async Task GetFeatureSettingsForOriginAsync()
{
var settings = await m_webviewProfile.GetEffectiveFeaturesForOriginAsync("https://www.microsoft.com/");
var builder = new StringBuilder();
foreach (var setting in settings) {
builder.AppendLine($"Feature: {setting.Feature}, Enabled = {setting.State}");
}
m_appWindow.AsyncMessageBox(builder.ToString(), "Origin features");
}/// Specifies the feature types that can be configured for origins.
[v1_enum]
typedef enum COREWEBVIEW2_ORIGIN_FEATURE {
/// Specifies the accent color feature for the origin.
/// This controls whether the origin can use the AccentColor CSS keyword, which provides
/// access to the system's accent color. The AccentColor keyword can be used in CSS color
/// properties to match the operating system's accent color, enabling
/// better integration with the native UI theme.
/// By default, the accent color feature is disabled for all origins.
///
/// For more information about CSS color keywords, see:
/// https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
COREWEBVIEW2_ORIGIN_FEATURE_ACCENT_COLOR,
/// Specifies enhanced security mode settings for the origin.
/// Enhanced Security Mode provides additional protections by disabling or restricting
/// certain web platform features that may pose security risks, such as JIT compilation,
/// certain JavaScript APIs, and other potentially dangerous capabilities. This feature
/// is particularly useful for protecting against zero-day exploits and reducing attack
/// surface. When enabled for an origin, that origin will have Enhanced Security Mode
/// applied; when disabled, normal security mode is used.
/// Enhanced security mode can be configured globally via EnhancedSecurityModeLevel API on profile.
/// If Enhanced Security Mode is not configured for an origin, the global profile setting will apply.
///
/// For more information about Enhanced Security Mode, see:
/// https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/security
COREWEBVIEW2_ORIGIN_FEATURE_ENHANCED_SECURITY_MODE,
} COREWEBVIEW2_ORIGIN_FEATURE;
/// Specifies the state of the origin feature.
[v1_enum]
typedef enum COREWEBVIEW2_ORIGIN_FEATURE_STATE {
/// Sets the enabled state of the origin feature.
COREWEBVIEW2_ORIGIN_FEATURE_STATE_ENABLED,
/// Sets the disabled state of the origin feature.
COREWEBVIEW2_ORIGIN_FEATURE_STATE_DISABLED,
} COREWEBVIEW2_ORIGIN_FEATURE_STATE;
/// Receives the result of the `GetEffectiveFeaturesForOrigin` method.
interface ICoreWebView2StagingGetEffectiveFeaturesForOriginCompletedHandler : IUnknown {
/// Provides the result of the corresponding asynchronous method.
HRESULT Invoke([in] HRESULT errorCode, [in] ICoreWebView2StagingOriginFeatureSettingCollectionView* result);
}
/// This is the ICoreWebView2Profile interface for origin feature management.
interface ICoreWebView2StagingProfile3 : IUnknown {
/// Creates a CoreWebView2OriginFeatureSetting objects. This object represents a specific feature and its state (enabled or disabled).
/// This method allows creating a feature settings object that can be used with
/// SetOriginFeatures to configure features for origins.
HRESULT CreateOriginFeatureSetting(
[in] COREWEBVIEW2_ORIGIN_FEATURE featureKind,
[in] COREWEBVIEW2_ORIGIN_FEATURE_STATE featureState
, [out, retval] ICoreWebView2StagingOriginFeatureSetting** value);
/// Configures one or more feature settings for the specified origins.
///
/// This method applies feature configurations—such as accent color support,
/// or enhanced security mode—to origins. Origins
/// may be provided as exact origin strings or as wildcard patterns.
///
/// The origin pattern can be an exact origin string or a wildcard pattern.
/// For wildcard patterns, `*` matches zero or more characters.
/// Examples:
/// | Origin Filter String | What It Matches | Description |
/// |---------|-----------------|-------------|
/// | `https://contoso.com` | Only `https://contoso.com` | Matches the exact origin with specific protocol and hostname |
/// | `https://[*.]contoso.com` | `https://app.contoso.com`,`https://api.contoso.com`,`https://admin.contoso.com` | Matches any subdomain under the specified domain |
/// | `*://contoso.com` | `https://contoso.com`,`http://contoso.com`,`ftp://contoso.com` | Matches any protocol for the specified hostname |
/// | `https://www.microsoft.com:*` | `https://www.microsoft.com:123` | Matches any port for the specified origin |
/// | `[*.]example.com` | `https://www.example.com`,`http://abc.example.com` | Matches any subdomain with any protocol for the specified domain |
/// | `https://xn--qei.example/` | `https://❤.example/`,`https://xn--qei.example/` | Normalized punycode matches with corresponding Non-ASCII hostnames |
///
/// Calling this method multiple times with the same (featureKind, featureState)
/// pair overwrites the previous configuration; the most recent call takes
/// precedence.
///
/// When multiple configurations exist for the same feature but specify
/// different featureState values, the configuration whose origin pattern is
/// more specific takes precedence.
///
/// The specificity of an origin pattern is determined by the presence and
/// placement of wildcards. Three wildcard categories influence specificity:
/// - Wildcards in the port (for example, `https://www.example.com:*/*`)
/// - Wildcards in the scheme (for example, `*://www.example.com:123/*`)
/// - Wildcards in the hostname (for example, `https://*.example.com:123/*`)
///
/// If one pattern is more specific in one component but less specific in
/// another, specificity is evaluated in the following order:
/// 1. Hostname
/// 2. Scheme
/// 3. Port
///
/// For example, the following patterns are ordered by precedence:
/// `https://www.example.com:*/*` → `*://www.example.com:123/*` → `https://*.example.com:123/*`.
///
/// To reset the origin list for a particular (feature, state) pair, call
/// SetOriginFeatures with an empty origin list or nullptr for the same
/// feature setting.
/// For example,
/// SetOriginFeatures(1, {"https://microsoft.com"}, 1, {{ESM: Enabled}});
/// SetOriginFeatures(0, {}, 1, {{ESM: Enabled}}); // Resets {ESM: Enabled}
HRESULT SetOriginFeatures(
[in] UINT32 originsCount,
[in] LPCWSTR* originPatterns,
[in] UINT32 featureCount,
[in] ICoreWebView2StagingOriginFeatureSetting** features
);
/// Gets the effective feature settings for a specified origin.
/// Returns a collection of feature settings for all the features in
/// `COREWEBVIEW2_ORIGIN_FEATURE`. This collection contains the effective
/// (computed) setting values for all features, including features that were
/// not explicitly configured via `SetOriginFeatures` and thus have their
/// default values.
/// The order of features in the returned collection is not guaranteed.
/// The origin should have a valid scheme and host (e.g. "https://www.example.com"),
/// otherwise the method fails with `E_INVALIDARG`.
HRESULT GetEffectiveFeaturesForOrigin(
[in] LPCWSTR origin
, [in] ICoreWebView2StagingGetEffectiveFeaturesForOriginCompletedHandler* handler);
}
/// Represents a feature setting configuration for a origin.
interface ICoreWebView2StagingOriginFeatureSetting : IUnknown {
/// The feature type for this setting.
[propget] HRESULT Feature([out, retval] COREWEBVIEW2_ORIGIN_FEATURE* value);
/// Indicates whether the feature is enabled for the origin.
[propget] HRESULT State([out, retval] COREWEBVIEW2_ORIGIN_FEATURE_STATE* value);
}
/// A collection of origin settings.
interface ICoreWebView2StagingOriginFeatureSettingCollectionView : IUnknown {
/// Gets the number of objects contained in the `OriginFeatureSettingCollection`.
[propget] HRESULT Count([out, retval] UINT32* value);
/// Gets the object at the specified index.
HRESULT GetValueAtIndex(
[in] UINT32 index
, [out, retval] ICoreWebView2StagingOriginFeatureSetting** value);
}namespace Microsoft.Web.WebView2.Core
{
enum CoreWebView2OriginFeatureState
{
Enabled = 0,
Disabled = 1,
};
enum CoreWebView2OriginFeature
{
AccentColor = 0,
EnhancedSecurityMode = 1,
};
runtimeclass CoreWebView2OriginFeatureSetting
{
// ICoreWebView2StagingOriginFeatureSetting members
CoreWebView2OriginFeature Feature { get; };
CoreWebView2OriginFeatureState State { get; };
}
runtimeclass CoreWebView2Profile
{
[interface_name("Microsoft.Web.WebView2.Core.CoreWebView2Profile_Manual5")]
{
void SetOriginFeatures(
Windows.Foundation.Collections.IIterable<String> origins,
Windows.Foundation.Collections.IIterable<
Windows.Foundation.Collections.IKeyValuePair<CoreWebView2OriginFeature, CoreWebView2OriginFeatureState> > features);
Windows.Foundation.IAsyncOperation<IVectorView<CoreWebView2OriginFeatureSetting> > GetEffectiveFeaturesForOriginAsync(String origin);
}
}
}