chromium93版本policys浏览器策略修改与定制_policies\google\chrome 支持哪些配置项

一、chromium中policy的基本作用

• 一组可由Chromium管理员管理的配置,这些配置称为管理策略(policy),它们给管理员更高级的配置,比正常用户有更多的控制功能。
• policy以JSON配置文件的形式放置于特定文件夹下以供浏览器读取并配置。
• 管理员使用policy可以 强制(或者建议) 用户 启用、禁用 某些功能。

如果是chrome配置地址：

/etc/opt/chrome/policies/managed/

/etc/opt/chrome/policies/recommended/

二、chromium的policy的配置

2.1 配置文件放置路径

• 控制策略包括两组,它们的配置路径分别为
  /etc/chromium/policies/managed/
/etc/chromium/policies/recommended/

• managed/下的所有*.json配置文件是浏览器会强制执行、不允许用户更改的设置；

• recommended/下的所有*.json配置文件为建议的配置,不会强制用户执行,只会在相应的设置界面对用户进行建议。

• 以managed/下的配置文件为例

  1. 如果/etc/chromium/policies/managed/路径不存在的话,管理员需要手动创建,并将对应配置文件放到路径中。
  2. 浏览器会读取managed/文件夹下所有*.json文件(（)如果路径不存在将不会读取）,并将所有的*.json文件中的配置全部应用在浏览器中。管理员可以在同一个配置文件中配置所有策略,也可以将策略分布在不同的配置文件中,但是,不能在多个配置文件中对同一项policy进行配置

2.2 配置实例

1. 如希望 建议 普通用户的浏览器显示主页按钮,则管理员可以创建/etc/chromium/policies/recommended/文件夹,并在文件夹目录中放置policy.json文件,配置为:

   {
    "ShowHomeButton": true
   }
   

   效果如图所示，浏览器会给出建议，用户可以调整配置。

   

2. 如希望 强制 普通用户的浏览器显示主页按钮,则管理员可以创建/etc/chromium/policies/managed/文件夹,属性设置为(只读)防止用户修改配置文件）,并在文件夹目录中放置policy.json文件,配置为

   {
      "ShowHomeButton": true
   }
   

   配置完成后普通用户的浏览器将会显示主页按钮,并且无法关闭,如图所示

 效果如图所示，浏览器会强制用户使用配置文件信息。

• policy所有支持字段的查阅方法

  图2-3

  图2-4

  • 所有的配置支持的字段见文末附件

  • 对于每个字段,都可以点击以查看详细信息,如图2-3所示

  • 每个字段的说明(如图2-4)都能显示其名称、数据类型、支持的效果、说明、示例值等详细信息；根据需要把字段和对应的值写入*.json文件中,并放置到规定的文件夹,即可实现对浏览器的策略控制。

三、Chrome浏览器的policy的配置

• chromium浏览器的配置文件放置路径与uos自研浏览器不同,为:
  /etc/opt/chrome/policies/managed/
/etc/opt/chrome/policies/recommended/
  其余配置相同

四、定制policy基本步骤

1. 第一步,需要为新定制的policy命名,遵循以下命名规则

   • 保持与现有命名方案一致。如选择"XXXEnabled"而不是"EnableXXX",因为前者更加直观,并且由于policy配置项数量多,"XXXEnabled"更容易在字母排序的列表中寻找
   • 需要考虑到可拓展性,并尽量避免与未来可能会有的扩展或用例出现命名冲突
   • 有 禁用/关闭 语义的policy(如名称中带有Disabled, Disallowed的)的名称一定要详细、没有歧义,因为设置这些policy很容易出错(比如一个policy名为DeveloperToolsDisabled,那要禁用开发者模式, 此配置是设置为true还是false呢?这就很容易产生理解上的歧义)

