Merge pull request #851 from mozilla/samesite

[policy-templates.git] / README.md

diff --git a/README.md b/README.md
index d9bc93ba059b695993d47821e1031ea8da756610..f480238c2ec09ffd42d536d2a454d43171e058f7 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,7 +1,3 @@
-**These policies are in active development and so might contain changes that do not work with current versions of Firefox.**
-
-**You should use the [officially released versions](https://github.com/mozilla/policy-templates/releases) if you are deploying changes.**
-

 Policies can be specified using the [Group Policy templates on Windows](https://github.com/mozilla/policy-templates/tree/master/windows), [Intune on Windows](https://support.mozilla.org/kb/managing-firefox-intune), [configuration profiles on macOS](https://github.com/mozilla/policy-templates/tree/master/mac), or by creating a file called `policies.json`. On Windows, create a directory called `distribution` where the EXE is located and place the file there. On Mac, the file goes into `Firefox.app/Contents/Resources/distribution`.  On Linux, the file goes into `firefox/distribution`, where `firefox` is the installation directory for firefox, which varies by distribution or you can specify system-wide policy by placing the file in `/etc/firefox/policies`.
 
 | Policy Name | Description
 Policies can be specified using the [Group Policy templates on Windows](https://github.com/mozilla/policy-templates/tree/master/windows), [Intune on Windows](https://support.mozilla.org/kb/managing-firefox-intune), [configuration profiles on macOS](https://github.com/mozilla/policy-templates/tree/master/mac), or by creating a file called `policies.json`. On Windows, create a directory called `distribution` where the EXE is located and place the file there. On Mac, the file goes into `Firefox.app/Contents/Resources/distribution`.  On Linux, the file goes into `firefox/distribution`, where `firefox` is the installation directory for firefox, which varies by distribution or you can specify system-wide policy by placing the file in `/etc/firefox/policies`.
 
 | Policy Name | Description


@@ -65,6 +61,8 @@ Policies can be specified using the [Group Policy templates on Windows](https://
 | **[`Homepage`](#homepage)** | Configure the default homepage and how Firefox starts.
 | **[`InstallAddonsPermission`](#installaddonspermission)** | Configure the default extension install policy as well as origins for extension installs are allowed.
 | **[`LegacyProfiles`](#legacyprofiles)** | Disable the feature enforcing a separate profile for each installation.
 | **[`Homepage`](#homepage)** | Configure the default homepage and how Firefox starts.
 | **[`InstallAddonsPermission`](#installaddonspermission)** | Configure the default extension install policy as well as origins for extension installs are allowed.
 | **[`LegacyProfiles`](#legacyprofiles)** | Disable the feature enforcing a separate profile for each installation.

+| **[`LegacySameSiteCookieBehaviorEnabled`](#legacysamesitecookiebehaviorenabled)** | Enable default legacy SameSite cookie behavior setting.
+| **[`LegacySameSiteCookieBehaviorEnabledForDomainList`](#legacysamesitecookiebehaviorenabledfordomainlist)** | Revert to legacy SameSite behavior for cookies on specified sites.

 | **[`LocalFileLinks`](#localfilelinks)** | Enable linking to local files by origin.
 | **[`ManagedBookmarks`](#managedbookmarks)** | Configures a list of bookmarks managed by an administrator that cannot be changed by the user.
 | **[`ManualAppUpdateOnly`](#manualappupdateonly)** | Allow manual updates only and do not notify the user about updates..
 | **[`LocalFileLinks`](#localfilelinks)** | Enable linking to local files by origin.
 | **[`ManagedBookmarks`](#managedbookmarks)** | Configures a list of bookmarks managed by an administrator that cannot be changed by the user.
 | **[`ManualAppUpdateOnly`](#manualappupdateonly)** | Allow manual updates only and do not notify the user about updates..


@@ -90,10 +88,10 @@ Policies can be specified using the [Group Policy templates on Windows](https://
 | **[`SanitizeOnShutdown` (Selective)](#sanitizeonshutdown-selective)** | Clear data on shutdown.
 | **[`SearchBar`](#searchbar)** | Set whether or not search bar is displayed.
 | **[`SearchEngines`](#searchengines-this-policy-is-only-available-on-the-esr)** |
 | **[`SanitizeOnShutdown` (Selective)](#sanitizeonshutdown-selective)** | Clear data on shutdown.
 | **[`SearchBar`](#searchbar)** | Set whether or not search bar is displayed.
 | **[`SearchEngines`](#searchengines-this-policy-is-only-available-on-the-esr)** |

+| **[`SearchEngines -> Add`](#searchengines--add)** | Add new search engines.

 | **[`SearchEngines -> Default`](#searchengines--default)** | Set the default search engine.
 | **[`SearchEngines -> PreventInstalls`](#searchengines--preventinstalls)** | Prevent installing search engines from webpages.
 | **[`SearchEngines -> Remove`](#searchengines--remove)** | Hide built-in search engines.
 | **[`SearchEngines -> Default`](#searchengines--default)** | Set the default search engine.
 | **[`SearchEngines -> PreventInstalls`](#searchengines--preventinstalls)** | Prevent installing search engines from webpages.
 | **[`SearchEngines -> Remove`](#searchengines--remove)** | Hide built-in search engines.

-| **[`SearchEngines -> Add`](#searchengines--add)** | Add new search engines.

 | **[`SearchSuggestEnabled`](#searchsuggestenabled)** | Enable search suggestions.
 | **[`SecurityDevices`](#securitydevices)** | Install PKCS #11 modules.
 | **[`ShowHomeButton`](#showhomebutton)** | Show the home button on the toolbar.
 | **[`SearchSuggestEnabled`](#searchsuggestenabled)** | Enable search suggestions.
 | **[`SecurityDevices`](#securitydevices)** | Install PKCS #11 modules.
 | **[`ShowHomeButton`](#showhomebutton)** | Show the home button on the toolbar.


@@ -108,86 +106,86 @@ Policies can be specified using the [Group Policy templates on Windows](https://
 
 Allow WebExtensions to configure policy. For more information, see [Adding policy support to your extension](https://extensionworkshop.com/documentation/enterprise/adding-policy-support-to-your-extension/).
 
 
 Allow WebExtensions to configure policy. For more information, see [Adding policy support to your extension](https://extensionworkshop.com/documentation/enterprise/adding-policy-support-to-your-extension/).
 

-### AppAutoUpdate
-
-Enable or disable **automatic** application update.
+### AllowedDomainsForApps

 
 

-If set to true, application updates are installed without user approval within Firefox. The operating system might still require approval.
+Define domains allowed to access Google Workspace.

 
 

-If set to false, application updates are downloaded but the user can choose when to install the update.
+This policy is based on the [Chrome policy](https://chromeenterprise.google/policies/#AllowedDomainsForApps) of the same name.

 
 

-If you have disabled updates via `DisableAppUpdate`, this policy has no effect.
+If this policy is enabled, users can only access Google Workspace using accounts from the specified domains. If you want to allow Gmail, you can add ```consumer_accounts``` to the list.

 
 

-**Compatibility:** Firefox 75, Firefox ESR 68.7\
+**Compatibility:** Firefox 89, Firefox ESR 78.11\

 **CCK2 Equivalent:** N/A\
 **CCK2 Equivalent:** N/A\

-**Preferences Affected:** `app.update.auto`
+**Preferences Affected:** N/A

 
 #### Windows (GPO)
 ```
 
 #### Windows (GPO)
 ```

-Software\Policies\Mozilla\Firefox\AppAutoUpdate = 0x1 | 0x0
+Software\Policies\Mozilla\Firefox\AllowedDomainsForApps = "managedfirefox.com,example.com"

 ```
 #### Windows (Intune)
 OMA-URI:
 ```
 ```
 #### Windows (Intune)
 OMA-URI:
 ```

-./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/AppAutoUpdate
+./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/AllowedDomainsForApps

 ```
 Value (string):
 ```
 ```
 Value (string):
 ```

-<enabled/> or <disabled/>
+<enabled/>
+<data id="AllowedDomainsForApps" value="managedfirefox.com,example.com"/>

 ```
 #### macOS
 ```
 <dict>
 ```
 #### macOS
 ```
 <dict>

-  <key>AppAutoUpdate</key>
-  <true/> | <false/>
+  <key>AllowedDomainsForApps</key>
+  <string>managedfirefox.com,example.com</string>

 </dict>
 ```
 #### policies.json
 ```
 {
   "policies": {
 </dict>
 ```
 #### policies.json
 ```
 {
   "policies": {

-    "AppAutoUpdate": true | false
+    "AllowedDomainsForApps": "managedfirefox.com,example.com"

   }
 }
 ```
   }
 }
 ```

-### AllowedDomainsForApps
+### AppAutoUpdate

 
 

-Define domains allowed to access Google Workspace.
+Enable or disable **automatic** application update.

 
 

-This policy is based on the [Chrome policy](https://chromeenterprise.google/policies/#AllowedDomainsForApps) of the same name.
+If set to true, application updates are installed without user approval within Firefox. The operating system might still require approval.

 
 

-If this policy is enabled, users can only access Google Workspace using accounts from the specified domains. If you want to allow Gmail, you can add ```consumer_accounts``` to the list.
+If set to false, application updates are downloaded but the user can choose when to install the update.

 
 

-**Compatibility:** Firefox 89, Firefox ESR 78.11\
+If you have disabled updates via `DisableAppUpdate`, this policy has no effect.
+
+**Compatibility:** Firefox 75, Firefox ESR 68.7\

 **CCK2 Equivalent:** N/A\
 **CCK2 Equivalent:** N/A\

-**Preferences Affected:** N/A
+**Preferences Affected:** `app.update.auto`

 
 #### Windows (GPO)
 ```
 
 #### Windows (GPO)
 ```

-Software\Policies\Mozilla\Firefox\AllowedDomainsForApps = "managedfirefox.com,example.com"
+Software\Policies\Mozilla\Firefox\AppAutoUpdate = 0x1 | 0x0

 ```
 #### Windows (Intune)
 OMA-URI:
 ```
 ```
 #### Windows (Intune)
 OMA-URI:
 ```

-./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/AllowedDomainsForApps
+./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/AppAutoUpdate

 ```
 Value (string):
 ```
 ```
 Value (string):
 ```

-<enabled/>
-<data id="AllowedDomainsForApps" value="managedfirefox.com,example.com"/>
+<enabled/> or <disabled/>

 ```
 #### macOS
 ```
 <dict>
 ```
 #### macOS
 ```
 <dict>

-  <key>AllowedDomainsForApps</key>
-  <string>managedfirefox.com,example.com</string>
+  <key>AppAutoUpdate</key>
+  <true/> | <false/>

 </dict>
 ```
 #### policies.json
 ```
 {
   "policies": {
 </dict>
 ```
 #### policies.json
 ```
 {
   "policies": {

-    "AllowedDomainsForApps": "managedfirefox.com,example.com"
+    "AppAutoUpdate": true | false

   }
 }
 ```
   }
 }
 ```


@@ -891,19 +889,32 @@ Configure cookie preferences.
 
 `Block` is a list of origins (not domains) where cookies are always blocked. You must include http or https.
 
 
 `Block` is a list of origins (not domains) where cookies are always blocked. You must include http or https.
 

-`Default` determines whether cookies are accepted at all.
+`Behavior` sets the default behavior for cookies based on the values below.
+
+`BehaviorPrivateBrowsing` sets the default behavior for cookies in private browsing based on the values below.

 
 

-`AcceptThirdParty` determines how third-party cookies are handled.
+| Value | Description
+| --- | ---
+| accept | Accept all cookies
+| reject-foreign | Reject third party cookies
+| reject | Reject all cookies
+| limit-foreign | Reject third party cookies for sites you haven't visited
+| reject-tracker | Reject cookies for known trackers (default)
+| reject-tracker-and-partition-foreign | Reject cookies for known trackers and partition third-party cookies (Total Cookie Protection) (default for private browsing)
+
+`Default` (Deprecated) determines whether cookies are accepted at all.
+
+`AcceptThirdParty` (Deprecated) determines how third-party cookies are handled.

 
 `ExpireAtSessionEnd` determines when cookies expire.
 
 
 `ExpireAtSessionEnd` determines when cookies expire.
 

-`RejectTracker` only rejects cookies for trackers.
+`RejectTracker` (Deprecated) only rejects cookies for trackers.

 
 `Locked` prevents the user from changing cookie preferences.
 
 
 `Locked` prevents the user from changing cookie preferences.
 

-**Compatibility:** Firefox 60, Firefox ESR 60 (RejectTracker added in Firefox 63, AllowSession added in Firefox 79/78.1)\
+**Compatibility:** Firefox 60, Firefox ESR 60 (RejectTracker added in Firefox 63, AllowSession added in Firefox 79/78.1, Behavior added in Firefox 95/91.4)\

 **CCK2 Equivalent:** N/A\
 **CCK2 Equivalent:** N/A\

-**Preferences Affected:** `network.cookie.cookieBehavior`, `network.cookie.lifetimePolicy`
+**Preferences Affected:** `network.cookie.cookieBehavior`, `network.cookie.cookieBehavior.pbmode`, `network.cookie.lifetimePolicy`

 
 #### Windows (GPO)
 ```
 
 #### Windows (GPO)
 ```


@@ -914,6 +925,8 @@ Software\Policies\Mozilla\Firefox\Cookies\Default = 0x1 | 0x0
 Software\Policies\Mozilla\Firefox\Cookies\AcceptThirdParty = "always" | "never" | "from-visited"
 Software\Policies\Mozilla\Firefox\Cookies\ExpireAtSessionEnd = 0x1 | 0x0
 Software\Policies\Mozilla\Firefox\Cookies\RejectTracker = 0x1 | 0x0
 Software\Policies\Mozilla\Firefox\Cookies\AcceptThirdParty = "always" | "never" | "from-visited"
 Software\Policies\Mozilla\Firefox\Cookies\ExpireAtSessionEnd = 0x1 | 0x0
 Software\Policies\Mozilla\Firefox\Cookies\RejectTracker = 0x1 | 0x0

+Software\Policies\Mozilla\Firefox\Cookies\Behavior = "accept" | "reject-foreign" | "reject" | "limit-foreign" | "reject-tracker" | "reject-tracker-and-partition-foreign"
+Software\Policies\Mozilla\Firefox\Cookies\BehaviorPrivateBrowsing = "accept" | "reject-foreign" | "reject" | "limit-foreign" | "reject-tracker" | "reject-tracker-and-partition-foreign"

 Software\Policies\Mozilla\Firefox\Cookies\Locked = 0x1 | 0x0
 ```
 #### Windows (Intune)
 Software\Policies\Mozilla\Firefox\Cookies\Locked = 0x1 | 0x0
 ```
 #### Windows (Intune)


@@ -985,6 +998,24 @@ Value (string):
 ```
 <enabled/> or <disabled/>
 ```
 ```
 <enabled/> or <disabled/>
 ```

+OMA-URI:
+```
+./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox~Cookies/Cookies_Behavior
+```
+Value (string):
+```
+<enabled/>
+<data id="Cookies_Behavior" value="accept | reject-foreign | reject | limit-foreign | reject-tracker | reject-tracker-and-partition-foreign"/>
+```
+OMA-URI:
+```
+./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox~Cookies/Cookies_BehaviorPrivateBrowsing
+```
+Value (string):
+```
+<enabled/>
+<data id="Cookies_BehaviorPrivateBrowsing" value="accept | reject-foreign | reject | limit-foreign | reject-tracker | reject-tracker-and-partition-foreign"/>
+```

 #### macOS
 ```
 <dict>
 #### macOS
 ```
 <dict>


@@ -1012,6 +1043,10 @@ Value (string):
     <true/> | <false/>
     <key>Locked</key>
     <true/> | <false/>
     <true/> | <false/>
     <key>Locked</key>
     <true/> | <false/>

+    <key>Behavior</key>
+    <string>accept | reject-foreign | reject | limit-foreign | reject-tracker | reject-tracker-and-partition-foreign</string>
+    <key>BehaviorPrivateBrowsing</key>
+    <string>accept | reject-foreign | reject | limit-foreign | reject-tracker | reject-tracker-and-partition-foreign</string>

   </dict>
 </dict>
 ```
   </dict>
 </dict>
 ```


@@ -1027,7 +1062,9 @@ Value (string):
       "AcceptThirdParty": "always" | "never" | "from-visited",
       "ExpireAtSessionEnd": true | false,
       "RejectTracker": true | false,
       "AcceptThirdParty": "always" | "never" | "from-visited",
       "ExpireAtSessionEnd": true | false,
       "RejectTracker": true | false,

-      "Locked": true | false
+      "Locked": true | false,
+      "Behavior": "accept" | "reject-foreign" | "reject" | "limit-foreign" | "reject-tracker" | "reject-tracker-and-partition-foreign",
+      "BehaviorPrivateBrowsing": "accept" | "reject-foreign" | "reject" | "limit-foreign" | "reject-tracker" | "reject-tracker-and-partition-foreign",

     }
   }
 }
     }
   }
 }


@@ -3172,6 +3209,85 @@ Value (string):
 ```
 <enabled/> or <disabled/>
 ```
 ```
 <enabled/> or <disabled/>
 ```

+### LegacySameSiteCookieBehaviorEnabled
+Enable default legacy SameSite cookie behavior setting.
+
+If this policy is set to true, it reverts all cookies to legacy SameSite behavior which means that cookies that don't explicitly specify a ```SameSite``` attribute are treated as if they were ```SameSite=None```.
+
+**Compatibility:** Firefox 96\
+**CCK2 Equivalent:** N/A\
+**Preferences Affected:** `network.cookie.sameSite.laxByDefault`
+
+#### Windows (GPO)
+```
+Software\Policies\Mozilla\Firefox\LegacySameSiteCookieBehaviorEnabled = = 0x1 | 0x0
+```
+#### Windows (Intune)
+OMA-URI:
+```
+./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/LegacySameSiteCookieBehaviorEnabled
+```
+Value (string):
+```
+<enabled/> or <disabled/>
+```
+#### macOS
+```
+<dict>
+  <key>LegacySameSiteCookieBehaviorEnabled</key>
+  <true/> | <false/>
+</dict>
+```
+#### policies.json
+```
+{
+  "policies": {
+    "LegacySameSiteCookieBehaviorEnabled": true | false
+}
+```
+### LegacySameSiteCookieBehaviorEnabledForDomainList
+Revert to legacy SameSite behavior for cookies on specified sites.
+
+If this policy is set to true, cookies set for domains in this list will revert to legacy SameSite behavior which means that cookies that don't explicitly specify a ```SameSite``` attribute are treated as if they were ```SameSite=None```.
+
+**Compatibility:** Firefox 96\
+**CCK2 Equivalent:** N/A\
+**Preferences Affected:** `network.cookie.sameSite.laxByDefault.disabledHosts`
+
+#### Windows (GPO)
+```
+Software\Policies\Mozilla\Firefox\LegacySameSiteCookieBehaviorEnabledForDomainList\1 = "example.org"
+Software\Policies\Mozilla\Firefox\LegacySameSiteCookieBehaviorEnabledForDomainList\2 = "example.edu"
+```
+#### Windows (Intune)
+OMA-URI:
+```
+./Device/Vendor/MSFT/Policy/Config/Firefox~Policy~firefox/LegacySameSiteCookieBehaviorEnabledForDomainList
+```
+Value (string):
+```
+<enabled/>
+<data id="LegacySameSiteCookieBehaviorEnabledForDomainList" value="1&#xF000;example.org&#xF000;2&#xF000;example.edu"/>
+```
+#### macOS
+```
+<dict>
+  <key>LegacySameSiteCookieBehaviorEnabledForDomainList</key>
+  <array>
+    <string>example.org</string>
+    <string>example.edu</string>
+  </array>
+</dict>
+```
+#### policies.json
+```
+{
+  "policies": {
+    "LegacySameSiteCookieBehaviorEnabledForDomainList": ["example.org",
+                                                         "example.edu"]
+  }
+}
+```

 ### LocalFileLinks
 Enable linking to local files by origin.
 
 ### LocalFileLinks
 Enable linking to local files by origin.
 


@@ -4190,7 +4306,7 @@ as well as the following security preferences:
 | security.tls.version.enable-deprecated | boolean | false
 | &nbsp;&nbsp;&nbsp;&nbsp;If true, browser will accept TLS 1.0. and TLS 1.1 (Firefox 86, Firefox 78.8).
 | security.warn_submit_secure_to_insecure | boolean | true
 | security.tls.version.enable-deprecated | boolean | false
 | &nbsp;&nbsp;&nbsp;&nbsp;If true, browser will accept TLS 1.0. and TLS 1.1 (Firefox 86, Firefox 78.8).
 | security.warn_submit_secure_to_insecure | boolean | true

-| &nbsp;&nbsp;&nbsp;&nbsp;If false, no warning is shown when submitting s form from https to http.
+| &nbsp;&nbsp;&nbsp;&nbsp;If false, no warning is shown when submitting a form from https to http.

 &nbsp;
 
 Using the preference as the key, set the `Value` to the corresponding preference value.
 &nbsp;
 
 Using the preference as the key, set the `Value` to the corresponding preference value.


@@ -4201,7 +4317,7 @@ Default preferences can be modified by the user.
 
 If a value is locked, it is also set as the default.
 
 
 If a value is locked, it is also set as the default.
 

-User preferences persist across invocations of Firefox. It is the equivalent of a user setting the preference. They are most useful when a preference is needed very early in startup so it can't be set as default by policy.
+User preferences persist across invocations of Firefox. It is the equivalent of a user setting the preference. They are most useful when a preference is needed very early in startup so it can't be set as default by policy. An example of this is ```toolkit.legacyUserProfileCustomizations.stylesheets```.

 
 User preferences persist even if the policy is removed, so if you need to remove them, you should use the clear policy.
 
 
 User preferences persist even if the policy is removed, so if you need to remove them, you should use the clear policy.
 


@@ -5415,7 +5531,7 @@ Prevent Firefox from messaging the user in certain situations.
 
 `ExtensionRecommendations` If false, don't recommend extensions while the user is visiting web pages.
 
 
 `ExtensionRecommendations` If false, don't recommend extensions while the user is visiting web pages.
 

-`FeatureRecommendations` IF false, don't recommend browser features.
+`FeatureRecommendations` If false, don't recommend browser features.

 
 `UrlbarInterventions` If false, Don't offer Firefox specific suggestions in the URL bar.
 
 
 `UrlbarInterventions` If false, Don't offer Firefox specific suggestions in the URL bar.