Pre-Configuration

• 1: Extension Source Code
• 2: Host Extension On Private Server
• 3: Entra ID Configuration
• 4: Cloud API Configuration
• 4.1: Configuration for AWS
• 4.2: Configuration for GCP
• 4.3: Configuration for Azure
• 5: Set Up Configuration File for Browser Protector

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 - 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.

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.

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.

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.

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

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}

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"
		}
	]