Managing the JSON Filtering Authorizer

JSON Filtering Authorizer Overview

The JSON Filtering Authorizer provides comprehensive and dynamic filtering for API JSON response fields based on Policies configured in PlainID. Acting as middleware, it ensures sensitive data is masked or filtered appropriately, maintaining compliance with security and regulatory requirements. This Authorizer can be integrated with API Gateways to seamlessly post-process API JSON responses before serving them back to calling clients, offering flexibility in securing data.

This capability enables organizations to customize their data protection rules, while maintaining control over how sensitive information is exposed to end users. By leveraging PlainID's Policy Decision Point (PDP), the JSON Filtering Authorizer dynamically enforces and applies Policy rules on JSON data responses in real-time.

How the JSON Filtering Authorizer Works

The JSON Filtering Authorizer operates as middleware, processing data protection requests for JSON responses received from a service. It intercepts the response via a calling service or API Gateway before it is delivered to the client. Upon receiving the request, the Authorizer evaluates it using the PDP's authorization decision and predefined policies that encapsulate data protection logic. It then applies the necessary transformations to the JSON payload, producing an authorized JSON response that can be securely returned to the client.

JSON Data Enforcing Process

To enforce the JSON Data:

1. Initiate a request to the Authorizer containing a payload with three parts:

• parameters - Request configuration flags that guide the Authorizer on how to evaluate the request.

• plainid - A set of PDP request parameters that the Authorizer uses to generate the Authorization request.

• json - The JSON payload intercepted from the service response that needs processing for Policy-based filtering.

2. Generate and send a PDP request through the Authorizer, based on configuration and the request parameters included in the Authorizer request. The Authorizer can leverage one of two PDP decision flows: Policy Resolution decisions or User Access Token with assetContext decisions.

3. Parse the Authorization decision response from the PDP and process the JSON based on the filtering and masking instructions derived from it. The Authorizer enforces Policy-Based Data Protection rules by filtering specific data objects and/or masking specific sensitive data properties.
   Note: Parsing the PDP response and applying the filtering and masking instructions depend on the Actions defined in the Policy Modeling. See more details about Actions below.

4. Return modified JSON responses to the Gateway/Service, ensuring that only authorized data is served back to the client.

Flow Diagram

1. User logs in to Application and requests data.
2. The Application calls a microservice to request data from the data repository.
3. The microservice receives data back and generates the JSON object(s) to be returned to the Application/user.
4. The microservice or GW sends the JSON objects to the PlainID JSON Authorizer for data protection processing.
5. The PlainID JSON Authorizer redacts or masks objects and properties dynamically based on PlainID’s Policy evaluation, and returns Authorized Objects to the microservice.
6. The microservice returns the Objects to the Application, and the user receives only Authorized Data.

Authorizer Request & Parameters

