InCountry Border documentation

This guide provides information about InCountry Border and how you can use it for the implementation of data residency services without using the REST API. For the details on managing Border configurations on InCountry Portal, please check our documentation.

Overview

InCountry Border is a component of the InCountry platform which allows you to take advantage of data residency services without developing any solutions with the InCountry SDK. This component integrates between your customer-facing frontend and system backend. It provides on-the-fly redaction and unredaction of regulated or sensitive data transmitted during the execution of API requests.

Data redaction and unredaction rules are specified within a JSON file. This configuration file is further deployed on the InCountry Border side.

Pre-requisites

Before you proceed to use InCountry Border you need to do the following:

1. Identify all REST endpoints which you want to integrate with InCountry Border and create a list of them.
2. Identify data that is passed or retrieved from each REST endpoint.
3. Identify which data is regulated and which data can be used as-is. Regulated data will further follow the redaction and unredaction rules which InCountry sets up for you.

Requirements for REST requests

InCountry Border imposes several requirements for execution of REST requests, as follows:

1. Data requests are performed through RESTful API. Data is communicated in the JSON format between the customer-facing frontend and system backend of the application.
2. For the correct execution of modification (create, update) requests, there must be a field (error correction field) with a random output redaction strategy on it.
3. id of a newly created record must be present in the response to the request for creating a new record.
4. id of the record should be present in the body of a request or in the URL request (for example, POST /users/1) in data requests for updating records.
5. id of the record should be present in the URL request for data requests for deleting records.
6. Data requests should be performed in the JSON format (content-type: application/json) if data redaction should be applied. Other data formats will be ignored and will be passed as-is.

Data redaction flow

Data redaction is automatically applied by InCountry Border according to the configured data redaction rules.

Let’s imagine a situation. We have a system that allows you to manage authors and their posts. The system provides the basic capabilities for managing authors and their posts (like creating, reading, updating, or deleting). The author entity includes both regulated and non-regulated data, as follows:

{
  "author_alias": "acdoyle",
  "email": "acdoyle@gmail.com",
  "first_name": "Arthur",
    "middle_name": "Conan",
  "last_name": "Doyle",
  "birthdate": "1859-05-22",
  "address": {
    "street": "221b, Baker street",
    "city": "London",
    "location": "Sherlock Holmes Shelter"
      }
}

Within this data structure, we want to redact fields containing sensitive data, as follows:

• email
• first_name
• middle_name
• last_name
• birthdate
• street

The rest of the fields should be passed as-is without redaction.

We publish a newly created page by sending a POST request to the REST endpoint, as follows:

POST https://crm-services.com/api/authors/

{
  "author_alias": "acdoyle",
  "email": "acdoyle@gmail.com",
  "first_name": "Arthur",
    "middle_name": "Conan",
  "last_name": "Doyle",
  "birthdate": "1859-05-22",
  "address": {
    "street": "221b, Baker street",
    "city": "London",
    "location": "Sherlock Holmes Shelter"
      }
}

To correctly handle redaction of these six fields, InCountry Border will apply different redaction strategies to the payload with regulated data to the /pages endpoint. In the current example, we have six regulated fields, for each field, a specific strategy is applied. Each strategy may take additional parameters. In our case, the path and strategy parameters are applied, as follows:

1. The path parameter is a jsonpath string that defines the field in the request body.
2. The strategy is a tokenization algorithm that is applied to the field according to the applied redaction strategy.

InCountry Border supports the following tokenization algorithms for redaction of sensitive data:

1. alphaNumeric - applies an alpha-numeric hash to a string containing letters and numbers. The produced alphanumeric string varies during every redaction.
2. alphaNumericLowerCase - applies a lower-case alphanumeric hash to a string containing letters and numbers.
3. alphaPrepended - applies a prefix comprised of a single letter.
4. email - applies an email-pattern string, e.g. dsf34fsdf@redactedemail.com. The produced email-pattern string varies during every redaction.
5. plain - forwards the original value.
6. one - applies '1' ( a single digit).
7. zero - applies '0' (a single digit).
8. numeric - applies a random numeric value of the length equal to the original value.
9. dateISO - applies a random date in the ISO format.
10. defaultDateISO - applies a random date in the default ISO format (1970-01-01T00:00:00Z).
11. fixed - applies any hardcoded value. If you select this option, in the Value box, enter the value that should be applied by default.
12. emailPersistent - applies an email-pattern string that remains the same for the same email address during every redaction.
13. alphaNumericPersistent - applies an alpha-numeric hash that remains the same for the same alphanumeric string during every redaction.