2. 定义policy

   • 在components/policy/resources/policy_templates.json中定义新的policy
   • 在policy_templates.json的定义中包含所有policy的属性,请确保设置了正确的版本号和功能标志(如dynamic_refresh和supported_on)
   • 下面是最常用的属性。请注意,除了supported_on之外,下面的其他属性都不会改变代码行为。
     • supported_on它控制着policy所支持的平台
     • dynamic_refresh如设置为true即可动态刷新,即不用重启浏览器,只要修改了配置文件,就能对浏览器生效.如设置为false则需要重启浏览器,配置才会生效.
     • per_profile此设置表示是否允许在不同的配置文件中配置policy(比如在policy1.json中设置属性1,在policy2.json中设置属性2)
     • can_be_recommended表示此属性是否可以被 推荐 .如设置为true即只对用户建议,而不强制执行,设置为false则此属性只能被强制执行
     • desc: policy文本说明,其中应包括以下内容
       • 浏览器的什么功能会受到影响
       • 什么行为以及什么UI/UX会改变policy的触发器。
       • 如果策略未设置或设置为无效的值或者是默认的值,那么policy的行为方式是什么
     • 所有属性的完整列表可以在components/policy/resources/policy_templates.json中找到(主要集中于 1-270行 )

3. 创建一个首选项(prefs value),并将策略值映射到它。

   • 在使用策略值之前需要将所有策略值映射到prefs value,除非在PrefService(首选项类)初始化之前需要策略
   • 映射策略的基本步骤
     • 创建prefs并在tools/metrics/histograms/enums.xmls中注册prefs。请注意,这必须与policy_templates.json中的id相匹配。
     • 大多数策略都可以使用configuration_policy_handler_list_factory.cc中的kSimplePolicyMap策略映射来映射到prefs。如果该策略需要额外的验证或处理,请实现ConfigurationPolicyHandler。
     • 通过向policy_test_cases.json添加策略来测试映射

4. 在应用策略时禁用用户设置用户界面。

   • 如果涉及到的功能可以由chrome://settings中的GUI控制,则在管理控制它的策略时,应禁用关联的选项(例如,policy设置强制启用显示主页按钮,则设置页面的启用主页按钮应该置灰.用户不可点击)
     • PrefService:Preference::IsManaged将显示prefs是否来自策略
     • 该设置需要一个指示器(ui/webui/resources/images/business.svg)来告诉用户该设置是由管理员强制执行的。即: 

5. 最好支持dynamic_refresh。

   • 建议支持此属性,这样管理员更改policy属性值时,浏览器将在运行时加载该更改,而不需要重新启动浏览器。(ChromeOS并不支持所有的policy动态刷新。详情请在chromium官网查询)
   • 大多数情况下,需要一个PrefChangeRegistrar(components/prefs/pref_change_registrar.h)来监听配置项更改的通知,并立即更新用户界面或浏览器的行为

6. 测试policy

   • 添加一个测试以验证该策略。可以在chrome/browser/policy/<area>_policy_browsertest.cc中或在策略实现中添加测试。例如,一个网络策略测试可以放入chrome/browser/net中。
   • 对于Linux操作系统的policy相关信息请查看Linux Quick Start(section "Set Up Policies")

7. 如果要添加新policy取代旧policy,需要保证即使设置旧策略,新策略也能正常工作(可能有的主机是运用了旧的policy配置,但装了新版浏览器,所以要保持新旧版本的兼容性)

8. 如果自定义的policy与其他policy有交互,需要确保通过自动测试记录文档、测试

五、示例1:新增policy

下面是一个基于上述说明的示例。可以作为参考: https://chromium-review.googlesource.com/c/chromium/src/+/1742209

六、示例2:以显示主页按钮(ShowHomeButton)为例

声明、定义、映射policy

