Installation

• 1: Required Skills and Prerequisites
• 2: Pre-Configuration
• 2.1: Extension Source Code
• 2.2: Host Extension On Private Server
• 2.3: Entra ID Configuration
• 2.4: Cloud API Configuration
• 2.4.1: Configuration for AWS
• 2.4.2: Configuration for GCP
• 2.4.3: Configuration for Azure
• 2.5: Set Up Configuration File for Browser Protector
• 3: Installation
• 3.1: Testing the Protegrity Browser Protector Extension Locally
• 3.2: Installing Browser Protector on Windows Devices Using Intune
• 3.3: Installing Browser Protector on macOS Using Kandji
• 3.4: MDM File Generator Utility
• 4: Testing and Troubleshooting

1 - Required Skills and Prerequisites

Before beginning the installation, ensure you have the necessary technical knowledge and access rights to complete the process smoothly.

Required Skills

To successfully deploy the Protegrity Browser Protector, the following roles and skillsets are necessary:

Prerequisites

Before deploying the Protegrity Browser Protector, ensure that the following requirements are met:

2 - Pre-Configuration

2.1 - Extension Source Code

Setting up the Browser Protector Extension For Distribution

Before deploying the Protegrity Browser Protector extension in your organization, you must set up the extension source code for secure distribution. This involves signing the extension and packaging it into a .crx file, which can then be distributed to users or deployed via MDM tools like Microsoft Intune.

Signing the extension ensures its integrity and authenticity, allowing browsers to verify that the extension has not been tampered with and originates from a trusted source. Packaging the extension into a .crx file makes it suitable for enterprise distribution and deployment.

Signing the Extension Binaries

Follow the steps below to create signed crx browser extension file.

Prepare the Extension Source Code

1. Protegrity will provide the following artifact.

   • WAP_ALL-ALL-64_x86-64_Browser.Chrome-<version>.zip

   The deployment package you receive from Protegrity must be extracted to reveal the Protegrity Browser Extension source files.

2. Extract the deployment package you receive from Protegrity to a folder. That folder will have Protegrity Browser Extension source files.

3. Place the extension source files folder in a directory on your system.

Generate a Private Key

1. A private key is required to sign the extension. If you do not already have a private key, you can generate one using a key management tool or browser-specific utilities.

You can use the Chrome Developer Tools to generate a private key during the signing process.

2. Store the private key securely, as it is critical for signing the extension and maintaining its authenticity, for instance when pushing new versions of the extension.

Security Guidelines

• Do not share the private key with unauthorized personnel.
• Store the private key in a secure location, such as a password-protected key management system or hardware security module (HSM).
• Ensure backups of the private key are kept in a secure environment.

Sign the Extension Using Chrome Developer Tools or the Chrome Command Prompt

Sign the Extension Using Chrome Browser Developer Tool

1. Open the Google Chrome browser.

2. Navigate to the extensions management page by entering the following URL in the address bar:

   chrome://extensions  
   

3. Enable Developer Mode.

   At the top right corner of the extensions page, toggle the Developer Mode switch to enable it.

4. In Developer Mode, a new toolbar will appear at the top of the extensions page.

5. Click the Pack Extension button to open the packaging tool.

6. In the popup window:

   • Extension root directory: Click the Browse button and select the folder containing Protegrity Browser Extension source files.
   • Private key file (optional): If you already have a private key file (.pem), provide its path by clicking Browse and selecting the file. This ensures the same key is used to sign the extension.
   • If you do not provide a private key, Chrome will generate one for you during the packaging process.

7. Click Pack Extension to generate the files.

Sign the Extension Using Chrome Command Prompt

1. Open a terminal or command prompt on your system.

2. Use Chrome’s chrome.exe tool or a third-party utility to sign the extension. For Chrome, the command is as follows:

   chrome.exe --pack-extension=path_to_extension_directory --pack-extension-key=path_to_private_key 
   

Locate the Generated Files

Once the packaging process is complete, Chrome will create the following files:

• A .crx file: This is the signed extension package, which can be distributed and installed.
• Optional: A .pem file: If no private key was provided, Chrome will generate a new .pem file. This file contains the private key and must be securely stored.
• The .crx file will be required in the Read Extension ID section.

Do not share the .pem file with unauthorized individuals, as it is used to sign future versions of the extension.

Read Extension ID

1. Locate the .crx file from the Locate the Generated Files section.
2. Open Chrome and navigate to the Extensions page:
   • Type chrome://extensions in the address bar and hit Enter.
3. In the top-right corner of the Extensions page, toggle Developer mode ON.
4. Drag the .crx file and drop it onto the Extensions page in Chrome.
5. When prompted, click Add Extension to complete the installation.
6. The 32 character long extension ID will be displayed on the extension tile, for instance: ID: abcdhleonbdlhddgbcfhffafcnjjabcd
7. Note the pty_extension_id.

The extension ID stays the same when as long as the same private key (.pem file) is used to sign it, even when updating the extension.

Security Guidelines

• Keep the .pem file secure. If it is lost, you will not be able to sign future versions of the extension, and you will need to distribute a new .crx signed with a new key.
• Never share the .pem file publicly or store it in insecure locations.
• Use a secure key management system to protect your private key.

