Skip to content

Commit 16e3079

Browse files
epanholzepanholz
committed
Update GPO docs for CJ AR
The old docs had a lot of wrong infotmation in them and were really long. I removed the old private-hosting guides and created two new ones; one for private hosting and one for configuring the extension via policies.
1 parent 439c0aa commit 16e3079

File tree

4 files changed

+299
-511
lines changed

4 files changed

+299
-511
lines changed

‎sites/labs/src/content/docs/cheerpj-applet-runner/04-guides/configure-extension-for-enterprises.mdx

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
---
2+
title: Configure extension for enterprises
3+
description: How to configure the Applet Runner extension for enterprises
4+
---
5+
6+
As an administrator, you can configure browser extensions for Chrome and Edge using the Windows Group Policy Editor or the Windows Registry.
7+
This applies to the CheerpJ Applet Runner extension as well, allowing you to customize the extension to meet your users' needs.
8+
9+
The following steps assume that you have a basic understanding of using Group Policy and editing the Windows Registry.
10+
11+
For more detailed guidance, please refer to the official [Chrome](https://support.google.com/chrome/a/answer/7532015)
12+
and [Edge](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-manage-extensions-policies) documentation on configuring browser extensions for enterprise use.
13+
14+
## The extension ID
15+
16+
The _extension ID_ is a unique identifier used to differentiate one extension from another.
17+
It is required when configuring extensions using the Windows Group Policy Editor or setting them in the registry.
18+
19+
The _extension ID_ of the official **Edge** Add-ons store version is:
20+
21+
```
22+
ebfcpaoldmijengghefpohddmfpndmic
23+
```
24+
25+
The _extension ID_ of the official **Chrome** Webstore version is:
26+
27+
```
28+
bbmolahhldcbngedljfadjlognfaaein
29+
```
30+
31+
If you are self-hosting a custom build of the Applet Runner, the _extension ID_ will differ.
32+
We either provided you with the _extension ID_, or you will need to retrieve it yourself.
33+
To obtain the _extension ID_ for a custom build, drag the CRX file onto your browser's Extensions page.
34+
You can navigate there by clicking the three dots in the top-right corner of the browser and selecting **Extensions**. Once the extension is loaded, you can note the ID.
35+
36+
## Configure with the Group Policies
37+
38+
A common way to configure your extensions is by using the `ExtensionSettings` policy, which includes multiple options for admins to set up extensions for users.
39+
The `ExtensionSettings` policy enables you to configure multiple settings in one place using a JSON string in the Windows Group Policy Editor.
40+
41+
For more information on the ExtensionSettings policy, please refer to the official documentation for [Chrome](https://support.google.com/chrome/a/answer/7532015)
42+
and [Edge](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-manage-extensions-ref-guide).
43+
44+
### Configure `ExtensionsSettings` policy with JSON format
45+
46+
You can access the `ExtensionSettings` policy through the Group Policy Editor. The location of the policy varies depending on the browser you are using.
47+
48+
- **_Edge:_** In the Group Policy Editor, go to **Administrative Templates > Microsoft Edge > Extensions > Configure extension management setting policy**
49+
50+
- **_Chrome:_** In the Group Policy Editor, go to **Administrative Templates > Google > Google Chrome > Extensions > Configure extension management setting policy**
51+
52+
You will need to **enable** the policy and enter the policy string in JSON format as a **single line**. To validate and compress the policy into a single line, use a JSON compression tool.
53+
54+
The policy string should include the _extension ID_ and the different policy settings you want to configure. Here is an example:
55+
56+
```json
57+
{ "ExtensionIDHere": { "Setting1": "Value1", "Setting2": "Value2" } }
58+
```
59+
60+
### Force install the CheerpJ Applet Runner extension
61+
62+
You can use the `ExtensionInstallForcelist` policy to force install an extension, or you can use`ExtensionSettings` policy.
63+
64+
For the `ExtensionSettings` policy, you will need to use the `installation_mode` setting and set it to `force_install`.
65+
You will also need to add `update_url` setting, which specifies where the browser should download the extension from.
66+
For extensions hosted in the official browser's app store, you should use the app store's URLs.
67+
If you are self-hosting your extension, this setting should point to the `manifest.xml` of the extension.
68+
69+
Policy string for **official Chrome** extension:
70+
71+
```json
72+
{
73+
"bbmolahhldcbngedljfadjlognfaaein": {
74+
"installation_mode": "force_install",
75+
"update_url": "https://clients2.google.com/service/update2/crx"
76+
}
77+
}
78+
```
79+
80+
Policy string for **official Edge** extension
81+
82+
```json
83+
{
84+
"ebfcpaoldmijengghefpohddmfpndmic": {
85+
"installation_mode": "force_install",
86+
"update_url": "https://edge.microsoft.com/extensionwebstorebase/v1/crx"
87+
}
88+
}
89+
```
90+
91+
> [!info] Make sure the policy string is in a single line
92+
93+
### Pin the CheerpJ Applet Runner extension to the toolbar
94+
95+
To automatically pin the extension to the toolbar you can use the `ExtensionSettings` policy, the setting property has a differnt name for
96+
[Chrome](https://support.google.com/chrome/a/answer/9867568?hl=en) and [Edge](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-manage-extensions-ref-guide).
97+
98+
Policy string for **official Chrome** extension:
99+
100+
```json
101+
{ "bbmolahhldcbngedljfadjlognfaaein": { "toolbar_pin": "forced_pin" } }
102+
```
103+
104+
Policy string for **official Edge** extension
105+
106+
```json
107+
{ "ebfcpaoldmijengghefpohddmfpndmic": { "toolbar_state": "force_shown" } }
108+
```
109+
110+
## Configuring Extension Settings via Windows Registry (Managed Storage)
111+
112+
The CheerpJ Applet Runner extension supports Chrome Managed Storage, allowing certain settings to be preconfigured via the Windows registry.
113+
114+
These values are read-only in the extension and must be set by an administrator.
115+
116+
### Registry Path
117+
118+
Custom settings must be stored under the following registry path, replacing `<extension-id>` with the extension’s actual ID (see previous [Extension ID](#the-extension-id) section):
119+
120+
- **Chrome**
121+
32-bit Windows
122+
`HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome\3rdparty\extensions\<extension-id>\policy`
123+
64-bit Windows
124+
`HKEY_LOCAL_MACHINE\Software\Wow6432Node\Policies\Google\Chrome\3rdparty\extensions\<extension-id>\policy`
125+
126+
- **Edge**
127+
32-bit Windows
128+
`HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Edge\3rdparty\extensions\<extension-id>\policy`
129+
64-bit Windows
130+
`HKEY_LOCAL_MACHINE\Software\Wow6432Node\Policies\Microsoft\Edge\3rdparty\extensions\<extension-id>\policy`
131+
132+
### Policy Formatting
133+
134+
Each custom setting corresponds to a property defined in the extension’s managed storage schema.
135+
The name, type, and structure of the registry entry must match the schema exactly.
136+
137+
To configure a custom setting, create a new string value under the extension’s policy registry key.
138+
Set the value name to the setting’s name, and set the value data to the appropriate value in the format required by the schema.
139+
140+
### `initOptions`
141+
142+
The `initOptions` setting is used to configure startup options for CheerpJ.
143+
It currently supports the following properties:
144+
[clipboardMode](https://cheerpj.com/docs/reference/cheerpjInit#clipboardmode),
145+
[enableinputmethods](https://cheerpj.com/docs/reference/cheerpjInit#enableinputmethods),
146+
[tailscaleControlUrl](https://cheerpj.com/docs/reference/cheerpjInit#tailscaleloginurlcb),
147+
[tailscaleAuthKey](https://cheerpj.com/docs/reference/cheerpjInit#tailscaleauthkey),
148+
and `overrideAllShortcuts`.
149+
150+
The `overrideAllShortcuts` is a custom option that, when set to `true`, overrides all browser-specific keyboard shortcuts.
151+
152+
The schema is as follows:
153+
154+
```json
155+
"initOptions": {
156+
"type": "object",
157+
"properties": {
158+
"clipboardMode": { "type": "string" },
159+
"enableInputMethods": { "type": "boolean"},
160+
"overrideAllShortcuts": { "type": "boolean" },
161+
"tailscaleControlUrl": { "type": "string"},
162+
"tailscaleAuthKey": { "type": "string"}
163+
}
164+
}
165+
```
166+
167+
Example value for the registry key `initOptions`:
168+
169+
```json
170+
{ "clipboardMode": "permission", "enableInputMethods": false }
171+
```
172+
173+
### `userAgent`
174+
175+
This setting allows you to change the browser’s user agent for pages where the extension is enabled.
176+
Some applets modify their output depending on the user agent being used.
177+
178+
The schema is as follows:
179+
180+
```json
181+
"userAgent": {
182+
"title": "Custom user-agent string and platform",
183+
"type": "object",
184+
"properties": {
185+
"uaString": {"type": "string"},
186+
"platform": {"type": "string"}
187+
}
188+
}
189+
```
190+
191+
Example value for the registry key `userAgent`:
192+
193+
```json
194+
{"uaString":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36","platform":"macOS"}
195+
```
196+
197+
### `licenseToken`
198+
199+
This setting is used to provide the enterprise license token to the extension.
200+
201+
The schema is as follows:
202+
203+
```json
204+
"licenseToken": {
205+
"type": "string"
206+
}
207+
```
208+
209+
Since this setting is a simple string, all you need to do is create a new string key named `licenseToken` and set its value to your provided token.

0 commit comments

Comments
 (0)