Inhaltsverzeichnis Vorheriger Eintrag (settings:content_script_api)

Overview

This document describes how to deploy Tampermonkey in a managed environment. It covers both installing the extension and centrally provisioning scripts and settings using managed browser policies.

The deployment approach is supported by:

• Chromium-based browsers (Chrome, Chromium, Edge, Brave, etc.)
• Firefox (desktop, non-mobile)

The configuration itself is provided as a JSON export from a preconfigured Tampermonkey installation and fetched by managed Tampermonkey instances at startup. This requires version 5.5+ or 5.5.6235+ (BETA).

Deployment consists of three steps:

1. Install Tampermonkey via browser policy (force-installed)
2. Host a provisioning JSON file (exported from Tampermonkey)
3. Configure browser policies so Tampermonkey imports that JSON via managed storage

The provisioning file can include:

• Userscripts
• Script storage
• Tampermonkey settings
• External script resources

Creating the Provisioning JSON

Tampermonkey provides a built-in export mechanism.

Export Steps

1. Open Tampermonkey
2. Dashboard → Utilities
3. Enable:
   • Include script storage
   • Include Tampermonkey settings
   • Include external script resources
4. In the File section, click Export

The resulting file (for example tm.json) is the provisioning source used by the browsers.

Example tm.json

{
  "version": "1",
  "scripts": [
    {
      "name": "Log location",
      "enabled": true,
      "position": 1,
      "uuid": "4190fc63-64c8-4c68-9a7c-96f41f85729a",
      "source": "Ly8gPT1Vc2VyU2NyaXB0PT0KLy8gQG5[...]sb2cobG9jYXRpb24uaHJlZik7",
      "requires": [
        {
          "meta": { "name": "jquery-3.4.1.min.js", "url": "https://code.jquery.com/jquery-3.4.1.min.js", "mimetype": "application/javascript" },
          "source": "Ly8ganF1ZXJ5IHN0dWIKdmFyIGpkVjMgPSAxOw=="
        }
      ]
    }
  ],
  "settings": {
    "configMode": 100,
    "logLevel": 80
  }
}

Host this file on an internal web server, for example:

php -S localhost:12121 -t .

In production mode – Use a real web server (Apache, Nginx, IIS, …) that serves the file over HTTPS with a valid certificate.

Hash Handling

Each provisioning entry requires a content hash to guarantee integrity. If the hash does not match, Tampermonkey logs an error similar to:

Error: Hash mismatch for provisioning jsonImport from http://localhost:12121/tm.json:
    expected 1:abcd... !== calculated 1:ef01...

The correct hash is shown in the error output (calculated …). Copy that value into the policy configuration. A dedicated hash helper tool is planned.

Managed Storage Schema

Tampermonkey reads its managed configuration from the browser. Relevant schema excerpt:

{
  "jsonImport": [
    {
      "hash": "1:…",
      "url": "https://example.com/tm.json",
      "haltOnError": true,
      "installAsSystemScripts": false
    }
  ]
}

Fields

• hash (required): integrity hash of the JSON file
• url (required): HTTPS or HTTP URL to the JSON file
• haltOnError: abort provisioning on error (Tampermonkey will not start at all in case of an error)
• installAsSystemScripts: install scripts as system scripts (default: true)

Duplicated Scripts

Tampermonkey identifies provisioned scripts by the uuid value stored in the export. Re-provisioning a document whose scripts keep the same UUID — the normal case when you re-export from the same preconfigured installation — updates the existing provisioned scripts in place instead of creating a second copy.

The following still apply:

• If a user has already installed the same script manually under a different UUID, both entries appear in the script list (the user's copy and the provisioned one) and both will run.
• A script that is removed from the provisioning JSON, or whose UUID changed (for example after re-exporting from a different machine), is not automatically deleted from already-provisioned browsers; its old copy remains until removed.

To avoid confusion for users, instruct them to remove the manually installed copies and keep the provisioned one (a system script by default, see installAsSystemScripts).

Extension IDs

See Q406 in the FAQ for Tampermonkey's extension IDs.

Firefox Deployment

Firefox supports managed extension configuration via policies.json.

Policies can be inspected at:

• about:policies

C:\Program Files\Mozilla Firefox\

C:\Program Files\Mozilla Firefox\distribution\

C:\Program Files\Mozilla Firefox\distribution\policies.json

Firefox.app/Contents/Resources/distribution/policies.json

{
  "policies": {
    "Extensions": {
      "Install": [
        "https://www.tampermonkey.net/xpi/firefox-current-beta.xpi"
      ]
    },
    "3rdparty": {
      "Extensions": {
        "firefoxbeta@tampermonkey.net": {
          "jsonImport": [
            {
              "hash": "1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0",
              "url": "http://localhost:12121/tm.json",
              "haltOnError": true,
              "installAsSystemScripts": false
            }
          ]
        }
      }
    }
  }
}

Mozilla policy documentation:

• https://mozilla.github.io/policy-templates/#extensions

Chromium-Based Browsers

Policies can be inspected at:

• chrome://policy/
• edge://policy/

Windows Registry Editor Version 5.00

; Force-install Tampermonkey (if not already installed)
[HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome\ExtensionInstallForcelist]
"1"="gcalenpjmijncebpfijmoaglllgpjagf"

; 3rd-party policy for the extension
[HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome\3rdparty\extensions\gcalenpjmijncebpfijmoaglllgpjagf\jsonImport\1]
"hash"="1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0"
"url"="http://localhost:12121/tm.json"
"haltOnError"=dword:00000001
"installAsSystemScripts"=dword:00000000

{
  "ExtensionInstallForcelist": [
    "gcalenpjmijncebpfijmoaglllgpjagf"
  ],
  "3rdparty": {
    "extensions": {
      "gcalenpjmijncebpfijmoaglllgpjagf": {
        "jsonImport": [
          {
            "hash": "1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0",
            "url": "http://localhost:12121/tm.json",
            "haltOnError": true,
            "installAsSystemScripts": false
          }
        ]
      }
    }
  }
}

Google Workspace (Chrome Admin Console)

Google Workspace customers can deploy the policy via the Chrome Admin Console instead of local policy files:

1. Open Chrome browser → Apps & extensions → Policy for extensions
2. Select the Tampermonkey extension ID (see Q406)
3. Enter the 3rd-party policy value:

{
  "jsonImport": {
    "Value": [
      {
        "hash": "1:66849534c66c5bd384f39f7fb5c7c5bdbc8611bfedab082762cb943f853637d0",
        "url": "https://example.com/tm.json",
        "haltOnError": true,
        "installAsSystemScripts": false
      }
    ]
  }
}

Note the "Value": [...] wrapper around the list: the Admin Console requires list-type policy values to be wrapped in a Value object. This is the only difference from the local policy files shown above.

Chromium documentation:

• https://www.chromium.org/administrators/configuring-policy-for-extensions/
• https://chromeenterprise.google/policies/#ExtensionInstallForcelist