By following these steps, you can create a signed .crx file that is ready for secure distribution and installation in Chrome.

2.2 - Host Extension On Private Server

Prepare the .crx File

Ensure you have the .crx file for Protegrity Browser Protector extension. If you haven’t created one yet, follow the steps in the Extension Source Code section.

Set Up HTTPS File Hosting

HTTPS File hosting service is required to host the .crx file. This can be any web server, such as, Apache, Nginx, or a cloud storage service.

Set Up an Amazon S3 Bucket

1. Create a new S3 bucket:

   • Log in to the AWS Management Console.
   • Navigate to S3 and click Create bucket.
   • Provide a unique name for the bucket, for example, s3-bucket-name and choose a region.
   • Leave other settings as default and click Create bucket.

2. Upload the .crx file:

   • Open the bucket in the S3 dashboard.
   • Click Upload and select your .crx file.
   • Set permissions to allow public access to the file as given in the below section.

Configure Permissions for Public Access

By default, files in S3 buckets are private. You need to make the .crx file publicly accessible:

1. Enable public access for the file:

   • Navigate to the uploaded .crx file in the S3 bucket.
   • Click Permissions.
   • Under Block public access, ensure the bucket allows public file access.

2. Add a bucket policy:

   • Navigate to the Permissions tab of the bucket.
   • Click Bucket policy and add a policy like the following:

     {  
       "Version": "2012-10-17",  
       "Statement": [  
         {  
           "Sid": "PublicReadGetObject",  
           "Effect": "Allow",  
           "Principal": "*",  
           "Action": "s3:GetObject",  
           "Resource": "arn:aws:s3:::s3-bucket-name/*"  
         }  
       ]  
     }  
     

   • Replace s3-bucket-name with the name of your bucket.
   • Click Save.

Set the Correct MIME Type for .crx Files

You need to configure the file’s MIME type so browsers recognize it as a Chrome extension:

1. Edit the file properties:

   • Navigate to the uploaded .crx file in the S3 bucket.
   • Click Properties.
   • Under Metadata, add the following key-value pair:
     • Key: Content-Type
     • Value: application/x-chrome-extension

2. Save the changes.

Access the Hosted .crx File

Once the file is uploaded and permissions are configured, you can access it via the S3 public URL:
https://.s3..amazonaws.com/pty-browser-protector.crx For example: https://s3-bucket-name.s3.us-east-1.amazonaws.com/pty-browser-protector.crx

Create an Update Manifest for Updates

Create an updated manifest file (update.xml) and host it on S3 as well.

Example update.xml File:

<?xml version="1.0" encoding="UTF-8"?>  
<gupdate xmlns="http://www.google.com/update2/response" protocol="2.0">  
  <app appid="pty_extension_id">  
    <updatecheck codebase="https://s3-bucket-name.s3.us-east-1.amazonaws.com/pty-browser-protector.crx" version="1.0.2" />  
  </app>  
</gupdate>  

• Replace pty_extension_id with Protegrity Browser Protector extension’s unique ID recorded in the Extension Source Code section.
• Replace the codebase URL with the public S3 URL of your .crx file.
• Update the version field to match your extension’s version.

Upload this update.xml file to the same S3 bucket and set the MIME type to application/xml.

Note down the update.xml S3 URL. It will be used in the Installing Browser Protector on Windows Devices Using Intune and Installing Browser Protector on macOS Using Kandji sections.

2.3 - Entra ID Configuration

Configuring Entra ID Single Sign-On (SSO) for Protegrity Browser Protector

To enable SSO using Microsoft Entra ID, formerly Azure AD, for the Protegrity Browser Protector extension, follow the steps below.

Create a New App Registration

1. Log in to the Microsoft Entra Admin Center.
2. Navigate to App registrations > New registration.
3. Provide the following details for the new app:
   • Name: Enter a name for the app, for example, Protegrity Browser Protector.
   • Supported account types: Choose the account type suitable for your organization. For example, accounts in this organizational directory only.
   • Redirect URI: Leave this blank for now; you will configure it in a later step.
4. Click Register to create the app registration.
5. After registration, copy the app_registration_client_id and app_registration_tenant_id displayed on the app overview page. You’ll need these IDs for configuration in Set Up Configuration File for Browser Protector.

Add Redirect URI for Single-Page Application

1. Log in to the Microsoft Entra Admin Center.
2. In the app registration overview, navigate to the Authentication tab.
3. Under Platform configurations, click Add a platform.
4. Select Single-page application from the list.
5. Add a new Redirect URI with the following format:
   • Format: https://pty_extension_id.chromiumapp.org
   • Example: https://epfnbngoodhmbeepjlcohfacgnbhbhah.chromiumapp.org/
   • Replace pty_extension_id with extension id recorded in Extension Source section.
6. Scroll down and set the Logout URL to the same URI:
   • Example: https://epfnbngoodhmbeepjlcohfacgnbhbhah.chromiumapp.org/
7. Click Save to apply the changes.

Finalize Authentication Settings

1. In the Microsoft Entra Admin Center, ensure that:
   • Access tokens and ID tokens are enabled in the Implicit grant and hybrid flows section.
   • Redirect URIs are correctly configured.
2. Save the changes.

2.4 - Cloud API Configuration

Configuring Cloud API for Protegrity Browser Protector