Once InCountry Border captures this POST request, it applies strategies and modifies this request, as follows:

{
  "author_alias": "acdoyle",
  "email": "bf4db4dd915b0d6a9e4b@redactedemail.com",
  "first_name": "52b67b60260da3937510",
    "middle_name": "333c50f47c9a71d202a6",
  "last_name": "47d68ef4cc6eb9372c39",
  "birthdate": "1200-07-02",
  "address": {
    "street": "redacted_street_fixed",
    "city": "London",
    "location": "Sherlock Holmes Shelter"
      }
}

Along with tokenization, InCountry Border also performs encryption of regulated data prior to its saving to the InCountry platform.

The key1 - key25 attributes can be used for record lookup and must be explicitly defined in the Searchable section within the configuration file. These keys may contain non-regulated data too if you need to search against these fields.

"searchable": {
        "key1": "$.first_name",
        "key2": "$.last_name",
        "key3": "$.email",
        "key4": "$.birthdate"
      }

Upon successful data saving, InCountry Border can further forward a tokenized request to the customer’s backend. At this point, the regulated data is stored in the encrypted format on the InCountry platform and tokenized data is sent to the customer’s backend. The backend returns an identifier of a newly created record.

InCountry Border intercepts this response and updates the profile_key with the actual value from the customer’s database.

{
    "author_id": "ACD4668774"
}

Following up on this example, let’s try to read information about posts written by a specific author including the redacted data about them.

GET https://crm-services.com/api/authorPosts/

Without the InCountry Border, the system returns an array of posts with information about authors, as follows:

[
  {
    "post_id": 646494631654876941313,
    "title": "Conan Doyle announces a new story",
    "post_body": "Conan Doyle will soon announce a new store about Sherlock Holmes",
    "author": {
        "author_id": "ACD4668774",
        "author_alias": "acdoyle",
    "email": "acdoyle@gmail.com",
    "first_name": "Arthur",
        "middle_name": "Conan",
    "last_name": "Doyle",
        "birthdate": "1859-05-22"
    }
  },
  {
    "post_id": 6464946316548769413547,
    "title": "Agatha Christie releases a new detective story",
    "post_body": "Agatha Christie is about to publish a new detective story about Hercule Poirot",
    "author": {
        "author_id": "AMC4668778",
        "author_alias": "amcchristie",
    "email": "achristie@gmail.com",
    "first_name": "Agatha",
        "middle_name": "Mary Clarissa",
    "last_name": "Christie",
        "birthdate": "1890-09-15"
  }
]

Data that is stored about this post on the InCountry platform is the following:

{
  record_key: 'some UUID',
  body: 'encrypted({first_name, middle_name, last_name, email, birthdate, address.street})',
  key1: 'Arthur',
  key2: 'Doyle',
  key3: 'acdoyle@gmail.com'
  key4: '1859-05-22'
}

Data that is stored about this page in the customer’s database is the following:

{
  pageId: 'page1',
  title: 'How to follow compliance requirements',
  first_name: '52b67b60260da3937510',
  middle_name: '333c50f47c9a71d202a6',
  last_name: '47d68ef4cc6eb9372c39'
  email: 'bf4db4dd915b0d6a9e4b@redactedemail.com',
  birthdate: '1200-07-02',
  address: {
    street: 'redacted_street_fixed',
    city: 'London',
    location: 'Sherlock Holmes Shelter'
  created_at: '2000-09-23T08:06:07.217Z'
}

InCountry Border supports the three basic types of backend-frontend interactions:

1. mutation (POST, PUT)
2. deletion (DELETE)
3. reading (GET)

If you need to mutate an entity that includes regulated data, InCountry Border redacts this query and saves regulated data on the InCountry platform, and forwards the data request with tokenized data.

If you need to get regulated data, InCountry Border unredacts data stored in the customer’s database by using the previously saved data on the InCountry platform.

Configuration JSON file

note

The configuration JSON file is produced by the InCountry Portal once you save your Border configuration. For the details on management of Border configuration, please check our documentation.

The configuration JSON file is used to manage the behavior of InCountry Border for redaction and unredaction of payloads with regulated data. The configuration structure looks as follows:

{
  "country": "in",
  "endpoint": "https://in-mt-01.api.incountry.io",
  "environmentId": "a4cded23-f491-4235-9821-4c088256ee45",
  "name": "Border integration",
  "redactions": [
    {
      "collectionName": "authors",
      "entityErrorCorrectionFieldPath": "$.email",
      "entityIdPath": "$.author_id",
      "method": "POST",
      "path": "/api/authors/?$",
      "searchable": {
        "key1": "$.first_name",
        "key2": "$.last_name",
        "key3": "$.email",
        "key4": "$.birthdate"
      },
      "strategies": [
        {
          "path": "$.first_name",
          "strategy": "alphaNumericPersistent",
          "strategyOptions": {
            "length": 20,
            "storeField": true
          }
        },
        {
          "path": "$.middle_name",
          "strategy": "alphaNumeric",
          "strategyOptions": {
            "length": 20,
            "storeField": true
          }
        },
        {
          "path": "$.last_name",
          "strategy": "alphaNumericPersistent",
          "strategyOptions": {
            "length": 20,
            "storeField": true
          }
        },
        {
          "path": "$.email",
          "strategy": "email",
          "strategyOptions": {
            "length": 20,
            "storeField": true
          }
        },
        {
          "path": "$.birthdate",
          "strategy": "dateISO",
          "strategyOptions": {
            "storeField": true
          }
        },
        {
          "path": "$.address.street",
          "strategy": "fixed",
          "strategyOptions": {
            "storeField": true,
            "value": "redacted_street_fixed"
          }
        }
      ]
    }
  ],
  "target": "https://crm-services.com",
  "unredactions": [
    {
      "collections": [
        {
          "entityErrorCorrectionFieldPath": "$.author.email",
          "entityIdPath": "$[*].author.author_id",
          "name": "authors",
          "strategies": [
            {
              "originalPath": "$.first_name",
              "path": "$.author.first_name"
            },
            {
              "originalPath": "$.middle_name",
              "path": "$.author.middle_name"
            },
            {
              "originalPath": "$.last_name",
              "path": "$.author.last_name"
            },
            {
              "isErrorCorrectionField": true,
              "originalPath": "$.email",
              "path": "$.author.email"
            },
            {
              "originalPath": "$.birthdate",
              "path": "$.author.birthdate"
            }
          ]
        }
      ],
      "method": "GET",
      "path": "/api/authorPosts/?$"
    }
  ]
}

The JSON configuration file is comprised of the three sections, as follows:

1. meta information
2. redactions
3. unredactions

Meta information

This section specifies general information about the country and environment where regulated data will be stored.

Parameter	Description
country	A code of the country which is used to construct a PoP API request.
endpoint	An address of the PoP API endpoint in the target country where regulated data will be stored.
environmentId	A unique identifier of the environment for storing regulated data.
name	A name of the Border configuration.
target	A home URL address of the application.

Redactions

This section specifies the redaction rules that are applied to data requests passing from the customer-facing frontend to the application’s backend. Each rule may include the following fields:

Parameter	Description
collectionName	A customer's collection name. For example pages for the pages collection. It is used along with Entity ID to uniquely identify an entity throughout all the customer's records.
entityErrorCorrectionFieldPath	A JSON path to the field that is used for error correction (used as a unique identifier of records, for example, email, id).
entityIdPath	A JSON path to the entity identifier coming from the application’s backend after the successful request execution within the customer’s system.
method	A request method that is handled by InCountry Border for redaction of regulated data.
searchable	A list of the record’s fields saved to the keyN fields supporting search on the InCountry platform.
strategies	An array of objects that define redaction strategies applied to the fields within the request payload.
path	A JSON path to the field subject to redaction within the request payload.
strategy	A name of the redaction strategy that is applied to the matched field.
strategyOptions	A list of parameters specific for the used redaction strategy.
length	Length of the produced redacted value.
storeField	A mode which is applied to the field, as follows: true - the field is redacted and saved to the InCountry platform. false - the field is redacted but is not saved to the InCountry platform.
value	A fixed value that is applied during redaction. This parameter is specific for the fixed strategy.

Unredactions

This section specifies the unredaction rules that are applied to the response from the customer's backend. Each rule may include the following fields:

Parameter	Description
method	A request method that is handled by InCountry Border for the unredaction of regulated data.
path (attributed to a method)	A regular expression to match the endpoint used for the unredaction of the redacted response body.
collections	An array of objects defining entities within the response body. Each response may potentially contain data from multiple collections. For example, when you fetch pages data, it may also include authors data (author of a page). Each collection item must describe all the needed unredactions for the matching path.
name	A name of the collection which should be used to retrieve the clear-text values from the InCountry platform.
entityIdPath	A JSON path to the entity identifier coming from the application’s backend after the successful request execution within the customer’s system.
entityErrorCorrectionFieldPath	A JSON path to the field that is used for error correction (used as a unique identifier of records, for example, email, id).
strategies	A list of mappings between object’s fields defined in the redaction rules (within the request payload) and in the unredaction rules (within the response body).
path (attributed to a strategy)	A JSON path to the field subject to the unredaction within the response body.
originalPath	A JSON path to the field subject to redaction within the request payload (should be used from the redaction rules).
isErrorCorrectionField	A flag that indicates whether the field is used for error correction.

Request structure and modifications

When integrating InCountry Border into your system, please ensure that the application’s frontend points to InCountry Border instead of the application’s backend, so all the requests are passed through InCountry Border.

An example of URL for the tenant’s application frontend looks as follows:

https://{border_url}/x-inc-{tenant}/{tenant_rest_enpoint}

The URL is comprised of the following parts:

Parameter	Description
{border_url}	URL of InCountry Border you want to use.
{tenant}	Name of the tenant (customer).
{tenant_rest_endpoint}	REST endpoint (for example /pages/page1).

Alternatively, you can define a tenant through the X-INC-CLIENT-ID header when performing requests through InCountry Border. This approach will not work when using the CORS policy for handling requests, because custom headers are not allowed in the preflight requests. In this case, the URL to point for the tenant’s application frontend will be as follows:

https://{border_url}/{tenant_rest_enpoint}

Let’s imagine a case when the country of data origin is Singapore. The name of the tenant is incountry. We also want to use InCountry Border deployed in Singapore and its endpoint, as follows:

https://sg-proxy-mt-01.incountry.io

InCountry Border is using Singapore PoP API

https://sg-mt-01.incountry.io

The resulting URL for an endpoint that should be used by the tenant’s application frontend will be as follows:

https://sg-proxy-mt-01.incountry.io/x-inc-incountry/pages/page1

or

https://sg-proxy-mt-01.incountry.io/pages/page1

For the second URL, you need to use the request header X-INC-CLIENT-ID=incountry.

You need to replace all the existing REST endpoints that the application frontend uses with the modified URL’s passing requests through InCountry Border.

Email Gateway

Email Gateway is a part of InCountry Border. It resides between the customer’s application (SaaS platform) that sends outbound emails and the customer’s SMTP server located in the recipient’s country of origin. It captures outbound emails with regulated data placeholders, identifies them according to the pre-defined patterns, and then substitutes these placeholders with clear-text values, such as names and email addresses. Once the data is unredacted, it sends emails via a direct SMTP connection to the customer’s SMTP server that further delivers this email to target recipients.

Email handling workflow

Typically, a client application sends an email with regulated data directly to the addressee, violating local data regulations if the application server is located in a country different from the recipient’s country of origin. With the InCountry platform, the client application sends an email with placeholders containing hashed values to Email Gateway that identifies them and retrieves regulated data from the InCountry platform against the specific identifiers. Email Gateway replaces these placeholders with the recipient’s name and email address in the TO, FROM, SUBJECT, and BODY fields of the outbound email. Then it sends the email with clear-text values to the customer’s SMTP server that delivers an email with regulated to the recipient.

Email Gateway works in conjunction with InCountry Border and uses the shared configuration that defines SMTP authentication credentials for the customer’s SMTP server. The customer’s SMTP server must be in the recipient’s country of origin so that no compliance regulations are violated.

This allows the customers' applications to comply with data residency regulations without modifying the underlying codebase and setting up data stores for regulated data in multiple countries.

Email requirements

Email Gateway imposes requirements on emails. as follows:

1. Only one addressee is in the To field.
2. The CC and BCC fields are ignored during the email handling.
3. The From and To fields, as well as the email subject and email body, are unredacted if placeholders match the pre-defined patterns.
4. The From and To fields should contain redacted email addresses of the specific pattern, like email@profile_key006jkdsa00000oLpo.se.
5. The email’s subject and body can contain placeholders with redacted data that will be replaced with clear-text values upon unredaction like %profile_key=006jkdsa00000oLpo,price%.
6. Emails in the HTML and plain-text formats are supported.
7. Attachments within emails will be forwarded as is without any additional processing.
8. The customer’s SMTP server should be available in the target country.

Configuration of Email Gateway

Configuration of Email Gateway is a part of InCountry Border configuration. Below you can find a typical configuration of Email Gateway:

{
  "country": "IN",
  "environmentId": "a4a3221c-zzzz-yyyy-xxxx-86edae5cee0a",
  "oauth": {
    "clientId": "58e5ccf4-xxxx-xxxx-xxxx-abf4404ad99d",
    "clientSecret": "tXjnUvG5FX7qMFDWAUhzIWJEv2"
  },
  "vaultEncryptionKeyPath": "/v1/staging-portal-generation/export/encryption-key/in.a4a3221c-zzzz-yyyy-xxxx-86edae5cee0a",
  "email": {
    "client": {
      "host": "smtp.company.com",
      "port": 25,
      "username": "username123",
      "password": "mTLEY00tQHmy1kprS2HhAg"
    }
  }
}

Within the Email Gateway configuration you need to define the following parameters:

Parameter	Tolerated values	Description
country	IN or SA (or any other country ISO code)	A code of the country which is used to construct a PoP API request.
environmentId		A unique identifier of the environment for storing regulated data.
oauth		OAuth 2.0 credentials giving access to the environment on the InCountry platform in the target country. Here the clientId and clientSecret are specified.
email		A list of email connection parameters to the SMTP server in the target country.
host	smtp.company.com	Address of the SMTP server which emails are proxied to.
port	- 25 - 465 - 587 - 2525	SMTP port that is used for sending emails.
username	username123	Client ID that is used for SMTP authentication.
password	mTLEY00tQHmy1kprS2HhAg	Client Secret that is used for SMTP authentication.

Handling placeholders within emails

Email Gateway receives an email and parses it to the JSON object, as follows:

{
  "from": "john.doe@mail.com",
  "to": "jane.doe@mail.com",
  "subject": "Hello, %profile_key=006jkdsa00123oLpo,name%! Personal discount update notification",
  "text": "%token=test_token_123%Hello, %profile_key=006jkdsa00123oLpo,name%! \n ✔ Your current discount is %profile_key=006jkdsa00000oLpo,amount%! test"
}

The email body is placed within the text property that should have a pre-defined structure.

1. The beginning of an email body should include the authentication token for InCountry Border like %token=<BORDER_AUTH TOKEN>%. This token is provided by InCountry.
2. For each record, you need to specify a token that will be further used to replace this token with a clear-text value of the record. For example. the following expression is used %profile_key=006jkdsa00123oLpo,name%. In this case, Email Gateway through InCountry Border will look up a record with profile_key=006jkdsa00123oLpo and then use the name field from the payload. In such situation, Email Gateway pulls the record’s data from the InCountry platform and replaces placeholders with their actual values:

{
  "recordKey": <uid>,
  "body": JSON({"name": "John", "amount": 100}),
  "profile_key": "006jkdsa00123oLpo",
  ...
}

HTML Gateway

HTML Gateway is a part of InCountry Border. It resides between the customer’s monolithic web application that generates HTML pages and the user who works with this monolithic application. It captures the generated HTML pages outputted by the monolithic, identifies regulated data placeholders, and swaps them with their clear-text values pulled from the InCountry platform. The HTML structure with clear-text values is passed to the user’s browser for rendering. HTML Gateway is needed when your monolithic application resides in one country and users work with it from countries with stringent data regulations and requirements for handling personal data. In this case, HTML Gateway resides in the user’s country of origin and pulls regulated data from the InCountry platform within the same country, so regulated data does not touch your monolithiс web application backend, which keeps your company compliant with data regulations.

HTML structure handling workflow

Typically, a monolithic application generates an HTML page structure with all the regulated data and passes it to the end-user without considering their actual location. In some cases, this can violate the local or regional data regulations, as the monolithic application is hosted in one country, while end-users can use it from other countries having their own data regulations. The outputted HTML page structure containing regulated data values that we filled out can cause compliance issues that may finally result in fees or unexpected sanctions. All this may have a negative impact on the company brand and deliberately cause customer churn or loyalty decrease.

HTML Gateway integrates with your monolithic web application and complements the process of generating HTML page structure by replacing regulated data placeholders with their actual values. Your monolithic web application does not directly handle regulated data values but inserts special placeholders containing record identifiers and a field key. HTML Gateway intercepts this HTML page structure and identifies regulated value placeholders within the HTML page code. For each placeholder within this structure, HTML Gateway fetches the clear-text value from the InCountry platform located in the end user’s country of origin. Once clear-text values are inserted into the HTML code, it is passed to the end user’s browser that renders it into a visual form. Here you should consider that your monolithic web application can be hosted in any country, while HTML Gateway will run in the end user’s country, so regulated data stays within the country without touching servers of your monolithic web application.

note

HTML Gateway unredacts the HTML page structure returned within a response and redacts the content of the json/x-www-form-urlencoded type upon request.

HTML page requirements

HTML Gateway imposes the following requirements for your monolithiс web application:

1. HTML elements used for output of regulated data must have two data attributes that regulate the unredaction of their values;
2. regulated data fields should contain plain values without nested elements or rich-text data within them;
3. the application loads the minimal amount of external resources, especially graphics or elements that are passed along in the SVG format;
4. the application handles HTTP requests in the application/x-www-form-urlencoded or application/json content type;
5. the application may perform basic database queries if needed without complex validation or aggregation functions;
6. the application may perform basic AJAX requests with a JSON or HTML response (without nested AJAX data in HTML responses).

Supported HTML elements

You need to modify the outputted HTML page structure generated by your monolithic web application. The current version of HTML Gateway supports the following HTML elements:

1. text fields
2. pre-filled input fields

Below you can find an example of how to mark fields storing regulated data values for their correct processing by HTML Gateway.

• Text elements (e.g. div and span)

<body>
    <span>Hello, user!</span>
    ...
    <span data-inc-entity-id="id1" data-inc-field-name="name">ID1_NAME_TOKEN</span>
    ...
    <span data-inc-entity-id="id2" data-inc-field-name="name">ID2_NAME_TOKEN</span>
    ...
    <span data-inc-entity-id="id2" data-inc-field-name="email">ID2_EMAIL_TOKEN</span>
    ...
    <span data-inc-entity-id="id1" data-inc-field-name="email">ID1_EMAIL_TOKEN</span>
    ...
    <div>Other content</div>
</body>

• Pre-filled input fields:

<body>
    <form action="/add_user" method="POST">
      ...
      <input name="name" data-inc-entity-id="id1" data-inc-field-name="name" type="text" value="ID1_NAME_TOKEN">
      ...
      <input name="email" data-inc-entity-id="id1" data-inc-field-name="email" type="text" value="ID1_EMAIL_TOKEN">
      ...
    </form>
    ...
    <form action="/add_user" method="POST">
      ...
      <input name="name" data-inc-entity-id="id2" data-inc-field-name="name" type="text" value="ID2_NAME_TOKEN">
      ...
      <input name="email" data-inc-entity-id="id2" data-inc-field-name="email" type="text" value="ID2_EMAIL_TOKEN">
      ...
    </form>
</body>

In the HTML structure, the fields can be organized in a flat form or organized as nested fields, as follows:

<body>
    <span>Hello, user!</span>
    <div>
      <span data-inc-entity-id="id1" data-inc-field-name="name">ID1_NAME_TOKEN</span>
      <span data-inc-entity-id="id1" data-inc-field-name="email">ID1_EMAIL_TOKEN</span>
    </div>
    <div>
      <span data-inc-entity-id="id2" data-inc-field-name="name">ID2_NAME_TOKEN</span>
      <span data-inc-entity-id="id2" data-inc-field-name="email">ID2_EMAIL_TOKEN</span>
    </div>
    ...
    <div>Other content</div>
</body>

Alternatively, you can organize regulated data fields in other forms while preserving the following data attributes throughout the HTML page structure: *[data-inc-entity-id]*[data-inc-field-name]. HTML Gateway will use the required selectors to fetch such HTML elements from any location in the HTML structure.

note

The element with the data-inc-entity-id and data-inc-field-name data attributes cannot have nested elements and fields other than the redacted value.

Processing regulated data fields

HTML Gateway performs deserialization of HTML page code and fetches redacted data fields with the help of CSS selectors (*[data-inc-entity-id]*[data-inc-field-name]).

[
  {
    "id": "id1",
    "name": ID1_NAME_TOKEN,
    "email": ID1_EMAIL_TOKEN
  },
  {
    "id": "id2",
    "name": ID2_NAME_TOKEN,
    "email": ID2_EMAIL_TOKEN
  }
]

Having extracted the regulated data fields, HTML Gateway processes this structure and swaps redacted values with their clear-text values pulled from the InCountry platform. Once this is done, HTML Gateway passed the unredacted HTML structure to the end user’s browser for rendering.

Configuration and validation

Configuration of the unredaction rule for HTML Gateway looks as follows:

[
  {
    "path": "/add_user",
    "type": "HTML",
    "method": "POST",
    "collections": [
      {
        "name": "users",
        "entityIdPath": "$[*].id",
        "entityIdName": "id",
        "entityIdAttr": "data-inc-entity-id",
        "entityFieldAttr": "data-inc-field-name",
        "entityErrorCorrectionFieldPath": "$[*].email",
        "strategies": [
          {
            "path": "name"
          },
          {
            "path": "email",
            "isErrorCorrectionField": true
          }
        ]
      }
    ]
  }
]

Here:

• type is a flag that indicates that a request is sent to the monolithic web app that returns HTML output.
• entityIdAttr defines a data attribute for record ID.
• entityFieldAttr defines a field attribute.
• entityIdName is a flag that defines the name of the field in which this entity ID should be stored within a JSON object. Commonly it should correspond to entityIdPath, for example, if entityIdPath: "$[*].id" so entityIdName should be "id".

note

Note that if HTML error proxying is enabled, the statusCodeAttr and statusMessageAttr flags are still optional: they can be enabled or disabled for each endpoint.

By default, type is equal to REST: this corresponds to the endpoints when the payload is a JSON string and not HTML.

Error handling

Unlike RESTful APIs, monolithic apps may not return an error code (Error 40X) upon an error occurrence. Anyway, you can identify the occurred error by relying on the following response:

<body>
    <div>Content</div>
    <span data-inc-status-code=true>400</span>
    <span data-inc-status-message=true>Bad Request</span>
</body>

Handling errors requires the addition of flags to the JSON configuration that specify the ID values of containers storing a status code and an error message:

[
  {
    "path": "/add_person",
    "type": "HTML",
    "method": "POST",
    "statusCodeAttr": "data-inc-status-code",
    "statusMessageAttr": "data-inc-status-message",
    "collections": [
      {
        "name": "users",
        "entityIdPath": "$[*].id",
        "entityIdName": "id",
        "entityIdAttr": "data-inc-entity-id",
        "entityFieldAttr": "data-inc-field-name",
        "entityErrorCorrectionFieldPath": "$[*].name",
        "strategies": [
          {
            "path": "$.name"
          },
          {
            "path": "$.email",
            "isErrorCorrectionField": true
          }
        ]
      }
    ]
  }
]

The following attributes are used:

• statusCodeAttr is a data attribute name where a status code is stored.
• statusMessageAttr is a data attribute name where an error status message is stored.

What’s next

To integrate InCountry Border into your application, please follow these steps:

1. Collect the requests that should be handled by InCountry Border.
2. Elaborate the data model and regulated data that should undergo redaction/unredaction.
3. Register on the InCountry Portal.
4. Create a Border service.
5. Create a Border configuration.
6. Define the redaction and unredaction rules.
7. Save the Border configuration.
8. Update you application to route its requests through InCountry Border.
9. Verify data requests in your application.