Add new permission

Make sure to notify permissions-core@ when you plan to add a new permission.

PermissionType vs ContentSettingsType

PermissionType roughly matches the web-facing APIs for Permission Policy and Permissions API.

ContentSettingsType is a key used in HostContentSettingsMap to store per-type and per-origin JSON dictionaries. It contains all entries from PermissionType but additionally, it contains entries that are not permissions, e.g. Cookies, Images, Javascript, Sound, etc.

ContentSettingsType represents the Chrome-layer entity and is not available outside of Chrome. We use PermissionType as a Web Platform - layer list of permissions. That means we always need to have a pair of PermissionType ContentSettingsType. To improve clarity of the permissions API we’re trying to use PermissionType everywhere it is possible. Conceptually ContentSettingsType should be used only in HostContentSettingsMap. But there are still a few places where ContentSettingsType is presented.

• PermissionContextBase
• PermissionManager
• PermissionRequestManager
• PermissionRequest
• PermissionManagerFactory

We’re actively working on reducing ContentSettingsType footprint in the permissions code base.

We have a few utils methods in components/permissions/permission_util.h that convert PermissionType to ContentSettingsType and vice versa. We strongly encourage developers to use PermissionType.

PermissionContexts

PermissionContextBase provides default implementation for requesting/verifying and saving a permission state. Most of the methods in the class are virtual that allows for a newly added permission to customize how it can be requested, verified and stored. A custom implementation of the PermissionContextBase is the only way to init permission policy. For most of the cases you do not need to change the default implementation. A good example of the custom behavior is an integration with OS-level permissions. E.g. Notifications permission on Android has custom logic that verifies if Chrome has app-level permission and if a notification channel exists, additionally Notifications has custom logic for extensions. Similarly Geolocation has multiple implementations for different platforms GeolocationPermissionContext.

Add new permission

Add PermissionType

1. Add a new enum entry to PermissionType
2. Update permission_descriptor.idl
3. In permission_utils.cc update methods:
   • PermissionNameToString()
   • ParsePermissionDescriptor()
4. Update permission.mojom
5. In permission_utils.cc update
   • GetPermissionString()
   • PermissionDescriptorInfoToPermissionType()
6. In permission_controller_impl.cc update PermissionToSchedulingFeature() . By default the new feature should return std::nullopt. That means it will not block back-forward cache. If your feature needs to block it, make sure it is explicitly mentioned in a design doc as that needs to be reviewed.
7. In aw_permission_manager.cc update
   • RequestPermissions()
   • CancelPermissionRequest()
8. In shell_permission_manager.cc update IsAllowlistedPermissionType()
9. For Controlled Frame:
   • By default, GetPermissionStatus() / IsPermissionRequestable() disable permissions for WebView/Controlled Frame. If your PermissionType needs to be used by Controlled Frame embedded content, you can rely on examples from WEB_VIEW_PERMISSION_TYPE_GEOLOCATION and WEB_VIEW_PERMISSION_TYPE_MEDIA to guide how to do this in Controlled Frame.
   • Add permission type to controlled_frame_permissions_unittest.cc.

Add ContentSettingsType

1. In content_settings_types.h update ContentSettingsType
2. In content_settings_uma_util.cc update kHistogramValue
3. In content_settings_registry.cc update method ContentSettingsRegistry::Init()
   • Register the new entry as WebsiteSettingsInfo::UNSYNCABLE . If you need to use WebsiteSettingsInfo::SYNCABLE , then it should be explicitly mentioned in a design doc.
4. In permission_util.cc update
   • GetPermissionDelegationMode() . If you need non-default permission delegation logic. That should be explicitly stated in a design doc.
   • GetPermissionType()
   • PermissionTypeToContentSettingTypeSafe()
5. In WebsitePermissionsFetcherTest.java update assertion.
6. For Controlled Frame:
   • By default, we disable capabilities that use ContentSettingsType as keys for permission storage from being used in Controlled Frame.
   • Examples of enabling:
     • WebView: add hid permission request crrev.com/c/5136796
     • Delegate HID permission to Chrome App in webview crrev.com/c/4946553
   • Example of disabling:
     • controlledframe: Disable Web Serial for & crrev.com/c/5838413
   • Add your new ContentSettingsType to controlled_frame_permissions_unittest.cc.