The Protegrity Browser Protector relies on a serverless REST API tokenization service provided by the Protegrity Cloud API. This section outlines the essential configuration steps for enabling JWT authentication in the Cloud API.

For more information about the Cloud API on AWS, refer to the Cloud API on AWS Guide 3.2.1.

Fetch Available Public Keys from the Azure AD OpenID Configuration Endpoint

1. The public keys for JWT authentication can be retrieved by calling the Azure AD OpenID configuration endpoint:

   https://login.microsoftonline.com/{tenant_id}/discovery/keys?appid={client_id}  
   

   • Replace {tenant_id} with your Azure AD tenant ID.
   • Replace {client_id} with your app registration’s client ID.

2. Use a Python script or another method to fetch the public keys.

   • Example Python script to fetch and print public keys:

        import argparse
        import jwt  
        import base64 
        import requests
        from cryptography.hazmat.primitives import serialization
     
        parser = argparse.ArgumentParser(
                          prog='JWK To PEM converter',
                          description='Helper program to download and convert public keys.',
                          epilog='Protegrity')
     
        parser.add_argument('tenant')   
        parser.add_argument('-c', '--client', help="appid for the Azure client application to narrow down keys result") 
        args = parser.parse_args()
     
        jwks_uri = f'https://login.microsoftonline.com/{args.tenant}/discovery/keys'
        if args.client:
           jwks_uri += f"?appid={args.client}"
        jwks_response = requests.get(jwks_uri)  
     
        if jwks_response.status_code != 200:
           print(f"Azure Entra request error: {jwks_response.text}")
           exit()
     
        for key in jwks_response.json()['keys']:
           public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)  
           public_pem = public_key.public_bytes(  
              encoding=serialization.Encoding.PEM,  
              format=serialization.PublicFormat.SubjectPublicKeyInfo  
           )  
           print(f"-----------Key Id: {key['kid']}--------------")
           print(f"{base64.encodebytes(public_pem).decode('utf-8').replace('\n', '')}\n")  
     

   • Run python3.12 ./tools/jwk_to_pem.py app_registration_tenant_id -c app_registration_client_id
     • Replace app_registration_tenant_id and app_registration_client_id with values recorded in Entra ID Configuration section.
     • Install pyjwt==.10.1 Python library before running the script.

3. Record PEM base64 formatted keys required by the Cloud API configuration.

• The script will print multiple public keys with their corresponding key Ids. Refer to example output below.

     -----------Key Id: CNv0AB3RwqlHFEVnaoMAshCH2XE--------------
     LS0tLS1CRUdJTiBQV...S0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==
  
     -----------Key Id: PoVKeBDIOvmTyLQ9G9BenBwos7k--------------
     LS0tLS1CRUdJTiBQV...KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==
  
     -----------Key Id: _jNwjBDnvTTK8XEdr5QUPkBRLLo--------------
     LS0tLS1CRUdJTiBQV...QUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==
  

• Record the the output for the next step.

Retrieve JWT Public Signing Key

Microsoft Azure AD maintains multiple public signing keys to ensures continuity in token validation during key transitions.

Follow the steps below to find the active signing key used for the Entra ID app registration configured in Entra ID Configuration section.

1. Set Cloud API Log Level to config:

   • Update your Cloud API configuration to set the log level to config.
   • This enables detailed logging, which will display the JWT token in the logs for debugging purposes.

   Set the log level back to its original value after debugging to avoid exposing sensitive information.

2. Retrieve the JWT Token from Logs:

   • Trigger the API call that generates the error.
   • Check the Cloud API CloudWatch logs to locate the JWT token. It will typically appear in the request logs.

3. Decode the JWT Token:

   • Use a tool like jwt.ms or any other JWT decoding tool to inspect the token.
   • Copy and paste the token into the decoding tool.
   • The decoded JWT header will look something like this:

     {  
       "alg": "RS256",  
       "typ": "JWT",  
       "kid": "exampleKeyId123"  
     }  
     

   • Note the kid value, for example, "exampleKeyId123". This identifies the public key used to sign the token.
   • Match the kid with the Key Id from step 1. Record the corresponding base64 value, for example, LS0tLS1CRUdJTiBQV…QUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==: jwt_signing_key: <>

   Microsoft may update or maintain the Azure AD service, which can involve replacing signing keys as part of operational processes. When public signing keys change, the Cloud API returns HTTP error 403 - Invalid JWT token. Verification failed.. which manifests as Protector service unavailable error in browser extension.

Cloud API Configuration for JWT Authentication

Please use the appropriate link below depending on the cloud provider in use.

2.4.1 - Configuration for AWS

When deploying the Cloud API on AWS using CloudFormation, ensure that JWT authentication is properly configured by setting the following parameters:

CloudFormation Parameters:

1. Set authorization to jwt:

   • This specifies that JWT authentication will be used to secure the API.

2. Set jwt_verify to 1:

   • Enables verification of the JWT token during API requests.

3. Set jwt_secret_base64 to the Public Key (PEM Base64 Encoded):

   • Use the jwt_signing_key public key obtained from Retrieve JWT Public Signing Key .

4. Set jwt_user_claim to upn or email:

   • Choose the claim used to identify the user. Typically, User Principal Name (upn) or email is selected based on your organization’s Entra ID configuration.

