Policy Settings in Chrome

Summary

Chrome exposes a different set of configurations to administrators. These configurations are called policy and they give administrators more advanced controls than the normal users. With different device management tools, an administrator can deliver these policies to many users. Here is the help center article that talks about Chrome policy and its deployment.

Do I need a policy

Usually you need a policy when

• Launching a new feature. Create a policy so that the admin can disable or enable the feature for all users.

• Deprecating an old feature. Create a policy to give enterprise users more time to migrate away from the feature.

To read more about best practices for shipping enterprise friendly features, please read this article.

Adding a new policy

ℹ️️ An AI agent (e.g., Gemini CLI) can help you write your policy YAML, map it to a pref, and write tests. Add the policy-creation skill, then ask your agent to create a policy.

Example for Gemini CLI:

shCopy

gemini skills link agents/skills/policy-creation

1. Design the policy, decide policy name, type, function, etc.
   • Please read policy_design.md for more information.
   • If you are adding support for a GenAI policy, please also read the internal instructions for new GenAI policies specifically.
2. Declare the policy in the policies.yaml file.
   • This file contains the policy names and their ids.
3. If you need to add a new policy group, create a directory with the name of that group under policy group.
   • Inside the newly created directory, create a .group.details.yaml file with the caption and description of the group. This group is used for documentation and policy template generation, so it is recommended to group policies in meaningful groups.
   • Use .group.details.yaml as a templates for group definition.
4. Create a file named PolicyName.yaml under the appropriate policy group. Please use policy.yaml to start off your policy.
   • This file contains meta-level descriptions of all policies and is used to generate code, policy templates as well as documentation. Please make sure you get the version and feature flags (such as dynamic_refresh and supported_on) right. More details on the fields can be found in policy.yaml.
   • See description_guidelines.md for additional guidelines when creating a description, including how various products should be referenced.
   • Optional fields can be skipped when they are set to the default value.
5. Create a policy atomic group.

   • If you are adding multiple policies that are closely related and interact with each other, you should put them in policy atomic group. An atomic policy group is used in the Chromium code and affects how policies are applied. When enabled by the admin, this ensures that policies from an atomic group get their values from the same source and are not a mix of policies from multiple sources. This feature is controlled by the policy PolicyAtomicGroupsEnabled.

     • Declare the atomic group in the policies.yaml file.

   • Create a policy_atomic_groups.yaml file in the group where you added the policies if it does not already exist. You may use policy_atomic_groups.yaml as reference.

6. Create a preference and map the policy value to it.
   • All policy values need to be mapped into a prefs value before being used unless the policy is needed before PrefService initialization.
   • To map the policy:
     1. Create a prefs and register the prefs in Local State or Profile Prefs. Please note that, this must match the per_profile attribute in the YourPolicyName.yaml. We also strongly encourage developers to register the prefs with Profile Prefs if possible, because this gives admin more flexibility of policy setup.
     2. Most policies can be mapped to prefs with kSimplePolicyMap in configuration_policy_handler_list_factory.cc. If the policy needs additional verification or processing, please implement a ConfigurationPolicyHandler to do so.
     3. Test the mapping by adding PolicyName.json under policy/test/data/pref_mapping (see instructions).
     4. iOS platform has its own configuration_policy_handler_list_factory.mm and policy/pref_mapping file.
7. Disable the user setting UI when the policy is applied.
   • If your feature can be controlled by GUI in chrome://settings, the associated option should be disabled when the policy controlling it is managed.
     • PrefService:Preference::IsManaged reveals whether a prefs value comes from policy or not.
     • The setting needs an indicator to tell users that the setting is enforced by the administrator.
     • There are more information and util functions can be found here.
8. Support dynamic_refresh if possible.
   • We strongly encourage developers to make their policies support this attribute. It means the admin can change the policy value and Chrome will honor the change at run-time without requiring a restart of the browser. ChromeOS does not always support non-dynamic profile policies. Please verify with a ChromeOS policy owner if your profile policy does not support dynamic refresh on ChromeOS.
   • Most of the time, this requires a PrefChangeRegistrar to listen to the preference change notification and update UI or browser behavior right away.
9. Adding a device policy for ChromeOS.
   • Most policies that are used by the browser can be shared between desktop and ChromeOS. However, you need a few additional steps for a device policy on ChromeOS.
     • Add a field for your policy in components/policy/proto/chrome_device_policy.proto. Please note that all proto fields are optional.
     • Update chrome/browser/ash/policy/core/device_policy_decoder.{h,cc} for the new policy.
10. Test the policy.
    • Add a test to verify the policy. You can add a test in chrome/browser/policy/<area>_policy_browsertest.cc or with the policy implementation. For example, a network policy test can be put into chrome/browser/net. 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.
11. Manually testing your policy.
    • This Internal Doc contains the most up to date instructions for testing policies. However, the following docs are still useful as public references.
    • 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.
    • Mac: See Mac Quick Start (section "Debugging")
    • Linux: See Linux Quick Start (section "Set Up Policies")
    • ChromeOS and Android are more complex to test, as a full end-to-end test requires network transactions to the policy test server. Instructions on how to set up the policy test server and have the browser talk to it are here: Running the cloud policy test server. If you'd just like to do a quick test for ChromeOS, the Linux code is also functional on CrOS, see Linux Quick Start.
12. If you are adding a new policy that supersedes an older one, verify that the new policy works as expected even if the old policy is set. And if the new policy has any interactions with the other policies, make sure to document and test all the possible combinations.

Policy Launch, modification and deprecation

Please read life of a policy for more information.

Examples

• Here is an example for adding a new policy. It's a good, simple place to get started: https://chromium-review.googlesource.com/c/chromium/src/+/4004453
• This is an example for the clean-up CL needed to remove a deprecated, escape hatch policy. https://chromium-review.googlesource.com/c/chromium/src/+/5483886
• This is an example of a CL that sets the expiration date of a policy in a future milestone: https://chromium-review.googlesource.com/c/chromium/src/+/4022055

Cloud Policy

For Googlers only: The Cloud Policy will be maintained by the Admin console team. See instructions here on how to update the Cloud Policy.

Post policy update

Once the policy is added or modified, nothing else needs to be taken care of by the Chromium developers. However, there are a few things that will be updated based on the yaml file. Please note that there is no ETA for everything listed below.

• Policy templates will be updated automatically.
• Policy documentation will be updated automatically.

---

Additional Notes

1. The future_on flag can disable policy on Beta of Stable channel only if the policy value is copied to PrefService in Step 3 of Adding a new policy.