A detailed guide to configuring extensions using the ExtensionSettings policy

Article
01/12/2024

Microsoft Edge offers multiple ways to manage extensions. A common way is to set multiple policies in one place with a JSON string in the Windows Group Policy Editor or in the Windows Registry using the ExtensionSettings policy.

Note

The Microsoft Edge management service, a dedicated and simplified management tool in the Microsoft 365 admin center, is rolling out now. Learn more.

Before you begin

Decide if you want to set all extension management settings in the ExtensionSettings policy or set these controls through other policies.

The ExtensionSettings policy can overwrite other policies that you've set elsewhere in group policy, including the following policies:

ExtensionSettings policy fields

This policy can control settings such as Update URL, where the extension is downloaded from for initial installation, and Blocked permissions. You can also use this policy to identify which permissions aren't allowed to run. The available policy fields are described in the following table.

Policy field	Description
allowed_types	Can only be used to configure the default configuration, *. Specifies what types of app or extension users are allowed to install on Microsoft Edge. The value is a list of strings, each of which should be one of the following types: "extension", "theme", "user_script", and "hosted_app".
blocked_install_message	If you block users from installing certain extensions, you can specify a custom message to display in the browser if users try to install them. Append text to the generic error message that is displayed on the Microsoft Edge Add-ons website. For example, you can tell users how to contact their IT department or why a particular extension is unavailable. The message can be up to 1,000 characters long.
blocked_permissions	Prevents users from installing and running extensions that request certain API permissions that your organization doesn't allow. For example, you can block extensions that access cookies. If an extension requires a permission that you blocked, the users can't install it. If users installed the extension previously, it won't load. If an extension contains a blocked permission as an optional requirement, it installs as usual. Then, while the extension is running, blocked permissions are automatically declined. For a list of available permissions, see declare permissions.
file_url_navigation_allowed	Edge browser version 120 and later Allows extensions to navigate to specified file URLs.
installation_mode	Controls if and how extensions that you specify are added to Microsoft Edge. You can set the installation mode to one of the following options: - `allowed`: Users can install the extension. If no installation mode is defined, this setting is the default. - `blocked`: Users can't install the extension. - `force_installed`: Automatically install the extension without user interaction. Users can't remove it. You also need to define the extension download location using "update_url". Note: You can't use this setting with * because Microsoft Edge wouldn't know which extension to automatically install. - `normal_installed`: Automatically install the extension without user interaction. Users can disable it. You also need to define the extension download location using "update_url". Note: You can't use this setting with * because Microsoft Edge wouldn't know which extension to automatically install. - `removed`: Users can't install the extension. If users installed the extension previously, Microsoft Edge removes it.
install_sources	Can be used only to configure the default configuration, . Specifies which URLs are allowed to install extensions. Both the location of the .crx file and the page where the download is started from (the referrer) must be allowed by these patterns. For URL pattern examples, see the match patterns.
minimum_version_required	Microsoft Edge disables extensions, including force-installed extensions, with a version older than the specified minimum version. The format of the version string is the same as the one used in the extension manifest.
update_url	Only applies to `force_installed` and `normal_installed`. Specifies where Microsoft Edge should download an extension from. If the extension is hosted in the Microsoft Edge Add-ons website, use this location: `https://edge.microsoft.com/extensionwebstorebase/v1/crx`. Microsoft Edge uses the URL that you specify for the initial extension installation. For subsequent extension updates, Microsoft Edge uses the URL in the extension's manifest.
runtime_allowed_hosts	Allows extensions to interact with specified websites, even if they're also defined in runtime_blocked_hosts. You can specify up to 100 entries. Extra entries are discarded. The host pattern format is similar to match patterns except you can't define the path. For example: - ://.example.com - ://example.—eTLD wildcards are supported
runtime_blocked_hosts	Prevent extensions from interacting with or modifying websites that you specify. Modifications include blocking JavaScript injection, cookie access, and web-request modifications. You can specify up to 100 entries. Extra entries are discarded. The host pattern format is similar to match patterns ex'cept you can't define the path. For example: - ://.example.com - ://example.—eTLD wildcards are supported
override_update_url	Available from Microsoft Edge 93 If this field is set to `true`, Microsoft Edge uses the update URL specified in the ExtensionSettings policy or in the ExtensionInstallForcelist policy, for subsequent extension updates. If this field isn't set or is set to `false`, Microsoft Edge uses the URL specified in the extension's manifest for updates.
toolbar_state	Available from Microsoft Edge 103 This policy setting lets you force show an installed extension to the toolbar. The default state is `default_hidden` for all extensions. The following values are possible for this setting: - `force_shown`: You can choose to force show an installed extension on the toolbar. Users won't be able to hide the specified extension icon from the toolbar. - `default_hidden`: This is the default setting for all the installed extensions on the browser. - `default_shown`: In this state, extensions are shown on the toolbar on installation. Users can hide them from the toolbar, if needed.
sidebar_auto_open_blocked	Available from Microsoft Edge 119 If this field is set to `true`, any sidebar app with the specified extension ID will be prevented from automatically opening.