Obtain the API Gateway Endpoint

After deploying the Cloud API using CloudFormation, retrieve the API Gateway endpoint URL for the service:

1. Navigate to the CloudFormation stack in your AWS Management Console.
2. Locate the Outputs section of the deployed stack.
3. Find the output parameter labeled ApiGatewayId.
4. Use the ApiGatewayId and your AWS region to construct the endpoint URL for the Protegrity Cloud API:
   • Format: https://{ApiGatewayId}.execute-api.{Region}.amazonaws.com/pty
   • Example: If ApiGatewayId is abc123xyz and the region is us-east-1, the service endpoint URL will be:

   https://abc123xyz.execute-api.us-east-1.amazonaws.com/pty
   

5. Record this endpoint URL for use in the Browser Protector configuration.
   • protector_endpoint_url: <>

Disable IAM Authentication for the /v1/unprotect Endpoint

By default, AWS API Gateway might enforce IAM authentication for API methods. Since authentication is already handled within the Cloud API protect Lambda function, IAM authentication for the /v1/unprotect endpoint must be disabled.

1. Navigate to the API Gateway:
   Open the AWS Management Console and go to the API Gateway service.

2. Locate the API Gateway:
   Find the API Gateway deployed for the Cloud API (use the ApiGatewayId obtained in Step 4).

3. Select the /v1/unprotect Resource:
   Locate the /v1/unprotect resource in the API Gateway.

4. Choose the POST Method:
   Under Method Execution, select the POST method.

5. Set Authorization to None:
   In the Method Request settings, set Authorization to None.

6. Save the Changes:
   Confirm and save the changes.

2.4.2 - Configuration for GCP

When deploying the Cloud API on GCP, ensure that JWT authentication is properly configured by setting the following parameters:

Cloud Function Parameters (Can be set in terraform template or by GCP UI):

1. Set authorization to jwt:

   • This specifies that JWT authentication will be used to secure the API.

2. Set jwt_verify to 1:

   • Enables verification of the JWT token during API requests.

3. Set jwt_secret_base64 to the Public Key (PEM Base64 Encoded):

   • Use the jwt_signing_key public key obtained from Retrieve JWT Public Signing Key .

4. Set jwt_user_claim to upn or email:

   • Choose the claim used to identify the user. Typically, User Principal Name (upn) or email is selected based on your organization’s Entra ID configuration.

Configure GCP cloud protect function Authentication security setting:

By default, GCP cloud function might enforce IAM authentication for API methods. Since authentication is already handled within the Cloud API protect function, we can change the authentication setting to “allow for public access” as below:

1. Navigate to the GCP cloud protect function
2. On the service details screen, select the security tab
3. In the Authentication section - ensure “allow public access” is selected.

Obtain the Gateway URL:

After deploying the Cloud API using terraform, retrieve the API endpoint URL for the service:

From Google Cloud Management console,

1. Navigate to API Gateway.
2. Select the deployed API Gateway instance.
3. Under the “Gateway Details” section, copy the “Gateway URL” or “Managed Service URL”.
4. Record the displayed URL for use in the Browser Protector configuration.
   • protector_endpoint_url: <>

example: https://{gateway-id}-{hash}.{region}.gateway.dev/api

2.4.3 - Configuration for Azure

Ensure that JWT authentication is properly configured by setting the following parameters:

Navigation:

1. From Azure console, navigate to Function App and select protect function app.
2. Navigate to Settings > Environment variables

Configuration Parameters to add / update:

1. Set OPENID_ENABLED to false.

2. Set authorization to jwt:

   • This specifies that JWT authentication will be used to secure the API.

3. Set jwt_verify to 1:

   • Enables verification of the JWT token during API requests.

4. Set jwt_secret_base64 to the Public Key (PEM Base64 Encoded):

   • Use the jwt_signing_key public key obtained from Retrieve JWT Public Signing Key .

5. Set jwt_user_claim to upn or email:

   • Choose the claim used to identify the user. Typically, User Principal Name (upn) or email is selected based on your organization’s Entra ID configuration.

Obtain the Gateway URL:

After deploying the Cloud API using ARM, retrieve the API endpoint URL for the service:

From Azure Management console,

1. Navigate to the deployed API Management gateway.
2. Under APIs, select the Cloud API.
3. Locate the Gateway URL (base URL) for the API.
4. Append the operation path /v1/unprotect to the gateway URL.
5. Record the complete endpoint URL for use in the Browser Protector configuration and also pass code query parameter.
   • protector_endpoint_url: <>

example: https://{apim-name}.azure-api.net/api/v1/unprotect?code={appKey}

2.5 - Set Up Configuration File for Browser Protector

Configuring the Protegrity Browser Protector

The Protegrity Browser Protector can be customized and managed using a configuration file in JSON format distributed via MDM tools described in the installation chapters. The configuration file defines key settings, such as the service endpoint for tokenization, authentication service configuration, the data elements to be used to protect clear text values as well as administrative contact information display in the Browser Protector Extension.

Configuration File Overview

Below is an example configuration file for the Protegrity Browser Protector:

