Custom Mapping Configuration

Custom Mapping Configuration

Custom mappings allow administrators to explicitly tell the Browser Protector which HTML elements on a specific site need to be protected or unprotected.

Custom mappings are defined under the optional customMappings key in the extension configuration JSON.

Structure Overview

customMappings
└── domains[]
    ├── domain                          — hostname to scope the rules to
    ├── page[]
    │   ├── path[]                      — URL path segments to scope rules to (empty = all paths on the domain)
    │   └── mappings[]                  — groups of attribute-based rules
    │       ├── attributeName           — HTML attribute to inspect (e.g. id, class, aria-label)
    │       ├── value                   — expected attribute value; omit to match on attribute presence alone
    │       └── entries[]
    │           ├── dataElement         — Protegrity data element name to use for the operation
    │           ├── operation           — "protect" or "unprotect"
    │           ├── splitSegments       — (optional) split text content into individual tokens before processing
    │           └── parentConditions[]  — (optional) ancestor element constraints for narrowing matches
    └── title[]
        ├── path[]                      — URL path segments to scope title rules to (empty = all paths on the domain)
        └── algo                        — identifier for the page title unprotection algorithm to use

Domain Matching

Exact domain entries take precedence over wildcard entries.

To read more about domain rules, go here.

Path Matching

• An empty path array applies the mapping rules to every page on the matched domain.
• When paths are provided, they are matched as substrings of the current URL path (e.g. "/accounts" matches /accounts/list).

Parent Conditions

parentConditions can optionally restrict a mapping so it only fires when the target element has a specific ancestor within a certain number of DOM levels. Each condition can check the ancestor’s tag name, an attribute name, and/or an attribute value.

Example

The following configuration unprotects any element on crm.example.com that has aria-label="customer-ssn", using the SSN data element:

"customMappings": {
    "domains": [
        {
        "domain": "crm.example.com",
        "page": [
            {
            "path": [],
            "mappings": [
                {
                "attributeName": "aria-label",
                "value": "customer-ssn",
                "entries": [
                    {
                    "dataElement": "SSN",
                    "operation": "unprotect"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

When the extension detects an element such as:

<span aria-label="customer-ssn">***-**-1234</span>

This example html element will match the custom mapping rule above, allowing the Protegrity browser protector to know this is an element that when selected, will use the SSN data element for unprotection.

Page Title Unprotection

The title array within a domain entry enables unprotection of protected values embedded in the browser’s page <title>. This is useful for single-page applications (such as Salesforce) that reflect record data in the tab title after navigation.

Each title entry specifies:

• path — URL path scope (empty array = applies to all pages on the domain)
• algo — the name of the page title extraction algorithm to use

The extension monitors the <title> element for changes and re-runs unprotection on navigation or if the title changes.

Example

"customMappings": {
  "domains": [
    {
      "domain": "myorg.example.com",
      "title": [
        {
          "path": ["/example/r/User"],
          "algo": "Example_Algo"
        }
      ]
    }
  ]
}

For a title such as example Title, the extension will unprotect and rewrite the title with the plaintext result.

Notes

• Attribute matching is case-insensitive.
• Class attribute matching supports partial class list matching (i.e. the configured value only needs to appear as one class in a multi-class attribute).