Private hosting (Edge)

Deploy the Applet Runner extension via Group Policy (Windows).

If your organisation requires you to use our extension on multiple devices, we have amazing news for you! Our Applet Runner extension is available for private hosting and deployment via Group Policies. This way, you can deploy our extension for multiple users under your organisation simultaneously and administrate it from a single place. This page will take you step by step on how to do this.

For a comprehensive tutorial on self-hosting custom extensions, please refer to the official Microsoft Documentation, which will be the primary reference for this guidance.

Requirements:

  • The appropriate IT permissions at your organisation.
  • For self hosting: The Applet Runner extension CRX file.

The CRX File and DownloadURL

The CRX file is a compressed format for extensions of browsers belonging to the Chromium family (such as Google Chrome and Edge). To obtain the CRX file of the Applet Runner extension for self-hosting, you will need to contact us and we will be happy to provide it for you.

You will need to host the extension CRX file in the appropriate location of your IT infrastructure and the file should be accessible via a URL. You will need this DownloadURL later in the tutorial.

About DownloadURL
You can also use the Edge add-ons store DownloadURL, but you won’t be self-hosting the extension and it will be retrieved from the Edge store for all your users. This is a limitation for IT infrastructures where the organisation devices do not have connection permissions to the wider internet. For this reason we recommend the self-hosting method.

The server hosting your extension’s CRX files must employ appropriate HTTP headers to allow users to install the extension through a link. Browsers belonging to the Chromium family (such as Google Chrome and Edge) consider a file installable, if it follows conditions:

  • The file has the content type "application/x-chrome-extension".
  • The file suffix is .crx, and both conditions are met:
    • The file is not served with the HTTP header "X-Content-Type-Options: nosniff".
    • The file is served with one of the specified content types: empty string, "text/plain", "application/octet-stream", "unknown/unknown", "application/unknown" or "/".

To fix an HTTP header issue, either change the configuration of the server or try hosting the .crx file at another server.

The extension ID

The extension ID is a unique identifier and is used to differentiate one extension from another. You can easily retrieve the official ID from the extension URL of Edge’s Add-ons store (last 32 characters):

https://microsoftedge.microsoft.com/addons/detail/cheerpj-applet-runner/ebfcpaoldmijengghefpohddmfpndmic

The extension ID of the official Edge Add-ons store version is:

ebfcpaoldmijengghefpohddmfpndmic

If you want to deploy a custom extension build, the extension ID will be different.

Either we have already provided you with the ID of the CRX file, or else you will first need to manually install the CRX file. To do that, navigate to edge://extensions/ in Edge and enable Developer Mode in the left menu. You can then drag and drop the CRX file onto the page to manually install the extension. You can find the exact steps in our documentation.

After installing the custom build you should be able to retrieve the extension ID of the CRX file.

Edge manage extension page
Example Extension ID
Custom Extension builds all have unique IDs. The version you will be installing will have a different ID than seen on the screenshot.

Manifest XML file

If you want to self host the extension you will need to create an additional manifest.xml file. You can create a file like this with the app/extension ID, download URL, and version, define the following fields:

  • appid - The extension ID from the previous step.
  • codebase - The download URL for the CRX file.
  • version - The version of the app/extension, you can retrieve that from edge://extensions/ again or it was provided by us.

Here is an example of an XML manifest file.

<?xml version='1.0' encoding='UTF-8'?>
<gupdate xmlns='http://www.google.com/update2/response' protocol='2.0'>
  <app appid='ebfcpaoldmijengghefpohddmfpndmic'>
  <updatecheck codebase='https://app.somecompany.com/extensionfolder/extension.crx' version='1.0' />
  </app>
</gupdate>

Just like with the CRX file, you will need to host the manifest.xml file and the file should be accessible via a URL. We will need this URL to create the policy string in the next step.

The policy string

Depending on whether you want to install a self-hosted extension or the official one from the Edge store, the string will look different. It will still follow the syntax of ID;PATH.

For extensions hosted in the Edge store use a string such as EXTENSION_ID;https://clients2.google.com/service/update2/crx, where the path points to the offical update URL.

In the case of a self-hosted extension, the path will point to the XML file that we are self-hosting and will resemble something like this ebfcpaoldmijengghefpohddmfpndmic;https://some.path.manifest.xml.

Hypothetical policy string
The example above contains hypothetical URL, please do not use this policy string.

Policy templates

You need to install the Microsoft Edge Administrative template to configure policies for Edge. Please follow this tutorial by Microsoft

Edge policies

Creating a new group policy

Now you have everything you need to create a new GPO, please follow these final steps to create a Group Policy. You can skip this step and just edit an existing one.

  1. Open the Group Policy Management interface
  2. Go to your desired domain and right click to display the options menu.
  3. Click on Create a GPO in this domain, and Link it here…
  4. Name your policy object and hit Ok.