{
  "serviceEndpoint": {
    "authentication": {
      "type": "oauth2",
      "identityProvider": "microsoft_entra_id",
      "login_email_or_domain_hint": "",
      "settings": {
        "msal_api": {
          "clientId": "app_registration_client_id",
          "authority": "https://login.microsoftonline.com/app_registration_tenant_id"
        },
        "scopes": [
          "app_registration_client_id/.default"
        ]
      }
    },
    "url": "protector_endpoint_url"
  },
  "dataElements": [
    {
      "value": "data_element_1",
      "label": "data_element_1_label"
    },
    {
      "value": "data_element_2",
      "label": "data_element_2_label"
    }
  ],
  "adminContactInfo": {
    "url": "extension_admin_page_url",
    "phone": "extension_admin_phone",
    "email": "extension_admin_email"
  }
}

Summary Table of Placeholder Values

After completing all steps in pre-configuration chapter, you should have the following values recorded.

"dataElements": [
		{
			"value": "deName",
			"label": "Unprotect First Name"
		},
		{
			"value": "deAddress",
			"label": "Unprotect Address"
		}
	]

3 - Installation

3.1 - Testing the Protegrity Browser Protector Extension Locally

Test the Protegrity Browser Protector Extension Locally

For testing and validation purposes, it is necessary to run the Protegrity Browser Protector extension locally. This allows developers and administrators to ensure the extension works as expected in a controlled environment before deploying it in production. In this section, we will outline the steps to load and use a local configuration file.

Load the Extension in the Google Chrome / Microsoft Edge Browser

1. Open Chrome or Edge.
2. Navigate to the Extensions page:
   • Enter chrome://extensions (for Chrome), edge://extensions (for Edge), in the address bar and press Enter.
3. Enable Developer Mode:
   • Toggle the Developer mode switch in the top-right corner of the Extensions page.
4. Click Load unpacked:
   • Click the Load unpacked button in the top-left corner.
5. Select the Protegrity Browser Protector Extension Folder:
   • In the file dialog, navigate to the folder containing the extension’s source code and select it.
6. Verify the Extension:
   • Ensure the extension appears in the list with its name and icon. Check for any errors or warnings in the extension details.

Load the Extension JSON configuration file

1. Use the JSON configuration from the Configuration Summary step and save it to a file on your local machine, e.g. config.json.
2. Open Google Chrome / Microsoft Edge.
3. From the top-right portion of the browser click on Extensions menu, select Protegrity Browser Protector.
4. Click Select File and specify the config.json file.
5. Test the extension following the instructions in the Using Protegrity Browser Protector Extension section.

Reviewing Logs

1. Open the browser’s Developer Tools:
   • Press Ctrl + Shift + I (Windows/Linux) or Cmd + Option + I (Mac) to open Developer Tools.
2. View the Console:
   • Navigate to the Console tab to view any logs or errors produced by the extension.

Unloading the Extension

Once testing is complete, remove the extension from the browser:

• Navigate to the Extensions page.
• Locate the Protegrity Browser Protector extension and click Remove.

3.2 - Installing Browser Protector on Windows Devices Using Intune

Deploy Protegrity Browser Protector Extension with Intune

Follow these steps to configure and deploy the Administrative Template files for the Protegrity Browser Protector policy using Intune.

For more information Administrative Templates, refer to Microsoft Intune Administrative Templates.

Utility script to generate configuration files for InTune

See MDM File Generator.

Prerequisites:

• Import the following ADMX files first:
  • google.admx
  • Windows.admx
  • chrome.admx - required if installing for Google Chrome browser
  • msedge.admx - required if installing for Microsoft Edge browser

Import ADMX and ADML Files

1. Sign in to the Microsoft Intune admin center.
2. Navigate to:
   • Devices > Manage devices > Configuration > Import ADMX tab > Import.
   • Or: Devices > By platform > Windows > Manage devices > Configuration > Import ADMX tab.
3. Upload the ADMX File:
   • Replace pty_extension_id with the extension’s ID generated in pre-configuration steps.
   • If installing on Microsoft Edge, replace “SOFTWARE\Policies\Google\Chrome” with “SOFTWARE\Policies\Microsoft\Edge” for key value (two occurrences).
   • Save the file with a recognizable name, such as ProtegrityBrowserProtector.admx

<?xml version="1.0"?>  
<policyDefinitions revision="1.0" schemaVersion="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
    <policyNamespaces>  
        <target namespace="Protegrity.Policies.BrowserProtector" prefix="ptyBrowserProtector" />  
        <using prefix="windows" namespace="Microsoft.Policies.Windows" />  
    </policyNamespaces>  
    <supersededAdm fileName="" />  
    <resources minRequiredRevision="1.0" fallbackCulture="en-US" />  
    <categories>  
        <category name="Protegrity_Browser_Extension_Configuration" displayName="$(string.Protegrity_Browser_Extension_Configuration)" />  
    </categories>  
    <policies>  
        <!-- Protegrity Browser Protector Configuration -->  
        <policy name="POL_ProtegrityBrowserProtector" 
        displayName="$(string.Protegrity_Browser_Extension_Configuration)" 
        explainText="$(string.Protegrity_Browser_Extension_Configuration_HELP)"
        class="Machine" key="SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\pty_extension_id\policy" presentation="$(presentation.POL_ProtegrityBrowserProtector)">  
            <parentCategory ref="Protegrity_Browser_Extension_Configuration" />  
            <supportedOn ref="windows:SUPPORTED_Windows10" /> 
            <elements>  
                <text id="TXT_ProtegrityBrowserProtector" valueName="ProtegrityBrowserProtector" />  
            </elements>  
        </policy>  
          
        <!-- Protegrity Browser Protector Installation/Updates -->  
        <policy name="POL_ExtensionSettings" 
        displayName="$(string.ExtensionSettings)"
        explainText="$(string.POL_ExtensionSettings_HELP)"
         class="Machine" key="SOFTWARE\Policies\Google\Chrome" presentation="$(presentation.POL_ExtensionSettings)">  
            <parentCategory ref="Protegrity_Browser_Extension_Configuration" />  
            <supportedOn ref="windows:SUPPORTED_Windows10" />  
            <elements>  
                <text id="TXT_ExtensionSettings" valueName="ExtensionSettings" />  
            </elements>  
        </policy>  
    </policies>  
