Managing Border endpoints

Table of сontents

• Creating Border endpoints
• Managing redaction rules
• Managing unredaction rules
  • Configuring value masking

You can manage web service endpoints that are handled by Border for redacting and unredacting regulated data. An endpoint represents a collection of rules describing how a request or response looks like and which fields must be redacted or unredacted and which fields must be passed as-is.

Border supports two data flows when

1. it redacts ingress data: converts input values (clear-text values) into tokenized values and replaces them within request payloads.
2. it unredacts egress data: swaps tokenized values with their original clear-text values within response bodies.

Border handles regulated data based on redaction and unredaction rules that describe the structure of request payloads and response bodies and regulate fields that contain sensitive values. Border intercepts web requests with their payloads or responses and acts accordingly to the configured redaction or unredaction rules. The intercepted regulated values are either redacted and saved to the InCountry platform (in redaction rules) or queried from the InCountry platform and swapped in responses (in unredaction rules). For example, for the POST, PUT, and UPDATE methods, you can apply a redaction rule, for the GET method you can apply an unredaction rule.

Depending on the value format, you need to apply an appropriate redaction algorithm to regulated values processed by Border. This greatly depends on your system architecture and handled values, as well as validation rules.

To preserve the search capabilities, you need to explicitly indicate what values in the payload should be treated as searchable. In this case, regulated values will be additionally saved to searchable fields where the InCountry platform can easily look up records against several searchable fields.

Redaction and unredaction rules deal with collections, so-called objects whose data undergoes redaction or unredaction. Border uses collections to produce unique hash values and identify the applicable redaction or unredaction strategies in the data communication pipeline.

Creating Border endpoints

1. Open the environment where you want to create a Border endpoint.
2. In the navigation sidebar, select the the country which a Web Services service is attributed to.
3. On the list with services, locate the service of the Web Services type.
4. Click the Manage endpoints icon. Portal opens the list of Border endpoints.
5. Click Add Endpoint.
6. It the Properties section, specify the following information:
   • Name - enter the name of the Border endpoint.
   • Existing REST URL - specify the URL of the application that handles regulated data.
   • Entity IDs are unique - check the box to allow Border to use the entity id as a profile key value directly without applying a key generation algorithm based on collection name and entity id. Use this option only when the entity id within the payload is a completely unique value that cannot be duplicated.
   • Data masking - check the box to enable the data masking for unredaction rules. By default, Border automatically unredacts data in responses, with this option activated Border will return masked values for users requests data outside the country of origin. So original clear-text values will not be reveled if requested outside the country of origin. When configuring unredaction rules, you will be able to define the value masking options.
   • Enable CORS- check the box to override CORS settings. Expand the CORS Settings section and specify the required Access-Control header. This header will be applied to all requests handled through Border.
7. Click Add redaction rule. Specify redaction rules that will regulate how Border redacts regulated data passing through the endpoint. For the details on how to configure a redaction rule, please see the Managing redaction rules section. You can add multiple rules to redact data passing through different endpoints.
8. Click Add unredaction rule. Specify unredaction rules that will regulate how Border unredacts regulated data passing through the endpoint. For the details on how to configure an unredaction rule, please see the Managing unredaction rules section. You can add multiple rules to redact data passing through different endpoints.
9. When complete, click Create Endpoint.
10. On the Endpoint review and confirmation page, review the Border endpoints you have specified.
11. Enter the verification code and click Confirm.

info

Once you have saved the Border endpoint, InCountry Portal will output information about the Border endpoint through which you need to pass requests within your web application.
You need to locate the Target endpoint value, which will look like
https://se-proxy-mt-01.incountry.io/x-inc-55898eff-361a-XXXX-XXXX-4b755d0afe8b
In the source code of your web application, you need to replace the web application URL with this target endpoint for all endpoints that you configured in the Border endpoint.
For example, you have the POST https://socialposts.com/api/authors/ endpoint, you need to make it look like https://se-proxy-mt-01.incountry.io/x-inc-55898eff-361a-XXXX-XXXX-4b755d0afe8b/api/authors/.

Warning

Please ensure that you use the correct country for handling regulated data. The ISO country code is specified in the target endpoint address. If the incorrect country is specified, Border will not be able to unredact regulated data when querying from the InCountry Vault where these records do not exist. The redaction of regulated data may result in the situation when you save regulated country in the country different from the country of origin.

Managing redaction rules

1. Click Add redaction rule.
2. In the Redaction rule initialization form, specify the following information:
   1. HTTP request method - select the request type, as follows:
      1. GET - used to retrieve data.
      2. POST - used to submit/create new data.
      3. PUT - used to submit/create new data.
      4. PATCH - used to update data.
      5. DELETE - used to delete data.
3. Path relative to Existing REST URL - enter the URI path to the endpoint and append the regular expression if needed to handle cases when the slash is either present or not in the request. You can enter the Request JSON and Response JSON examples.
4. Request JSON - enter the request payload that you want to redact when passing through Border to the application backend.
5. Response JSON - enter the response body that the application backend returns to the response.
6. Click Create rule.
7. Click the Advanced settings icon. Here you can select the appropriate operating mode for this endpoint, as follows:
   1. Processing & Storage - ingress regulated data is saved to the InCountry platform and then it is redacted and passed to the endpoint.
   2. Processing - ingress regulated data is redacted and passed to the endpoint without its saving on the InCountry platform.
