Document Firefox uBlock configuration

README.fr.md

@@ -96,6 +96,8 @@ powershell -ExecutionPolicy Bypass -File .\powershell\Configure-FirefoxDefaults.
 
 Le script écrit les policies Firefox, force l'installation de uBlock Origin depuis Mozilla Add-ons, configure les paramètres gérés de uBlock Origin et importe les associations d'applications Windows par défaut pour les futurs utilisateurs.
 
+Documentation détaillée : [configuration Firefox ESR et uBlock Origin](./docs/firefox-ublock.md).
+
 ## 🧹 Supprimer des Applications Intégrées
 
 Utilise le script de nettoyage Appx pour supprimer certaines applications intégrées sans winget et limiter leur reprovisionnement pour les nouveaux utilisateurs.

README.md

@@ -96,6 +96,8 @@ powershell -ExecutionPolicy Bypass -File .\powershell\Configure-FirefoxDefaults.
 
 The script writes Firefox enterprise policies, force-installs uBlock Origin from Mozilla Add-ons, configures managed uBlock Origin defaults and imports Windows default app associations for future users.
 
+More details: [Firefox ESR and uBlock Origin configuration](./docs/firefox-ublock.md).
+
 ## 🧹 Remove Built-In Apps
 
 Use the Appx cleanup script when you want to remove selected built-in applications without winget and reduce reprovisioning for newly created users.

docs/firefox-ublock.md