</policyDefinitions>  

4. Upload the ADML File:

• Replace https://s3.region.amazonaws.com/s3-bucket-name/update.xml with the URL where extension updates are hosted.
• Replace all placeholder values (e.g., app_registration_client_id, protector_endpoint_url, etc.) with configuration values recorded in pre-configuration chapter.
• Save the file with a recognizable name, such as ProtegrityBrowserProtector.adml.

<?xml version="1.0"?>  
<policyDefinitionResources revision="1.0" schemaVersion="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
    <displayName>Protegrity Browser Extension Configuration</displayName>  
    <description>Protegrity Browser Extension Configuration</description>  
    <resources>  
        <stringTable>  
            <string id="Protegrity_Browser_Extension_Configuration">Protegrity Browser Protector</string>  
            <string id="Protegrity_Browser_Extension_Configuration_HELP">Configures Protegrity Browser Protector settings.</string>  
            <string id="POL_ProtegrityBrowserProtector_HELP">Configures the JSON value for Protegrity Browser Protector settings.</string>  
            <string id="ExtensionSettings">Extension Settings</string>  
            <string id="POL_ExtensionSettings_HELP">Configures the settings for extension.</string>  
        </stringTable>  
        <presentationTable>  
            <presentation id="POL_ProtegrityBrowserProtector">  
                <textBox refId="TXT_ProtegrityBrowserProtector">  
                    <label>ProtegrityBrowserProtector</label>  
                    <defaultValue>{"serviceEndpoint":{"authentication":{"type":"oauth2","identityProvider":"microsoft_entra_id","settings":{"msal_api":{"clientId":"app_registration_client_id","authority":"https://login.microsoftonline.com/app_registration_tenant_id"},"scopes":["app_registration_client_id/.default"]}},"url":"protector_endpoint_url"},"dataElements":[{"value":"data_element_1","label":"data_element_1_label"},{"value":"data_element_2","label":"data_element_2_label"}],"adminContactInfo":{"url":"extension_admin_page_url","phone":"extension_admin_phone","email":"extension_admin_email"}}</defaultValue>  
                </textBox>  
            </presentation>  
            <presentation id="POL_ExtensionSettings">  
                <textBox refId="TXT_ExtensionSettings">  
                    <label>ExtensionSettings</label>  
                    <defaultValue>{"pty_extension_id":{"installation_mode":"normal_installed","override_update_url":true,"update_url":"https://s3.region.amazonaws.com/s3-bucket-name/update.xml"}}</defaultValue>  
                </textBox>  
            </presentation>  
        </presentationTable>  
    </resources>  
</policyDefinitionResources>  

5. Click Next.
6. In Review + Create, verify your selections and click Create.

Notes

• Once imported, ADMX templates will appear in the list.
• Use Refresh to update the list or Delete to remove templates.

Create a Profile Using Imported ADMX Files

For more details on the steps or configuration, refer to:

• ADMX-backed policies in Policy CSP.
• Role-based access control (RBAC) and scope tags.

1. Sign in to the Microsoft Intune admin center.
2. Navigate to:
   • Devices > Manage devices > Configuration > Create > New policy.
3. Enter the following properties:
   • Platform: Select Windows 10 and later.
   • Profile Type: Select Templates > Imported Administrative Templates (Preview).
4. Click Create.
5. In Basics, enter:
   • Name: Provide a descriptive name, e.g., ADMX: Protegrity Browser Protector for Windows Devices.
   • Description: (Optional) Add a brief description about the profile’s purpose, e.g., “Configures Protegrity Browser Protector security policies for managed devices.”
6. Click Next.
7. In Configuration Settings, configure the policies using the imported ADMX files specific to Protegrity Browser Protector.
8. Click Next.
9. Assign scope tags to filter the profile to specific IT groups, e.g., Security Team or Compliance Department.
10. Click Next.
11. Assign the profile to users or device groups:

• User Groups: Configured settings apply to devices where users sign in.
• Device Groups: Configured settings apply to all users on the assigned device.

12. For more information, refer to User Groups vs. Device Groups.
13. Click Next.
14. In Review + Create, verify your settings.
15. Click Create to save and assign the profile.

Assign the Profile to Devices

After creating the profile, go to the Assignments section. Assign the profile to the appropriate users or devices groups in Intune. Click Save to finalize the deployment.

