|
| 1 | + |
| 2 | +# Page Interaction Restriction Manager |
| 3 | + |
| 4 | +## Authors |
| 5 | + |
| 6 | +- [Jineen Seirup](http://github.com/jineens) |
| 7 | + |
| 8 | +## Table of Contents |
| 9 | + |
| 10 | +1. [Introduction](#introduction) |
| 11 | +2. [User-Facing Problem](#user-facing-problem) |
| 12 | +3. [Goals](#goals) |
| 13 | +4. [Non-goals](#non-goals) |
| 14 | +5. [User Research](#user-research) |
| 15 | +6. [Proposed Approach](#proposed-approach) |
| 16 | +7. [Example Usage](#example-usage) |
| 17 | +8. [Accessibility, Privacy, and Security Considerations](#accessibility-privacy-and-security-considerations) |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +## Introduction |
| 22 | + |
| 23 | +This proposal provides a way for enterprise websites to communicate with enterprise-configured browsers whether certain restrictions should be enforced for a webpage. An example of such a restriction is removing user access to copy data from a webpage, which many enterprise websites attempt to do by intercepting user input and/or overriding the default right click menu. |
| 24 | + |
| 25 | +> Note: This is a data leak/data loss prevention feature and not a security feature. Data leak prevention features are intended to automatically help users avoid accidental, inappropriate disclosure of data and unintentional violations of their company's data management policies. These features are not intended to completely prevent malicious, determined users from extracting data, though the features may enable enterprises to have more opportunity to detect such scenarios. |
| 26 | +
|
| 27 | +Access to this JavaScript API in the browser is controlled via enterprise policy on the client device. [Protect Office documents with Microsoft Purview Information Protection labeling | Microsoft Learn](https://learn.microsoft.com/en-us/microsoft-365/compliance/protect-office-files-with-microsoft-information-protection?view=o365-worldwide). Non-browser platforms that leverage web platform technology, such as Microsoft’s WebView2, may also choose to expose APIs that allow a host app to control this API’s availability. |
| 28 | + |
| 29 | +## User-Facing Problem |
| 30 | + |
| 31 | +Web sites (in particular document viewing and editing sites) that wish to implement enterprise-managed browser user interaction restrictions tied to policies associated with the documents need to be able to communicate to the browser about which restrictions need to be enforced. |
| 32 | + |
| 33 | +## Goals |
| 34 | + |
| 35 | +- Allow a communication pathway between enterprise web sites and enterprise configured browsers so that enterprise web sites can communicate what user interaction restrictions they'd like and enterprise configured browsers can communicate which restrictions they are willing to enforce. |
| 36 | + |
| 37 | +## Non-goals |
| 38 | + |
| 39 | +- Prevent a web page from accessing its own document after it’s had these restrictions applied to them; it is up to the web page to maintain control of the code they load on their site. |
| 40 | +- Prevent a compromised process (e.g. due to a browser security bug or local malware) from having access to the document. This feature is not a security boundary. |
| 41 | +- Create a security boundary that guarantees a motivated user cannot work around restrictions the page and/or browser are attempting to enforce. |
| 42 | +- Prevent extensions from interacting with or having access to the DOM of a restricted page. (Many browsers offer enterprises policies to control the use of browser extensions). |
| 43 | + |
| 44 | +## User Research |
| 45 | + |
| 46 | +This API has been designed to take advantage of the same mechanisms available to non-browser applications but in a web-exposed way. Those APIs and resulting system behaviors are well-understood. |
| 47 | + |
| 48 | +## Proposed Approach |
| 49 | + |
| 50 | +The API provides a mechanism to request that a specific type of user interaction no longer be allowed. The list below is the proposed initial set, but it's expected that additional actions will be defined over time. This portion of the API is only visible in the browser. |
| 51 | + |
| 52 | +| Action Name | Description | |
| 53 | +|------------------|--------------------------------------------------------------------| |
| 54 | +| copy | User can put text from the web site on the OS clipboard. | |
| 55 | +| paste | User can paste data into the web site from the OS clipboard. | |
| 56 | +| builtin-ai | AI features built into the browser can process content on the web site. | |
| 57 | +| save-as-webpage | User can save the webpage as an html file. | |
| 58 | +| debugging-tools | Browser debugging tools can be used by the user on the webpage. | |
| 59 | +| screenshot | User can use printscreen for the webpage on supported OSs. | |
| 60 | +| print | User can print the webpage directly. | |
| 61 | +| save-as-pdf | User can save the webpage directly as a pdf. | |
| 62 | +| extract-data | User can extract data from the webpage. | |
| 63 | +| export-data | User can export data from the webpage outside of the browser. | |
| 64 | + |
| 65 | +This API also provides a mechanism to associate labels of different types to the web site. |
| 66 | + |
| 67 | +| Supported Label Type | Description | Data Types | Public documentation | |
| 68 | +|-----------------------------|--------------------------------------------------------|--------------------------------------------|--------------------------------------------------------------------------------------| |
| 69 | +| MicrosoftSensitivityLabels | Microsoft Purview Information Protection Sensitivity Labels | Label ID: GUIDv4, Organization ID: GUIDv4 | [Overview - Microsoft Information Protection SDK. | Microsoft Learn](https://learn.microsoft.com/en-us/information-protection/develop/overview-information-protection-sdk) | |
| 70 | + |
| 71 | +## Example Usage |
| 72 | + |
| 73 | +### API existence check |
| 74 | + |
| 75 | +The `navigator.pageInteractionRestrictionManager` object is present on web pages where an enterprise-defined policy has indicated it should be used. The object provides methods for determining which types of user interactions can potentially be restricted by the user agent. |
| 76 | + |
| 77 | +```javascript |
| 78 | +if (!navigator.pageInteractionRestrictionManager) { |
| 79 | + // The API is not available; the site can, if desired, add its own logic to attempt to impede the user or |
| 80 | + // notify the user that the document cannot be accessed. |
| 81 | + AddJavascriptCopyBlock(); |
| 82 | + return; |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +### Detecting user activities that can be blocked |
| 87 | + |
| 88 | +```javascript |
| 89 | +const desired_action_names = ["copy", "print"]; |
| 90 | +const revokable_activities = await navigator.pageInteractionRestrictionManager.getSupportedActivities(); |
| 91 | + |
| 92 | +const missing_enforcement_option = desired_action_names.some(x => !revokable_activities.includes(x)); |
| 93 | +if (missing_enforcement_option) { |
| 94 | + // The API is available, but cannot be used to enforce the desired restriction. |
| 95 | + AddJavascriptCopyBlock(); |
| 96 | + return; |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +### Asking the browser permission to revoke user activities |
| 101 | + |
| 102 | +Even though the browser supports restricting user interactions, it may choose to disallow a site from using the API, e.g. due to the enterprise configuring the feature in a way that allows the user to choose if the functionality should be allowed. |
| 103 | + |
| 104 | +```javascript |
| 105 | +try { |
| 106 | + const revoke_manager = await navigator.pageInteractionRestrictionManager.requestRevokePermission(); |
| 107 | +} catch { |
| 108 | + // user or policy prevented access |
| 109 | + AddJavascriptCopyBlock(); |
| 110 | + return; |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +### Asking the browser to revoke specific user activities |
| 115 | + |
| 116 | +```javascript |
| 117 | +try { |
| 118 | + const revoked_activities = await revoke_manager.revoke([{name:'copy'}, {name:'print'}]); |
| 119 | +} catch { |
| 120 | + // something went wrong, e.g. invalid arguments. |
| 121 | + AddJavascriptCopyBlock(); |
| 122 | + return; |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +### Checking which user activities were revoked |
| 127 | + |
| 128 | +```javascript |
| 129 | +let all_revoked = true; |
| 130 | +for (const activity of revoked_activities) { |
| 131 | + if (activity.status == "revoked") { |
| 132 | + console.log("revoked " + activity.name); |
| 133 | + } |
| 134 | + if (activity.status == "denied") { |
| 135 | + console.log("failed to revoke " + activity.name); |
| 136 | + all_revoked = false; |
| 137 | + } |
| 138 | +} |
| 139 | + |
| 140 | +if (all_revoked) { |
| 141 | + // If needed, the web page can remove any logic that it implemented to prevent the user from |
| 142 | + // performing specific actions as the browser is doing it instead. |
| 143 | + RemoveJavascriptCopyBlock(); |
| 144 | +} else { |
| 145 | + AddJavascriptCopyBlock(); |
| 146 | +} |
| 147 | +``` |
| 148 | + |
| 149 | +### Getting the label manager |
| 150 | + |
| 151 | +```javascript |
| 152 | +try { |
| 153 | + const label_manager = await navigator.pageInteractionRestrictionManager.requestLabelManager(); |
| 154 | +} catch { |
| 155 | + console.log("label manager isn’t available"); |
| 156 | +} |
| 157 | +``` |
| 158 | + |
| 159 | +### Checking which label types are supported |
| 160 | + |
| 161 | +```javascript |
| 162 | +const label_types = await label_manager.getSupportedLabels(); |
| 163 | +let mip_supported = false; |
| 164 | +for (const label of label_types) { |
| 165 | + console.log("Type supported:" + label.type); |
| 166 | + if (label === 'MicrosoftSensitivityLabels') { |
| 167 | + mip_supported = true; |
| 168 | + } |
| 169 | +} |
| 170 | +``` |
| 171 | + |
| 172 | +### Adding a specific Label to the webpage |
| 173 | + |
| 174 | +UUID: [RFC 9562: Universally Unique IDentifiers (UUIDs)](https://datatracker.ietf.org/doc/html/rfc9562) |
| 175 | + |
| 176 | +[Concepts - Label metadata in the MIP SDK | Microsoft Learn](https://learn.microsoft.com/en-us/information-protection/develop/concept-label-metadata) |
| 177 | + |
| 178 | +```javascript |
| 179 | +let label; |
| 180 | +try { |
| 181 | + if (label_manager) { |
| 182 | + // MicrosoftSensitivityLabel expected format: |
| 183 | + // dictionary, label: GUID, organization GUID. (with dashes, no extra braces) |
| 184 | + label = await label_manager.addLabel('MicrosoftSensitivityLabel', {label:'00000000-0000-0000-0000-000000000000', organization:'11111111-1111-1111-1111-111111111111'}); |
| 185 | + } |
| 186 | +} catch { |
| 187 | + console.log("something went wrong (invalid args?)"); |
| 188 | +} |
| 189 | +``` |
| 190 | + |
| 191 | +### Removing a specific Label from a webpage |
| 192 | + |
| 193 | +```javascript |
| 194 | +if (label) { |
| 195 | + // Label must be removed from the same object that added the label. |
| 196 | + label.remove(); |
| 197 | +} |
| 198 | +``` |
| 199 | + |
| 200 | +## Accessibility, Privacy, and Security Considerations |
| 201 | + |
| 202 | +### Privacy |
| 203 | + |
| 204 | +- The `navigator.pageInteractionRestrictionManager` object should not rely on device status for existence or what restrictions are supported, as that would allow the website to determine specific information they might not otherwise be able to acquire, such as device management status. |
| 205 | +- This API does not have a query method that tells the webpage the state of the action to avoid webpages deducing information about the user's device that it doesn't already have. For instance, allowing a query method would allow the webpage to deduce if the user has specific enterprise policies applied to their device. |
| 206 | + |
| 207 | +### Security |
| 208 | + |
| 209 | +- This API does not guarantee perfect restrictions (there are always ways around such restrictions). |
| 210 | +- This API does not protect web sites from having their data compromised due to a virus or security bug. |
0 commit comments