@@ -0,0 +1,210 @@
+# Configuration Firefox ESR et uBlock Origin
+
+Cette page documente la configuration appliquee par
+[`powershell/Configure-FirefoxDefaults.ps1`](../powershell/Configure-FirefoxDefaults.ps1).
+
+Le but est de preparer Firefox ESR pour tous les utilisateurs Windows, y compris
+les futurs profils :
+
+- Firefox ESR devient le navigateur par defaut pour `.htm`, `.html`, `http` et `https`.
+- uBlock Origin est installe automatiquement depuis Mozilla Add-ons.
+- uBlock Origin recoit une configuration geree commune a tous les profils Firefox.
+
+## Execution
+
+Lance le script dans un terminal PowerShell administrateur, apres installation de
+Firefox ESR :
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\powershell\Configure-FirefoxDefaults.ps1
+```
+
+Le script est aussi appele automatiquement par
+[`powershell/libres-softwares-install.ps1`](../powershell/libres-softwares-install.ps1)
+quand Firefox ESR est installe via l'installateur interactif.
+
+## Fichiers et cles crees
+
+Le script ecrit un fichier `policies.json` dans le dossier d'installation Firefox :
+
+```text
+C:\Program Files\Mozilla Firefox\distribution\policies.json
+```
+
+Selon l'installation, le dossier peut etre sous `Program Files (x86)`.
+
+Le script ecrit aussi un fichier XML d'associations Windows :
+
+```text
+C:\ProgramData\WindowsLibreSoftwareToolkit\FirefoxDefaultAssociations.xml
+```
+
+Puis il configure la policy Windows :
+
+```text
+HKLM\SOFTWARE\Policies\Microsoft\Windows\System
+  DefaultAssociationsConfiguration
+```
+
+Enfin, il importe les associations par defaut pour les futurs utilisateurs avec :
+
+```powershell
+dism.exe /Online /Import-DefaultAppAssociations:C:\ProgramData\WindowsLibreSoftwareToolkit\FirefoxDefaultAssociations.xml
+```
+
+## Policies Firefox
+
+Firefox lit les policies machine au demarrage. Le fichier `policies.json` genere
+contient principalement :
+
+```json
+{
+  "policies": {
+    "DontCheckDefaultBrowser": true,
+    "DisableDefaultBrowserAgent": true,
+    "ExtensionSettings": {
+      "uBlock0@raymondhill.net": {
+        "installation_mode": "force_installed",
+        "install_url": "https://addons.mozilla.org/firefox/downloads/latest/ublock-origin/latest.xpi"
+      }
+    }
+  }
+}
+```
+
+`ExtensionSettings` force l'installation de uBlock Origin pour chaque profil
+Firefox. Si l'extension est supprimee ou absente, Firefox la reinstalle au
+demarrage suivant.
+
+L'identifiant officiel de l'extension Firefox est :
+
+```text
+uBlock0@raymondhill.net
+```
+
+## Configuration geree uBlock Origin
+
+La configuration uBlock Origin passe par la policy Firefox `3rdparty`.
+Firefox expose ensuite ces valeurs a l'extension via `storage.managed`.
+
+Extrait simplifie :
+
+```json
+{
+  "policies": {
+    "3rdparty": {
+      "Extensions": {
+        "uBlock0@raymondhill.net": {
+          "adminSettings": {
+            "selectedFilterLists": [
+              "user-filters",
+              "ublock-filters",
+              "ublock-badware",
+              "ublock-privacy",
+              "ublock-abuse",
+              "ublock-unbreak",
+              "ublock-quick-fixes",
+              "easylist",
+              "easyprivacy",
+              "urlhaus-1",
+              "plowe-0"
+            ],
+            "userSettings": {
+              "advancedUserEnabled": false,
+              "cloudStorageEnabled": false,
+              "contextMenuEnabled": true,
+              "showIconBadge": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Listes de filtres activees
+
+| Liste | Role |
+| --- | --- |
+| `user-filters` | Reserve les filtres utilisateur. |
+| `ublock-filters` | Filtres principaux uBlock Origin. |
+| `ublock-badware` | Protection contre domaines malveillants. |
+| `ublock-privacy` | Protection vie privee. |
+| `ublock-abuse` | Protection contre abus et nuisances. |
+| `ublock-unbreak` | Corrections de compatibilite. |
+| `ublock-quick-fixes` | Correctifs rapides publies par uBlock Origin. |
+| `easylist` | Liste anti-publicite generaliste. |
+| `easyprivacy` | Liste anti-tracking generaliste. |
+| `urlhaus-1` | Blocage de domaines malveillants URLhaus. |
+| `plowe-0` | Liste de blocage complementaire. |
+
+## Parametres utilisateur imposes
+
+| Parametre | Valeur | Effet |
+| --- | --- | --- |
+| `advancedUserEnabled` | `false` | Desactive le mode utilisateur avance. |
+| `cloudStorageEnabled` | `false` | Desactive la synchronisation cloud uBlock. |
+| `contextMenuEnabled` | `true` | Garde le menu contextuel uBlock disponible. |
+| `showIconBadge` | `true` | Affiche le badge de compteur sur l'icone. |
+
+## Firefox navigateur par defaut
+
+Windows ne permet pas de forcer proprement le navigateur par defaut en modifiant
+simplement le registre utilisateur. Le script utilise donc la methode
+administrateur standard :
+
+1. lire les ProgID Firefox dans le registre ;
+2. generer un XML `DefaultAssociations` ;
+3. definir la policy `DefaultAssociationsConfiguration` ;
+4. importer le XML avec DISM pour les futurs profils.
+
+Les associations configurees sont :
+
+| Identifiant | Application |
+| --- | --- |
+| `.htm` | Firefox |
+| `.html` | Firefox |
+| `http` | Firefox |
+| `https` | Firefox |
+
+## Verification
+
+Pour verifier les policies Firefox :
+
+1. ouvre Firefox ;
+2. va sur `about:policies` ;
+3. verifie l'onglet `Active`.
+
+Pour verifier uBlock Origin :
+
+1. ouvre Firefox avec un nouveau profil utilisateur Windows ;
+2. va sur `about:addons` ;
+3. verifie que uBlock Origin est present ;
+4. ouvre le tableau de bord uBlock Origin ;
+5. verifie que les listes de filtres attendues sont selectionnees.
+
+Pour verifier les associations Windows :
+
+```powershell
+dism.exe /Online /Get-DefaultAppAssociations
+```
+
+## Limites
+
+Les associations importees par DISM ciblent les futurs profils Windows. Un profil
+deja cree peut conserver ses associations existantes.
+
+Firefox doit etre installe avant l'execution du script, sinon les ProgID Firefox
+peuvent etre absents.
+
+uBlock Origin est telecharge par Firefox depuis Mozilla Add-ons au demarrage. La
+machine doit donc avoir acces a `addons.mozilla.org`.
+
+## Sources
+
+- Mozilla Firefox policies : <https://firefox-admin-docs.mozilla.org/guides/policies-configuration/>
+- Mozilla `ExtensionSettings` : <https://firefox-admin-docs.mozilla.org/reference/policies/extensionsettings/>
+- Mozilla `3rdparty` policies : <https://firefox-admin-docs.mozilla.org/reference/policies/3rdparty/>
+- Mozilla Firefox default browser enterprise : <https://support.mozilla.org/en-US/kb/make-firefox-enterprise-default-browser>
+- Microsoft DISM default app associations : <https://learn.microsoft.com/windows-hardware/manufacture/desktop/dism-default-application-association-servicing-command-line-options>