docs/enterprise/add_new_policy.md

# 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](https://support.google.com/chrome/a/answer/9037717?hl=en)
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](https://www.chromium.org/developers/enterprise-changes/).**

## Adding a new policy

1.  Design the policy, decide policy name, type, function, etc.
    - Please read [policy_design.md](./policy_design.md) for more information.
    - If you are adding support for a GenAI policy, please also read the
      internal [instructions](http://go/genai-chrome-policy-instructions) for
      new GenAI policies specifically.
2.  Declare the policy in the [policies.yaml](https://cs.chromium.org/chromium/src/components/policy/resources/templates/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](https://cs.chromium.org/chromium/src/components/policy/resources/templates/policy_definitions/).
    -  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](https://cs.chromium.org/chromium/src/components/policy/resources/new_policy_templates/.group.details.yaml)
       as a templates for group definition.
4.  Create a file named `PolicyName.yaml` under the appropriate [policy group](https://cs.chromium.org/chromium/src/components/policy/resources/templates/policy_definitions/).
    Please use [policy.yaml](https://cs.chromium.org/chromium/src/components/policy/resources/new_policy_templates/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](https://cs.chromium.org/chromium/src/components/policy/resources/new_policy_templates/policy.yaml).
    -   See [description_guidelines.md](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](https://chromeenterprise.google/intl/en_ca/policies/atomic-groups/)
      is controlled by the policy [PolicyAtomicGroupsEnabled](https://chromeenterprise.google/intl/en_ca/policies/#PolicyAtomicGroupsEnabled).

        -  Declare the atomic group in the [policies.yaml](https://cs.chromium.org/chromium/src/components/policy/resources/templates/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](https://cs.chromium.org/chromium/src/components/policy/resources/new_policy_templates/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**.](../../chrome/browser/prefs/README.md)
            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](https://cs.chromium.org/chromium/src/chrome/browser/policy/configuration_policy_handler_list_factory.cc?type=cs&q=kSimplePolicyMap&g=0&l=150). 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](https://cs.chromium.org/chromium/src/components/policy/test/data/pref_mapping) (see [instructions](https://cs.chromium.org/chromium/src/docs/enterprise/policy_pref_mapping_test.md)).
        4.  iOS platform has its own
            [configuration_policy_handler_list_factory.mm](https://source.chromium.org/chromium/chromium/src/+/main:ios/chrome/browser/policy/model/configuration_policy_handler_list_factory.mm)
            and
            [policy/pref_mapping](https://source.chromium.org/chromium/chromium/src/+/main:ios/chrome/test/data/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](https://cs.chromium.org/chromium/src/ui/webui/resources/images/business.svg)
            to tell users that the setting is enforced by the administrator.
        -   There are more information and util functions can be found [here](https://source.chromium.org/chromium/chromium/src/+/main:ui/webui/resources/cr_elements/policy/).
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](https://cs.chromium.org/chromium/src/components/prefs/pref_change_registrar.h)
        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](go/chrome-with-policies) 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](https://www.chromium.org/administrators/windows-quick-start).
    -   Mac: See
        [Mac Quick Start](https://www.chromium.org/administrators/mac-quick-start)
        (section "Debugging")
    -   Linux: See
        [Linux Quick Start](https://www.chromium.org/administrators/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](https://www.chromium.org/developers/how-tos/enterprise/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](https://www.chromium.org/administrators/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](./life_of_a_policy.md) 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](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](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](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](https://docs.google.com/document/d/1QgDTWISgOE8DVwQSSz8x5oKrI3O_qAvOmPryE5DQPcw/edit?usp=sharing)
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](https://dl.google.com/dl/edgedl/chrome/policy/policy_templates.zip)
  will be updated automatically.
* [Policy documentation](https://cloud.google.com/docs/chrome-enterprise/policies/)
  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**.