Verify Deployment

On a managed device, sign in with a user account assigned to the policy. Open Chrome and navigate to chrome://policy to verify the ExtensionSettings policy is applied. Check that the extension is installed and updated from the private server.

3.3 - Installing Browser Protector on macOS Using Kandji

Deploy Protegrity Browser Protector Extension Using Kandji

Follow these steps to configure and deploy the .mobileconfig files for the Protegrity Browser Protector policy using Kandji.

Utility script to generate configuration files for Kandji

See MDM File Generator.

Testing .mobileconfig

• Test the .mobileconfig file on a single device before deploying it to a large number of devices.
• If modifications are needed, edit the .mobileconfig file, re-upload it to Kandji, and reassign it to the blueprint.

Prepare the Browser Extension installation/update .mobileconfig File

1. Use the .mobileconfig file below. Make sure to:

• Replace https://s3.region.amazonaws.com/s3-bucket-name/update.xml with the URL where extension updates are hosted.
• If installing on Microsoft Edge, replace <key>com.google.Chrome</key> with <key>com.microsoft.Edge</key>.

2. Save the file with a recognizable name, such as ProtegrityBrowserProtector.mobileconfig.

<?xml version="1.0" encoding="UTF-8"?>  
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>com.protegrity.browserprotector.install</string>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadDisplayName</key>
            <string>Protegrity Browser Protector Management</string>
            <key>PayloadContent</key>
            <dict>
                <key>com.google.Chrome</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>ExtensionSettings</key>
                                <dict>
                                    <!-- Protegrity Browser Protector Installation/Updates -->  
                                    <key>pty_extension_id</key>
                                    <dict>
                                        <key>installation_mode</key>
                                        <string>normal_installed</string>
                                        <key>update_url</key>
                                        <string>https://s3.region.amazonaws.com/s3-bucket-name/update.xml</string>
                                        <key>override_update_url</key>
                                        <true/>
                                    </dict>
                                </dict>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configuration for managing the Protegrity Browser Protector Chrome extension.</string>
    <key>PayloadDisplayName</key>
    <string>Protegrity Browser Protector Management</string>
    <key>PayloadIdentifier</key>
    <string>com.protegrity.browserprotector.install</string>
    <key>PayloadOrganization</key>
    <string>Protegrity Inc.</string>
    <key>PayloadRemovalDisallowed</key>
    <true/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist> 

Prepare the Browser Extension Configuration .mobileconfig File

1. Use the .mobileconfig file below. Make sure to:
   • If installing on Microsoft Edge, replace <key>com.google.Chrome.extensions.pty_extension_id with <key>com.microsoft.Edge.extensions.pty_extension_id</key>.
   • Replace pty_extension_id with the extension id.
   • Replace all placeholder values (e.g., app_registration_client_id, protector_endpoint_url, etc.) with configuration values recorded in pre-configuration chapter.
2. Save the file with a recognizable name, such as ProtegrityBrowserProtectorSettings.mobileconfig.

<?xml version="1.0" encoding="UTF-8"?>  
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadType</key>
            <string>com.apple.ManagedClient.preferences</string>
            <key>PayloadVersion</key>
            <integer>1</integer>
            <key>PayloadIdentifier</key>
            <string>com.protegrity.browserprotector.settings</string>
            <key>PayloadEnabled</key>
            <true/>
            <key>PayloadDisplayName</key>
            <string>Protegrity Browser Protector Management</string>
            <key>PayloadContent</key>
            <dict>
                <!-- Protegrity Browser Protector Configuration -->  
                <key>com.google.Chrome.extensions.pty_extension_id</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>
                            <key>mcx_preference_settings</key>
                            <dict>
                                <key>ProtegrityBrowserProtector</key>
                                <dict>
                                    <key>serviceEndpoint</key>
                                    <dict>
                                        <key>authentication</key>
                                        <dict>
                                            <key>type</key>
                                            <string>oauth2</string>
                                            <key>identityProvider</key>
                                            <string>microsoft_entra_id</string>
                                            <key>settings</key>
                                            <dict>
                                                <key>msal_api</key>
                                                <dict>
                                                    <key>clientId</key>
                                                    <string>app_registration_client_id</string>
                                                    <key>authority</key>
                                                    <string>https://login.microsoftonline.com/app_registration_tenant_id</string>
                                                </dict>
                                                <key>scopes</key>
                                                <array>
                                                    <string>app_registration_client_id/.default</string>
                                                </array>
                                            </dict>
                                        </dict>
                                        <key>url</key>
                                        <string>protector_endpoint_url</string>
                                    </dict>
                                    <key>dataElements</key>
                                    <array>
                                        <dict>
                                            <key>value</key>
                                            <string>data_element_1</string>
                                            <key>label</key>
                                            <string>data_element_1_label</string>
                                        </dict>
                                        <dict>
                                            <key>value</key>
                                            <string>data_element_2</string>
                                            <key>label</key>
                                            <string>data_element_2_label</string>
                                        </dict>
                                    </array>
                                    <key>adminContactInfo</key>
                                    <dict>
                                        <key>url</key>
                                        <string>extension_admin_page_url</string>
                                        <key>phone</key>
                                        <string>extension_admin_phone</string>
                                        <key>email</key>
                                        <string>extension_admin_email</string>
                                    </dict>
                                </dict>
                            </dict>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configuration for managing the Protegrity Browser Protector Chrome extension.</string>
    <key>PayloadDisplayName</key>
    <string>Protegrity Browser Protector Management</string>
    <key>PayloadIdentifier</key>
    <string>com.protegrity.browserprotector.settings</string>
    <key>PayloadOrganization</key>
    <string>Protegrity Inc.</string>
    <key>PayloadRemovalDisallowed</key>
    <true/>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