1. 首先,需要在components/policy/resources/policy_templates.json中定义ShowHomeButton(以下暂时用C++风格来进行注释)

   {     //4360行
     'name': 'ShowHomeButton',   //policy名称
     'owners': ['file://components/policy/resources/OWNERS'],  //作者名称(可以是邮箱、文件等形式)
     'type': 'main',             //数据类型
     'schema': { 'type': 'boolean' },    //属性介绍
     'supported_on': ['chrome.*:8-', 'chrome_os:11-'],   //支持环境
     'features': {     //属性
       'can_be_recommended': True,     //可以被“推荐”
       'dynamic_refresh': True,      //动态刷新
       'per_profile': True,    //可以在多个配置文件中配置
     },
     'example_value': True,    //示例置
     'id': 35,       //id,这个值是自己定义,且不能与其他policy冲突
     'caption': '''Show Home button on toolbar''',   //简介
     'tags': [],     //允许在表格中跳转
     'desc': '''Shows the Home button on <ph name="PRODUCT_NAME">$1<ex>Google Chrome</ex></ph>'s toolbar.
     If you enable this setting, the Home button is always shown.
     If you disable this setting, the Home button is never shown.
     If you enable or disable this setting, users cannot change or override this setting in <ph name="PRODUCT_NAME">$1<ex>Google Chrome</ex></ph>.
     Leaving this policy not set will allow the user to choose whether to show the home button.''',      //详细说明
     /*
     所有属性的完整列表可以在components/policy/resources/policy_templates.json中找到(主要集中于 1-270行 )
     */
   },  //4383行
   

   

   图2-5 ShowHomeButton详细信息

   • policy数据类型(详情见policy_templates.json 21-37行):
     • 'group': - not a real policy, contains a list of policies. NOTE: Currently nesting groups inside other groups is not supported.
     • 'string' - a string value
     • 'int' - an integer value
     • 'int-enum' - the user can select an integer value from a collection of items
     • 'string-enum' - the user can select a string value from a collection of items
     • 'string-enum-list' - the user can select a set of string values from a collection of items
     • 'main' - a boolean value
     • 'list' - a list of string values. Using this for a list of JSON strings is now discouraged, because the 'dict' is better for JSON.
     • 'dict' - perhaps should be named JSON. An arbitrarily complex object or array, nested objects/arrays, etc. The user defines the value with JSON.
     • 'external' - a policy that references external data. NOTE: This type is currently supported on Chrome OS only.

   1. 在tools/metrics/histograms/enums.xml中对ShowHomeButton进行定义

      <int value="35" label="ShowHomeButton"/>
      

   2. 在components/policy/core/browser/configuration_policy_handler_list_factory.cc中将key::ShowHomeButton映射到prefs::kShowHomeButton

      //chrome/browser/policy/configuration_policy_handler_list_factory.h
      //PolicyToPreferenceMapEntry结构体声明
      struct POLICY_EXPORT PolicyToPreferenceMapEntry {
        const char* const policy_name;      //policy名称
        const char* const preference_path;  //首选项路径
        const base::Value::Type value_type; //数据类型
      };
      
      //chrome/browser/policy/configuration_policy_handler_list_factory.cc
      //在kSimplePolicyMap[]结构体中将policy名称和首选项进行映射
      const PolicyToPreferenceMapEntry kSimplePolicyMap[] = {
        ......
        { key::kShowHomeButton,
          prefs::kShowHomeButton,
          base::Value::Type::BOOLEAN },
        ......
      }
      

   3. 在chrome/common/pref_names.cc和chrome/common/pref_names.h中增加首选项的声明和定义

      //chrome/common/pref_names.h
      extern const char kShowHomeButton[];
      

      //chrome/common/pref_names.cc
      // A boolean pref set to true if a Home button to open the Home pages should be
      // visible on the toolbar.
      const char kShowHomeButton[] = "browser.show_home_button";
      

   4. 在toolbar类中声明一个BooleanPrefMember类对象(其中BooleanPrefMember类就是模板类PrefMember<bool>的别名)

      //chrome/browser/ui/views/toolbar/toolbar_view.h
      class ToolbarView {
      public:
       
        ......
       
        Browser* const browser_;
        BooleanPrefMember show_home_button_;
       
        ......
       
      }
      

      PrefMember类定义如下,这个类继承自PrefMemberBase基类

      //components/prefs/pref_member.h
      ......
          
      typedef PrefMember<bool> BooleanPrefMember;
      typedef PrefMember<int> IntegerPrefMember;
      typedef PrefMember<double> DoublePrefMember;
      typedef PrefMember<std::string> StringPrefMember;
      typedef PrefMember<base::FilePath> FilePathPrefMember;
      // This preference member is expensive for large string arrays.
      typedef PrefMember<std::vector<std::string>> StringListPrefMember;
       
      ......
       
      //components/prefs/pref_member.h
      template <typename ValueType>
      class PrefMember : public subtle::PrefMemberBase {
      public:
       
        .....
       
        void Init(const std::string& pref_name,
                  PrefService* prefs,
                  const NamedChangeCallback& observer) {
          subtle::PrefMemberBase::Init(pref_name, prefs, observer);
        }
        void Init(const std::string& pref_name,
                  PrefService* prefs,
                  const base::RepeatingClosure& observer) {
          subtle::PrefMemberBase::Init(
              pref_name, prefs,
              base::BindRepeating(&PrefMemberBase::InvokeUnnamedCallback, observer));
        }
        void Init(const std::string& pref_name, PrefService* prefs) {
          subtle::PrefMemberBase::Init(pref_name, prefs);
        }
       
        ......
       
        bool IsManaged() const {
          VerifyPref();
          return internal_->IsManaged();
        }
       
        ValueType GetValue() const {
          VerifyPref();
          return internal_->value();
        }
       
        // Provided as a convenience.
        ValueType operator*() const {
          return GetValue();
        }
       
        ......
       
      };
      

      PrefMemberBase类定义如下,这个类继承自PrefMemberBase基类,主要负责监听Prefs的更改消息

      //components/prefs/pref_observer.h
      class PrefObserver {
      public:
        virtual void OnPreferenceChanged(PrefService* service,
                                 const std::string& pref_name) = 0;
      };
      

   5. 在chrome/browser/ui/views/toolbar/toolbar_view.cc中对show_home_button_初始化

      void ToolbarView::Init() {
       
        ......
       
        show_home_button_.Init(
            prefs::kShowHomeButton, browser_->profile()->GetPrefs(),
            base::BindRepeating(&ToolbarView::OnShowHomeButtonChanged,
                                base::Unretained(this)));
        /*
        base::BindRepeating(&ToolbarView::OnShowHomeButtonChanged,
                                base::Unretained(this))
        注册了一个可执行多次的回调函数,在policy配置更改时,通过PrefObserver类来进行监听policy配置的更改(PrefMemberBase是PrefMember的父类,是PrefObserver的子类)
        所以当policy发生变化时,会通知PrefMember类的实例show_home_button_,然后调用ToolbarView::OnShowHomeButtonChanged回调,实现对"显示主页"按钮的控制
        */
       
        ......
       
      }
       
      void ToolbarView::OnShowHomeButtonChanged() { 
        UpdateHomeButtonVisibility();
        Layout();
        SchedulePaint();
      }
       
        ......
       
      void ToolbarView::UpdateHomeButtonVisibility() {
        const bool show_home_button =
            show_home_button_.GetValue() || browser_->deprecated_is_app();
        home_->SetVisible(show_home_button);    //设置工具栏中的"主页按钮"是否可见
      }
      /*
        browser_->deprecated_is_app(): 返回Browser窗口的类型,如果是app窗口、弹出式(popup)窗口、Devtools窗口,则返回true
        show_home_button_.GetValue(): 返回当前policy的配置值(对于ShowHomeButton,返回true或false)
      */
      