The following keys are allowed at the global scope (*):

blocked_permissions
installation_mode - only "blocked", "allowed", or "removed" are the valid values in this scope.
runtime_blocked_hosts
blocked_install_message
allowed_types
runtime_allowed_hosts
install_sources

The following keys are allowed at an individual extension scope:

blocked_permissions
minimum_version_required
blocked_install_message
installation_mode - "blocked", "allowed", "removed", "force_installed", and "normal_installed" are the possible values.
runtime_allowed_hosts
update_url
override_update_url
runtime_blocked_hosts
toolbar_state
sidebar_auto_open_blocked

The following keys are allowed at an update URL scope:

blocked_permissions
installation_mode - only "blocked", "allowed", or "removed" are the valid values in this scope.

Configure using a JSON string in Windows Group Policy Editor

The steps to use the extension settings policy using GPO assume that you've already imported the ADM/ADMX for Microsoft Edge Policies.

Open the group policy editor and go to Microsoft Edge > Extensions > Configure extension management setting policy.
Enable the policy and enter its compact JavaScript Object Notation (JSON) data in the text box as a single line without line breaks.
To validate the policy and compact it into a single line, use a JSON compression tool.

Properly format JSON for the extension settings policy

You need to understand the two parts to this policy—the default scope and the individual scope. The default scope is a catch-all for extensions without their own scope. The individual scope is applied to that extension only.

The default scope is identified by the asterisk (*). The next example defines a default scope and an individual extension scope.

{ 
   "*": {}, 
   "nckgahadagoaajjgafhacjanaoiihapd": {} 
}

An extension will only get its settings from one scope. If there's an individual extension scope for that extension, those will be the settings that apply to that extension. If no individual extension scope exists, then the extension will use the default scope.

The next JSON example blocks any extension from running on .example.com and blocks any extension that requires the permission "USB".

{ 
  "*": { 
    "runtime_blocked_hosts": ["*://*.example.com"], 
    "blocked_permissions": ["usb"] 
  } 
}

Compact JSON

{"*":{"runtime_blocked_hosts":["*://*.example.com"],"blocked_permissions":["usb"]}}

A few more JSON examples for extension settings

Using installation_mode property to allow and block extensions

User can install all extensions - the default setting

{ "*": {"installation_mode": "allowed" }}
User can't install any extensions.

{ "*": {"installation_mode": "blocked" }}
Specify a custom message to display when installation is blocked.

{"*": {"blocked_install_message": ["Call IT(408 - 555 - 1234) for an exception"]}}

Using installation_mode property to force install extensions

When using installation_mode as "force_installed", the extension is automatically installed without user interaction. A user can't disable or remove the extension. If an extension is "normal" or "force" installed, the update_url field must also be defined. This field points to the location where the extension can be installed from. Use the following locations for the update_url field:

If the extension you're downloading is hosted on the Microsoft Edge Add-ons store, use the location in the following JSON example:

{"nckgahadaanghapdoaajjgafhacjaoii": {"installation_mode": "force_installed","update_url": "https://edge.microsoft.com/extensionwebstorebase/v1/crx"}}
If the extension you're downloading is hosted on the Chrome Web Store, use the location in the following JSON example:

{"nckgiihapdoaajjgafhacjgahadaanao": {"installation_mode": "force_installed","update_url": "https://clients2.google.com/service/update2/crx"}}
If you're hosting the extension on your own server, use the URL where Microsoft Edge can download the packed extension (.crx file). JSON example:

{"nckgahadagoaajjgafhacjanaoiihapd": {"installation_mode": "force_installed","update_url": "https://edge.microsoft.com/extensionwebstorebase/v1/crx"}}

In the previous example, if you use "normal_installed" instead of "force_installed", then the extension is automatically installed without user interaction, but they can disable the extension.

Tip

Formatting a JSON string correctly can be tricky. Use a JSON checker before implementing the policy. Or try the early version of Extension Settings Generator Tool

Configure using the Windows Registry

The ExtensionSettings policy should be written to the registry under this key:

HKLM\Software\Policies\Microsoft\Edge\

Note

It's possible to use HKCU instead of HKLM. The equivalent path can be configured with Group Policy Object (GPO).

For Microsoft Edge, all settings will start under this key:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\

The next key that you'll create is either the Extension ID for individual scope or an asterisk (*) for the Default Scope. For example, you'd use the following location in the registry for settings that apply to Google Hangouts:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\ExtensionSettings\nckgahadagoaajjgafhacjanaoiihapd

For settings that apply to the Default Scope (asterisk), use the following location in the registry:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\ExtensionSettings\*

Different settings will require different formats, depending on whether they're a string or an array of strings. Array values require [＂value＂]. String values can be entered as is. The following list shows which settings are arrays or strings:

Installation_mode = String
update_url = String
blocked_permissions = Array of strings
allowed_permissions = Array of Strings
minimum_version_required = String
runtime_blocked_hosts = Array of strings
runtime_allowed_hosts = Array of Strings
blocked_install_message = String