External Custom Policy Handler

Deprecation notice: Support for this feature has been deprecated.

Private preview: This feature is only available to select accounts.

External custom policy handler overview

A custom policy handler can be written with code to enforce complex policy rules on your data sources beyond direct string matching provided through the Immuta user interface policy builder. The policy handler is a REST web service that the data owner defines to ensure that policies are being applied to data. This page outlines how to create, deploy, and secure a custom policy handler.

Requirements

• 2022.5+ LTS

• Immuta Self-Managed

Enable the external policy handler

1. Navigate to the Advanced Configuration section of the App Settings Page.

2. Enable external policy handlers with the following YAML:

   featureFlags:
       externalPolicyHandlers: true

Create a custom policy handler

1. Expose a REST web service that accepts a JSON object via an HTTP POST request.

   {
   "userAuthorizations":object,
   "dataVisibilities":array[object],
   "iamProfile":object,
   "groups":array[string]
   }

   The JSON posted to your policy handler endpoint has the following data to enable you to build the policy logic:

   • userAttributes: The key:value(s) attributes for that user from the Immuta internal IAM.

   • dataVisibilities: All the possible data visibilities from the data source the user is attempting to access.

   • iamProfile: A JSON representation of all the data for that user from the enterprise IDAM, if one is being used. This is how you know where the groups come from.

   • groups: The groups the user belongs to, either from the Immuta internal IDAM or the external enterprise IDAM, depending how the user logged in.

2. The policy handler processes all of the access decisions in bulk for that user against the data source in question. In other words, all the possible data visibilities will be passed to this endpoint for processing. The processing will consist of your handler applying the custom logic that you have implemented to determine which data visibilities a user has the right to see. If there are no errors it will return a 200 response with a JSON object:

   {
   "userCanSee":array[ids],
   "masked":array[object] (optional)
   }

   The response object will contain two keys:

   • userCanSee: A list of the visibility id(s) the user is authorized to see based on the dataVisibilities list in the request to the endpoint.

   • masked: If applicable, a list of masking objects that correspond to each masked column.

   Note: If there are any errors with the data that Immuta POSTed then Immuta will expect the policy handler to return an HTTP response with a status code in the 400 range, with an optional message in the body. If there are any errors in the policy handler that are not client related but are server related, then Immuta will expect an HTTP response with a status code in the 500 range, with an optional message in the body.

Change a policy handler

Changing policies is supported. When changes take effect, data availability will change accordingly per user.

Deploy a custom policy handler

Handlers are not hosted within the Immuta product, so it is up to the creator of the handler to deploy and maintain handlers.

Secure a custom policy handler

Use Two-Way SSL Configuration

The two-way SSL configuration is highly recommended as it is the most secure configuration for a custom policy handler endpoint.

When registering a policy store handler, the Data Owner is provided with these security option:

• The data owner may provide a CA bundle for their blob store handler in the event that an internally signed or self-signed certificate is being used by the policy store handler endpoint.

• The data owner can also provide a client certificate and key, which will be used by Immuta when contacting the blob store handler. This option will enable two-way SSL with client verification (if that method of operation is supported by the blob store handler endpoint).

Masking configurations

If your policy handler masks columns, your policy response should include a masked attribute that contains an array of objects that correspond to masked columns in your data source.

Standard masking

• type: The type of masking applied.

• metadata: Apply additional metadata to your masking configuration.

• name: The name of the column that you wish to mask.

"masked": [
    {
        "type": "Consistent Value",
        "metadata": {"constant": null},
        "name": "col_name_1"
    }
]

Note: The constant value represents the value that will be used as a replacement for your specified column. If no constant is specified in the policy handler response metadata, a hash of the column value will be used.

Regular expression masking

If a policy uses regular expression replacement, the policy handler will send this masking configuration in the response:

"masked": [
    {
        "name": "col_name",
        "type": "Regular Expression",
        "metadata": {
            "regex": "your regex",
            "replacement": "your replacement",
            "global": false,
            "caseInsensitive": false
        }
    }
]

Rounding

If a policy rounds the value in col_name to the nearest 10, the policy handler will send this masking configuration in the response:

"masked": [
    {
        "name": "col_name",
        "type": "Grouping",
        "metadata": {
            "bucketSize": 10
        }
    }
]