8. Click Redact Field.
9. At the Redaction Rule Step 1: Fields redaction step, you need to specify all the fields from the request payload that contain regulated values that you want to redact. For each field you want to redact, specify the following information:
   • Path - specify the JSON path to the field carrying a regulated value that should be redacted. InCountry Portal also automatically parses the request payload, so you can select the necessary field from the dropdown box.
   • Algorithm - select the appropriate algorithm to redact the regulated value from the available options. Please use the algorithm that matches the format of the original value.
     • alphaNumeric - applies an alpha-numeric hash to a string containing letters and numbers. The produced alphanumeric string varies during every redaction.
     • alphaNumericLowerCase - applies a lower-case alphanumeric hash to a string containing letters and numbers.
     • alphaPrepended - applies a prefix comprised of a single letter.
     • email - applies an email-pattern string, e.g. dsf34fsdf@redactedemail.com. The produced email-pattern string varies during every redaction.
     • plain - forwards the original value.
     • one - applies '1' ( a single digit).
     • zero - applies '0' (a single digit).
     • numeric - applies a random numeric value of the length equal to the original value.
     • dateISO - applies a random date in the ISO format.
     • defaultDateISO - applies a random date in the default ISO format (1970-01-01T00:00:00Z).
     • fixed - applies any hardcoded value. If you select this option, in the Value box, enter the value that should be applied by default.
     • emailPersistent - applies an email-pattern string that remains the same for the same email address during every redaction.
     • alphaNumericPersistent - applies an alpha-numeric hash that remains the same for the same alphanumeric string during every redaction.
   • Length - enter the length for the redacted value if your system performs some validation of value length, otherwise leave the default length.
   • Searchable Key - select the record’s key or key-alias that will be used to store a searchable value of the record on the InCountry platform.
10. At the Redaction Rule Step 2: Entity Identification step, specify the following information:
    • Prefix to add to non-unique ID - enter a meaningful and unique name to the collection that will allow endpoint to correctly differentiate between entities even when they have the same identifier.
    • Path to non-unique ID - ensure that the regular expression matches the path of your request.
    • Randomly-tokenized field - enter the path to the record identifier that is returned within the response to this request.
11. Click Add Unreduction Rule. While defining the configuration of Border, you can set up unredaction rules that regulate how Border unredacts outgress regulated data passing through the endpoint. You can add multiple rules to unredact data passing through different endpoints.
12. Configure the unredaction rule, as follows:
    • Method - select the request type, as follows:
      1. GET - used to retrieve data.
      2. POST - used to submit/create new data.
      3. PUT - used to submit/create new data.
      4. PATCH - used to update data.
      5. DELETE - used to delete data.
    • Path - enter the URI path to the endpoint and append the regular expression if needed to handle cases when the slash is either present or not in the request.
13. When complete, save the Border endpoint.

Managing unredaction rules

1. Click Add unredaction rule.
2. At the At the Unredaction Rule Step 1: Entity identification step, specify the following information:
   • Entity Prefix - select the prefix (entity name) which the current unredaction rule is attributed to. Border will use the prefix to identify records pertaining to a specific entity while unredacting their hashed values. When the response combines multiple entities, you need to properly reference them in the configuration. In this case, you may need to register another entity by clicking Add another entity.
   • Path to non-unique ID - enter the JSON path to the field carrying a non-unique record identifer.
   • Randomly-tokenized field - enter the JSON path to field that you redact with an undeterministic tokenization algorithm (email, alphaNumeric, or alphaNumericLowerCase).
3. Click Unredact field.
4. At the step Unredaction Rule Step 2: Fields unredaction step, specify the following information for each field you want to unredact:
   • Path - enter the JSON path to the field carrying a regulated value that must be unredacted.
   • Original Path - select the JSON path to the original field carrying a regulated value from the redaction rule.
5. When complete, save the Border endpoint.

When your Border endpoint deals with unique entity Ids The Entity ID’s are unique option is enabled), then you need to specify the path to unique ID and select the randomly-tokenized field.

When you enable the data masking, while configuring unredaction rules, you will be able to define how to mask regulated values when returning them to the application backend residing in the country different from the country of origin. To users coming from the country of origin, Border will return the original clear-text value as-is.

Configuring value masking

By default, Web Services Border automatically unredacts the data in the response body. You can forbid this for users requesting regulated data outside its country of origin. Regulated values will be masked except when requested from the country of origin. Once enabled, you can choose the appropriate masking algorithm within the settings of the unredaction rule.

1. Click Unredact field.
2. For each field you want to mask, specify the following information:
   1. Algorithm - select the masking algorithm that you want to apply. You can select among the following ones:
      1. default - Border will use the initial redaction algorithm used for this field in the configured redaction algorithm.
      2. outside country fixed - Border will apply the fixed value you enter in the Value field, for example, John Doe can be replaced with REDACTED.
      3. outside country masking - Border will apply the masking value to original clear text value, for example, John Doe can be replaced with J**** D****. For this algorithm, you can specify additional settings, as follows:
   2. Path and Original path - specify the JSON paths as for a generic unredaction rule. See the instructions above.
   3. Type - select the value type (alphanumeric or email).
      1. Masking after N characters - specify the number of characters that will be preserved as is at the string beggining. All the characters then will be masked with the masking character.
      2. Masking character - enter the character that will mask values from the original clear-text value, for example, * (asterisk), @ (ampersand) or X.
      3. Masking length - specify the number of masking characters applied to the string.
3. When complete, save the Border endpoint.