An Application Service or a Gateway intercepting specific data requests initiates an API call to the JSON Authorizer enforce endpoint: [http://{{authorizer host name}}:{{authorizer listening port}}/enforce](http://{{authorizer host name}}:{{authorizer listening port}}/enforce)

The request to the Authorizer includes these key request parameters:

Note: In addition to the parameters included in the request body sent to the Authorizer, all headers in the request are forwarded to the PDP and can be utilized based on PDP capabilities. For example, an Authorization Header containing a JWT can be passed instead of a Client Secret to authenticate the PDP request.

PDP Calculation Methods

• Policy Resolution Calculation (resolution): Processes filtering and masking instructions received from the PDP and applies them to the JSON response data. Ideal for scenarios where Policies depend on existing data properties in the JSON response and do not require additional contextual data.
• Asset Context Calculation (context): Extracts additional information from the JSON and sends it as assetIDs used as assetContext in the PDP User Access Token calculation flow. This is useful when Attributes required for Policy evaluation are missing from the JSON response and need to be fetched for Policy-based decision context.

When using the context calculation type, use these additional parameters:

• parameters.assetId: Defines the path in the JSON payload (using gjson syntax) for the assetID sent as assetContext to the PDP.
• parameters.protectedObject: Defines the Asset Type of the assetId, used in Policies as the resource being protected by the Authorizer. This Asset Type is defined as data Asset Type, and Policies use it to define data filtering logic.

Example Request Structure

{

  "parameters": {

    "root": "result",

    "assetType": "<attributes asset type>", //default "columns"

    "calculationType" : "context", 

    "assetId": "<json path>",

    "protectedObject": "<data asset type>"

    //"filter" : true

    // "maskString": "---"

  },

  "plainid": {

    "entityTypeId": "<user_id>",

    "entityId": "<user_id>",

    "clientId": "<client_id>",

    "clientSecret": "<client_secret>",

    "environment": {

      "resourceFullPath": [ "<data mapper resource full path>" ]

    }

    // any other PDP request property or flag

  },

"json": <JSON payload to be processed>

}

Policy Modeling

This Authorizer applies masking and filtering based on Policies to safeguard data. It requires Asset Type modeling to represent relevant data objects and structures, as well as the classification of sensitive or other critical data Attributes.

Additionally, you are required to define data Policies that reflect your business logic for data protection.

For more details on setting up Asset Types, modifying Data Access, and understanding how the PDP evaluates Policies using Policy Resolution and User Access Token with Asset Context, refer to the relevant documentation.

Actions

The JSON Authorizer relies on the Action returned in the PDP response to execute predefined data processing instructions. These are the predefined behaviors using Actions in the PDP access and privileges response sections:

• Access: Defines allowed data properties/columns.

  • The default action is MASK, specifying that a data property is accessible only after being masked.
  • When using MASK, the Authorizer applies masking to the data property based on its data type and the masking configurations defined earlier.
  • Custom Actions for data properties enable masking with specific action values. Examples include:
    • To mask the category property in JSON with the value --- while other masking uses the default ***, define a Policy for the category property and assign it the Action CategoryMasking with the action value ---.
    • If you want to set a value for a specific field in a JSON payload when that field is missing or empty, follow these steps:
      1. Define a rule set specifically for the target JSON property (similar to how you set up masking or filtering rules).
      2. Create a new action. You can name this action anything you like.
      3. Assign a value to the action. If the JSON property is missing or empty at Runtime, the property will be created (if needed) and the value will be inserted automatically.

• Privileges: Defines filtering rules.

  • Privileges support Conditional Masking, which specifies the logic for determining which data properties of an object are masked. This applies to all Actions except filter.
  • The filter Action instructs the Authorizer to apply the privileges logic from the PDP Policy Resolution response to determine which response objects are Authorized and filter out all others.

Data Mappers

Data Mappers enable users to distinguish between the logical representation of Asset Types and Attributes used in Policies and their physical representation in the data model — specifically within the JSON structure of each protected service.

They are particularly useful when dealing with complex JSON objects or arrays that require referencing data properties in nested paths.

Example
If an email field needs to be protected by masking and this field appears in different locations or paths across JSONs from various services, Mappers can be used to manage the transformation effectively.

Assuming an Asset Type Customer Accounts is modeled with several Attributes, including Email, and Policies are defined to mask this field under specific conditions:

• Service 1: CustomersAccounts, uses the accountEmail property as part of the account object in its JSON structure.

• Service 2: Contracts, uses the customerEmail property as part of a sub-object array, customerDetails.

To protect data across these two services using a single logical template for Customer Accounts, Data Mappers can be leveraged:

• Define Mappers for the Asset Type:

• Mapper Name: Accounts

• Mapper Name: Contracts

• Define Attribute Mappers for the Email Attribute:

• For Mapper Accounts, define Attribute Mapper accountEmail

• For Mapper Contracts, define Attribute Mapper customerDetails.#.customerEmail

Note: When defining a nested path in the Attribute Data Mapper, use the JSON Path syntax sample from this table. The path is relative to the defined root of the enforcement request.

With this setup, when Service #1 calls the Authorizer, it sends resourceFullPath with the value Accounts and receives the logical filter for Email in the Policy Resolution response, using accountEmail as the property name. Similarly, when Service #2 sends Contracts in the resourceFullPath, it receives the logical filter for Email as customerDetails.#.customerEmail.

For more information, check out our article on Data Mappers.

Authorizer Setup and Configuration

Deploy the Authorizer, and set up the configuration according to the below table:

Example Use Case

In this example we demonstrate how the Authorizer can be used to mask sensitive PII data from a JSON response of a data service returning Accounts data to clients.

For this example the JSON structure of the Accounts service looks like this -

{
  "data": {
    "accounts": [
      {
        "accountId": "acc123",
        "accountName": "Company X",
        "accountType": "Business",
        "accountCategory": "Premium",
        "accountBalance": 200000,
        "contactDetails": {
          "contactName": "John Doe",
          "contactDoB": "1974-11-09"
        }
      },
      {
        "accountId": "acc567",
        "accountName": "Company Y",
        "accountType": "Business",
        "accountCategory": "Regular",
        "accountBalance": 1000,
        "contactDetails": {
          "contactName": "John Doe",
          "contactDoB": "1983-10-07"
        }
      },
      {
        "accountId": "acc999",
        "accountName": "Jane Doe",
        "accountType": "Private",
        "accountCategory": "Regular",
        "accountBalance": 68000,
        "contactDetails": {
          "contactName": "Jane Doe",
          "contactDoB": "1986-06-06"
        }
      },
      {
        // ...
      },
      {
        // ...
      }
    ]
  }
}

Account Asset Type and a Data Catalog Asset Types need to be modeled with the data structure.
Policies are modelled to mask the accountBalance for Premium Accounts (which is a sensitive data property when the account is set to Premium) and the contactDoB as PII. Additionally, they filter out Private Accounts.
We also define a Data Mapper for the Account Asset Type with the value AccountsService and reference it in an Attribute data mapper for the Attribute accountCategory with mapper value accountCategory.
An enforce request to the Authorizer is sent using the above payload sent under the json property, along with these parameters:

{

"parameters": {
    "root": "accounts",
    "assetType": "Data Catalog",
    "calculationType" : "resolution"
  },
  "plainid": {

    "entityTypeId": "<user_id>",
    "entityId": "<user_id>",
    "clientId": "<client_id>",
    "clientSecret": "<client_secret>",
    "environment": {
      "resourceFullPath": [ "AccountsService" ]
    }
  },
"json": <the above example JSON payload>
}

The Authorizer processes the response based on the PDP's instructions to mask sensitive and PII properties when the account is Premium, resulting in the following output:

{
  "data": {
    "accounts": [
      {
        "accountId": "acc123",
        "accountName": "Company X",
        "accountType": "Business",
        "accountCategory": "Premium",
        "accountBalance": null,
        "contactDetails": {
          "contactName": "John Doe",
          "contactDoB": "***"
        }
      },
      {
        "accountId": "acc567",
        "accountName": "Company Y",
        "accountType": "Business",
        "accountCategory": "Regular",
        "accountBalance": 1000,
        "contactDetails": {
          "contactName": "John Doe",
          "contactDoB": "***"
        }
      },
      {
        // ...
      },
      {
        // ...
      }
    ]
  }
}

Supported JSON Path Syntax

Path Structure, expressed by referencing a series of JSON components (properties) separated by . sign and/or using the special characters # \ * ?.

Path Expression Characters

Simple and Complex Path Expressions: Example Table with JSON Sample

{  
  "name": {"first": "Tom", "last": "Anderson"},  
  "age":37,  
  "children": ["Sara","Alex","Jack"],  
  "fav.movie": "Deer Hunter",  
  "friends": [  
    {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},  
    {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},  
    {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}  
  ]
}

Dry Run Mode

You can safely test your JSON authorizer Policies using Dry Run Mode. Instead of actually masking or filtering the JSON payload, this mode simulates the Policy logic and logs the changes that would have been applied.

To enable Dry Run Mode:

1. Add a metadata attribute with the key "DRY_RUN" to your Policy.
2. Set its value to the asset identifier you want to reference in the logs.
   Example JSON payload:

{
  "result": [
    {
      "BillingState": "CA",
      "Cases": [
        {
          "AccountId": "1111MMMMM",
          "CaseNumber": "00000000",
          "ContactEmail": "frank@gmail.com",
          "ContactPhone": "(777) 777-7777",
          "Id": "7001d000002vuQ5AAI",
          "type": "Case"
        }
        ...
      ],
      "Id": null,
      "Name": "Company",
      "type": "Account"
    }
    ...
  ]
}

3. Add the metadata attribute "DRY_RUN" with the value AccountId to your Policy.

Resulting log:

INFO Enforcement by Policy Cases-PII on **AccountId** 1111MMMMM was skipped for User u1234