</dict>
</plist>  

Log In to Kandji

Visit the Kandji dashboard and log in with your administrative credentials.

Create a New Library Item

1. Navigate to the Library section in the Kandji dashboard.
2. Click Add New in the upper-right corner.
3. Select Custom Profile from the list of options.

Upload the .mobileconfig Files

1. In the Custom Profile section:
   • Click Upload Profile.
   • Select your ProtegrityBrowserProtector.mobileconfig file.
2. Kandji will parse the .mobileconfig file and display its configuration details.

Review and Verify the Profile

1. Carefully review the uploaded configuration:
   • Ensure the Payload Display Name, Payload Description, and other details match the intended configuration.
   • Confirm that the policy enforces the Protegrity Browser Protector settings correctly.
2. Click Save to save the profile.

Assign the Profile to a Blueprint

1. Go to the Blueprints section in the Kandji dashboard.
2. Select the blueprint for the devices you want to apply this policy to.
3. Click Edit Blueprint.
4. Scroll to the Custom Profiles section and click Add.
5. Select the newly created Protegrity Browser Protector profile from the list.
6. Click Save Changes to update the blueprint.

Deploy the Policy

1. Devices assigned to the blueprint will automatically receive the new configuration the next time they check in with Kandji.
2. To enforce the policy immediately:
   • Go to the Devices section.
   • Select a device assigned to the blueprint.
   • Click Sync Device to push the updated configuration.

Verify Policy Deployment

1. On a target device, open System Preferences > Profiles to confirm the new configuration profile (Protegrity Browser Protector Management) is installed.
2. Open Google Chrome / Microsoft Edge (based on where the extension was installed) on the device and confirm:
   • The Protegrity Browser Protector extension is installed.
   • The enforced settings (OAuth2 authentication, service endpoint, etc.) are applied.

Optional: Monitor Compliance

1. Navigate to the Devices section in Kandji to view the compliance status.
2. Look for any deployment errors or issues and resolve them as necessary.

3.4 - MDM File Generator Utility

pty_policy_generator.py generates MDM policy configuration files for deploying the Protegrity Browser Protector extension on Mac and Windows. It currently supports both Chrome and Edge browser.

Output

Mac — 4 files written to output-mac/

Windows — 4 files written to output-windows/

Inputs

Usage

The script accepts input in three ways.

CLI arguments

python3 pty_policy_generator.py \
  --platform mac \
  --extension-id glktrkejbpmhpaeekkmfinokdlbhcolr \
  --update-url "https://example.com/update" \
  --runtime-blocked-hosts "http://*, https://*" \
  --runtime-allowed-hosts "https://allowed1.com, https://allowed2.com" \
  --configuration-file config.json

JSON input

Pass all parameters as a single JSON string using --json-input.

python3 pty_policy_generator.py --json-input \
  '{"extension_id":"glktrkejbpmhpaeekkmfinokdlbhcolr","update_url":"https://example.com/update.xml","runtime_blocked_hosts":"http://*, https://*","runtime_allowed_hosts":"https://allowed1.com, https://allowed2.com","configuration_file":"config.json","platform":"windows"}'

Interactive prompts

Run with no arguments. The script will prompt for each value individually.

python3 pty_policy_generator.py

extension-id: glktrkejbpmhpaeekkmfinokdlbhcolr
update_url: https://example.com/update.xml
runtime_blocked_hosts (comma-separated, Enter for default http/https): http://*, https://*
runtime_allowed_hosts (comma-separated): https://allowed1.com, https://allowed2.com
configuration file path: config.json
platform (mac or windows): mac

Requirements

• Python 3.10 or later
• Standard library only (no third party packages required)

4 - Testing and Troubleshooting

Verifying Policy Deployment

On Managed Devices

1. Ensure assigned devices have synced with Intune:
   • Open Settings on the device.
   • Navigate to Accounts > Access work or school > Sync to initiate a manual sync.
2. Open the browser on the managed device to confirm that Protegrity Browser Protector settings are active.

In Microsoft Endpoint Manager

1. Navigate to Devices > Configuration profiles.
2. Select the policy profile you created.
3. View the Device status and User status tabs to confirm successful deployment.

Testing Browser Extension

1. Log in to a managed device and open the browser.
2. Verify that the Protegrity Browser Protector extension is installed and enabled.
3. Test the extension functionality by selecting tokenized text on a webpage and observing the reveal operation.

Troubleshooting

• If the extension does not appear:
  • Confirm that the Intune configuration profile is assigned to the correct device group.
  • Ensure the HTTPS file server is accessible from the device.
• If the tokenized text does not reveal:
  • Verify the connection to the Protegrity Cloud Protect API.
  • Check that the user has sufficient permissions to access the protected data.