Force-install

You can now configure your Group Policy to force install the extension in all your organisation browsers. To do so, you will need the Policy String from the previous step and follow this force-install tutorial by Microsoft

Additional policies

Depending on your IT infrastructure it might be necessary to enable additionaly policies to allow users to install the a privately hosted extension.

To enable users to install self-hosted extensions, you must include the CRX IDs of the extensions in the ExtensionInstallAllowList policy and specify the URL hosting the CRX file in the ExtensionInstallSources policy.

You can find more information regarding these policies in the official Microsoft Documentation.

Group policy settings

This step is optional and allows you to define additional settings for the Applet Runner Group Policy.

  1. Open the Group Policy Management interface, find the Applet Runner group policy you created previously (or your existing policy) and click Edit.
  2. Find Microsoft Edge > Extensions > Configure Extension management setting policy.
  3. On the right side menu click on Configure Extension management settings.

In this window you can configure all the settings relevant for your organisation when using the Applet runner extension. To do so you need to input the relevant settings in JSON format into the editor. This is done by editing the JSON string shown in the interface using the format:

{ "*": { "FieldKey": "FieldValue" } }

They Key (*) will apply the settings to all extensions or apps under this policy. Remember to use the extension ID for those settings that you want to apply only for the Applet Runner extension.

{ "ExtensionIDHere": { "Setting1": "Value1", "Setting2": "Value2" } }

You can find all the edge specific Group policy settings in the official Microsoft documentation.

Next we will show you some examples of settings that you can configure to further enhance the user experience when using the Applet Runner extension. For example, you can enable the extension on specific URLs by default.

Enable the extension for certain URLs

If you want the Applet Runner extension to be enabled by default on certain URLs, you can use the "runtime_allowed_hosts" setting to achieve this. This way, users won’t need to click the extension icon anymore to enable it.

{ "ExtensionIDHere": { "runtime_allowed_hosts": ["*://an.example.com"] } }

Pin the extension to the toolbar by default

With this setting, users won’t need to manually pin the extension anymore.

{ "ExtensionIDHere": { "toolbar_state": "force_shown" } }

Applet Runner specific settings

These Group Policy settings are specific to the Applet Runner extension and do not originate from Edge itself. They allow you to further configure and customize the behavior of the Applet Runner extension.

Configure clipboard behaviour

"clipboardMode" : "permission" | "system" | "java"

This option allows you to configure how the clipboard will behave. Supported clipboard modes are [java], [system] and [permission]. You can find more information about the clipboard modes in our CheerpJ documentation.

Example:

{ "ExtensionIDHere": { "clipboardMode": "permission" } }

Enable input methods

"enableInputMethods": boolean

When this option is set to true the Applet Runner extension will be able to receive text input from the input method framework of the platform. This is useful to support text input for languages such as Chinese, Japanese and Korean.

Example:

{ "ExtensionIDHere": { "enableInputMethods": true } }

Override browser keyboard shortcuts

"overrideAllShortcuts": boolean

Some applications need to internally handle keyboard shortcuts which are also used by the browser, for example Ctrl+F. Most users expect the standard browser behavior for these shortcuts but the Applet Runner extension does not override them by default. Setting this option to true will override all browser specific keyboard shortcuts.

Example:

{ "ExtensionIDHere": { "overrideAllShortcuts": true } }

Set the license key

"licenseKey": string

This option is for paying enterprise users of the CheerpJ Applet Runner extension to remove the license text seen at the bottom of the Applet loading screen and enable full support of CheerpJ.

Example:

{ "ExtensionIDHere": { "licenseKey": "exampleLicenseString" } }

Set the Tailscale Control Url

"tailscaleControlUrl": string

This option expects a string URL of the Tailscale control plane. The control plane verifies the user’s identity and validates various keys among the connected peers in the network. Only pass this option if you are self-hosting Tailscale, if omitted, it will point to the Tailscale control plane.

Example:

{ "ExtensionIDHere": { "tailscaleControlUrl": "https://my.url.com/" } }

Set Tailscale authentication key

"tailscaleAuthKey": string

This option expects a string that contains a Tailscale auth key. Using auth keys allows one to register new users/devices that are pre-authenticated. You can create an auth key here.

Info
A combination of a user and a device connected to a Tailscale network is called a “node” in Tailscale terminology.

For more information about auth keys visit the Tailscale auth keys documentation.

Example:

{ "ExtensionIDHere": { "tailscaleAuthKey": "AuthKeyStringGoesHere" } }

Update your changes

Once you are happy with your group policy configuration, you can apply these changes to see them reflected on your user’s Edge clients by running the shell command:

Terminal window
 gpupdate

Now your users should be able to see the extension installed in their Edge browser.

Was this page helpful?
Suggest changes
Private hosting (Chrome)