对UI界面进行设置

1. 先回到chrome/common/pref_names.cc

   //chrome/common/pref_names.cc
   // A boolean pref set to true if a Home button to open the Home pages should be
   // visible on the toolbar.
   const char kShowHomeButton[] = "browser.show_home_button";
   

2. "browser.show_home_button"是为前端提供的接口:

   • 在chrome/browser/resources/settings/controls/settings_checkbox.html中,"showhomebutton"按钮(实质上是一个checkbox)由controlDisabled(disabled, pref.*)控制的控件,

     图7-6 settings_checkbox.html

   • 而对于controlDisabled,chrome/browser/resources/settings/controls/settings_boolean_control_behavior.js,是由this.disable和this.isPrefEnforced()取并集,即只要是用户设置为disable或者是由pref强制设置为disable,控件都不可点击(不可控)

   图7-7 settings_boolean_control_behavior.js

• isPrefEnforced()的定义见ui/webui/resources/cr_elements/policy/cr_policy_pref_behavior.js

  图7-8 cr_policy_pref_behavior.js

  • 见chrome/browser/resources/settings/appearance_page/appearance_page.html,其中"browser.show_home_button"为后端提供的接口

  图7-9 appearance_page.html

  • 至此,当后端传来的"browser.show_home_button"值为false,在设置界面上的"显示主页"按钮即不可点击

在适当的位置添加一个指示器(ui/webui/resources/images/business.svg),告诉用户此设置由管理员管理

1. chrome/browser/resources/settings/controls/settings_checkbox.html

图7-10 settings_checkbox.html

1. 页面上的指示器资源如图7-6所示

   图7-11 设置页面的指示器资源

十一、其他

1. 附加说明

   • policy_templates.json实际上是一个Python字典,尽管文件后缀名是json