UI-less ContentSettingsType

If you add a new ContentSettingsType which require no UI and no associated permission, then:

1. In site_settings_helper.cc update kContentSettingsTypeGroupNames.
   • Add a new entry into the second part of the array.

PageInfo, Settings Page

Some ContentSettingsType is displayed in chrome://settings/content. To be able to display it there, you need to do:

1. In site_settings_helper.cc update kContentSettingsTypeGroupNames.
   • Add a new entry into the first part of the array as permissions are available in the content settings page.
2. Add new strings for the new permission. The strings should be reviewed by meggynwatkins@ and permissions-core@ in a design doc.
3. In page_info.cc update kPermissionType . IMPORTANT: The order in the array is not random or organic. Please carefully read the comment.
4. In page_info_ui.cc update methods:
   • GetContentSettingsUIInfo()
   • GetPermissionAskStateString()
5. Add a new icon for the permission to be displayed in PageInfo
6. In page_info_view_factory.cc update
   • GetPermissionIcon()

Permission request

Most permissions allow sites to request a permission prompt where a user can grant or deny the permission.

1. In request_type.h update enum RequestType
2. In request_type.cc update
   • GetIconId*() for Android and Desktop
     • Reuse icons from the step above.
   • GetDialogMessageText() for Android
   • GetMessageTextFragment() for Desktop
     • Permission prompt strings should be reviewed by meggynwatkins@ and permissions-core@ in a design doc.
   • PermissionKeyForRequestType()
   • GetBlockedIconIdDesktop()

Tracking

1. In tools/metrics/histograms/enums.xml update histograms:
   • name="PermissionType"
   • name="ContentType"
   • name="PermissionRequestType"
2. In tools/metrics/histograms/metadata/histogram_suffixes_list.xml update histograms
   • name="PermissionTypes"
   • name="PermissionRequestTypes"
3. In tools/metrics/histograms/metadata/content/histograms.xml update <token key="ContentSettingsType">
4. In permission_uma_util.h updated enum RequestTypeForUma
5. In permission_uma_util.cc updated methods:
   • GetUmaValueForRequestType()
   • GetPermissionRequestString()
   • RecordPermissionAction()

Extend PermissionContextBase

To extend PermissionContextBase:

1. Create a new class <PermissionName>PermissionContext and extend permissions::PermissionContextBase.
2. Put it in components/permissions/contexts/ or in a feature folder.
3. In permission_manager_factory.cc update CreatePermissionContexts()
4. In permission_manager_factory.cc update CreatePermissionContexts()
5. In permission_test_util.cc update CreatePermissionContexts()

DevTools

Add new permissions for browser automation (e2e testing).

1. Update third_party/blink/public/devtools_protocol/browser_protocol.pdl
2. In content/browser/devtools/protocol/browser_handler.cc update
   • PermissionDescriptorToPermissionType()
   • FromProtocolPermissionType()

Optional: Add a permission policy

If you need to add a permission policy:

1. In permissions_policy_feature.mojom update enum PermissionsPolicyFeature

2. In permissions_policy_features.json5 update data array with the new policy. Also update PermissionPolicyFeature enum in browser_protocol.pdl

3. Update feature-policy-features-expected.txt

4. In the <PermissionName>PermissionContext, make sure to initialize the permission policy variable permissions_policy_feature_ in the class ctor.

Optional: Enterprise policies

Permissions infrastructure has its own provider for storing policies PolicyProvider. If you plan on allowing enterprise admins to control your newly added permission:

1. Follow that instructions docs/enterprise/add_new_policy.md
2. For the step #6 you need to create and register variables in content settings policy providers. That allows automatically verifying policy values for a given permission.
   • Create a new policy in components/content_settings/core/common/pref_names.(h/cc)
   • In content_settings_policy_provider.cc update
     • PrefsForManagedContentSettingsMapEntry
     • kManagedPrefs
     • kManagedDefaultPrefs
   • In ​configuration_policy_handler_list_factory.cc register the newly created policies as well.
3. In tools/metrics/histograms/enums.xml add new policies in enum name="EnterprisePolicies"