Policy Settings in Chrome

Adding new policy settings

This section describes the steps to add a new policy setting to Chromium, which administrators can then configure via Windows Group Policy, the Google Apps control panel, etc. Administrator documentation about for setting up Chrome management is here if you're looking for information on how to deploy policy settings to Chrome.

Wire the feature you want to be controlled by policy to PrefService, so a pref can be used to control your feature's behavior in the desired way.

For existing command line switches that are being turned into policy, you will want to modify the CommandLinePrefStore in chrome/browser/prefs/command_line_pref_store.cc to set the property appropriately from the command line switch (the managed policy will override this value from the command line automagically when policy is set if you do it this way).

Add a policy to control the pref:

components/policy/resources/policy_templates.json - This file contains meta-level descriptions of all policies and is used to generated code, policy templates (ADM/ADMX for windows and the application manifest for Mac), as well as documentation. When adding your policy, please make sure you get the version and features flags (such as dynamic_refresh and supported_on) right, since this is what will later appear on http://dev.chromium.org/administrators/policy-list-3. The textual policy description should include the following:

What features of Chrome are affected

Which behavior and/or UI/UX changes the policy triggers

How the policy behaves if it's left unset or set to invalid/default values. This may seem obvious to you, and it probably is. However, this information seems to be provided for Windows Group Policy traditionally, and we've seen requests from organizations to explicitly spell out the behavior for all possible values and for when the policy is unset.

If your feature can be controlled by GUI in chrome://settings, then you will want chrome://settings to disable the GUI for the feature when the policy controlling it is managed.

There is a method on PrefService::Preference to ask if it's managed.

You will also want chrome://settings to display the "some settings on this page have been overridden by an administrator" banner. If you use the pref attribute to connect your pref to the UI, this should happen automagically. NB: There is work underway to replace the banner with setting-level indicators. Once that's done, we'll update instructions here.

Wherever possible, we would like to support dynamic policy refresh, that is, the ability for an admin to change policy and Chrome to honor the change at run-time without requiring a restart of the process.

This means that you should listen for preference change notifications for your preference.

Don't forget to update chrome://settings when the preference changes. Note that for standard elements like checkboxes, this works out of the box when you use the pref attribute.

If you’re adding a device policy for Chrome OS, make sure you’ve updated chrome/browser/chromeos/policy/device_policy_decoder_chromeos.{h,cc} so the policy shows up on the chrome://policy page.

Build the policy_templates target to check that the ADM/ADMX, Mac app manifests, and documentation are generated correctly.

The generated files are placed in out/Debug/gen/chrome/app/policy/ (on Linux, adjust for other build types/platforms)

Add an entry for the new policy in chrome/test/data/policy/policy_test_cases.json

Add an entry for the new policy in tools/metrics/histograms/histograms.xml, in the EnterprisePolicies enum.

Add a test that verifies that the policy is being enforced in chrome/browser/policy/policy_browsertest.cc. Ideally, your test would set the policy, fire up the browser, and interact with the browser just as a user would do to check whether the policy takes effect. This significantly helps Chrome QA which otherwise has to test your new policy for each Chrome release.

Manually testing your policy

Windows: The simplest way to test is to write the registry keys manually to Software\Policies\Chromium (for Chromium builds) or Software\Policies\Google\Chrome (for Google Chrome branded builds). If you want to test policy refresh, you need to use group policy tools and gpupdate; see Windows Quick Start.

If you'd just like to do a quick test, the Linux code is also functional on CrOS, see Linux Quick Start

Examples

Here's a CL that has the basic infrastructure work required to add a policy for an already existing preference. It's a good, simple place to get started: http://codereview.chromium.org/8395007

Modifying existing policies

There are a few noteworthy pitfalls that you should be aware of when updating code that handles existing policy settings, in particular:

Make sure the policy meta data is up-to-date, in particular supported_on, and the feature flags.

In general, don’t change policy semantics in a way that is incompatible (as determined by user/admin-visible behavior) with previous semantics. In particular, consider that existing policy deployments may affect both old and new browser versions, and both should behave according to the admin's intentions.

It is OK to expand semantics of policy values as long as the previous policy description is compatible with the new behavior.

It is OK to update feature implementations and the policy description when Chrome changes as long as the intended effect of the policy remains intact.

The process for removing policies is to deprecate them first, wait a few releases (if possible) and then drop support for them. Make sure you put the deprecated flag if you deprecate a policy.

Open out/{Debug,Release}/gen/chrome/app/policy/common/html/en-US/chrome_policy_list.html in a text editor.

Cut&paste everything from the text editor into the wiki. (The wiki seems to have problems with pasting large amounts of text, so it might be necessary to split the text into a couple of smaller chunks for pasting.)