# Policy Handler Objects

This page describes how to update policies using the Policy Handler API.

## Create policy handler

| Method | Path              | Successful Status Code |
| ------ | ----------------- | ---------------------- |
| POST   | `/policy/handler` | 200                    |

### Request parameters

The create policy handler endpoint must be a [policy handler object](#policy-handler-object).

## Update policy handler

| Method | Path              | Successful Status Code |
| ------ | ----------------- | ---------------------- |
| PUT    | `/policy/handler` | 200                    |

### Request parameters

The update policy handler endpoint must be a [policy handler object](#policy-handler-object).

## Policy handler object

* `dataSourceId` (integer): ID of the data source the policy will be applied to.
  * **Example:** `1`
* `jsonRules` (array\[object]): Array of JSON rules objects.
  * **Example:** See [defining policy rules](#defining-policy-rules)

## Defining policy rules

The `jsonRules` array contains rules objects. The following types of policy rules are supported:

* [Prerequisite](#prerequisite-policy-rule-type)
* [Visibility](#visibility-policy-rule-type)
* [Masking](#masking-policy-rule-type)
* [Minimization](#minimization-rule-type)
* [Time-based](#time-based-rule-type)

Not all combination of policy rules are valid. The examples below are supported policy rule combinations:

* Prerequisite, Visibility, Masking
* Prerequisite, Masking, Minimization

### Prerequisite policy rule type

Prerequisite policies are used to limit usage to one or more purposes.

* `type` (*string*): Policy rule type. Must be `prerequisite` for prerequisite policy rules.
  * **Example:** `"prerequisite"`
* `operator` (*string*): Operator to be applied on conditions. Possible values: *and*, *or*.
  * **Example:** `"or"`
* `conditions` (*array\[object]*): Conditions to be applied for the rule. Multiple values will be evaluated according to the *operator*.
  * **Example:** See [purpose condition object](#purpose-policy-condition)

**Example**:

In this example, users will only have access to data from this data source when they are acting under the `purpose` named `Purpose Name`.

```json
{
    "type": "prerequisite",
    "operator": "or",
    "conditions": [{
        "type": "purposes",
        "value": "Purpose Name"
    }]
}
```

### Visibility policy rule type

Visibility policies are used to enforce row-level security.

* `type` (*string*): Policy rule type. Must be `visibility` for row-level security policy rules.
  * **Example:** `"visibility"`
* `operator` (*string*): Operator to be applied on conditions. Possible values: *and*, *or*.
  * **Example:** `"or"`
* `conditions` (*array\[object]*): Conditions to be applied for the rule. Multiple values will be evaluated according to the *operator*.
  * **Example:** See [policy conditions](#policy-conditions)

*Note: When adding conditions to a visibility policy rule, the `field` is required, and the condition `value` should be left empty. For example, for a group policy condition, the group name is not specified.*

```json
{
    "type": "groups",
    "field": "organization",
    "group": {
        "iam": "active_directory"
    }
}
```

The user must possess the group, attribute, or purpose that matches the value stored in the `field`.

**Example**:

In this example, users will only see rows when they have an `authorization` that matches the value in the field `department` **and** they belong to a `group` that matches the value in the field `organization`.

```json
{
    "type": "visibility",
    "operator": "and",
    "conditions": [{
        "type": "authorizations",
        "field": "department",
        "authorization": {
            "auth": "accesses",
            "iam": "active_directory"
        }
    }, {
        "type": "groups",
        "field": "organization",
        "group": {
            "iam": "active_directory"
        }
    }]
}
```

### Masking policy rule type

Masking policy rules will mask the value in one or more columns.

* `type` (*string*): Policy rule type. Must be `masking` for masking policy rules.
  * **Example:** `"masking"`
* `fields` (*array\[string]*): Fields that will be masked when a user does not fulfill policy conditions.
  * **Example:** `["email", "location"]`
* `operator` (*string*): Operator to be applied on conditions. Possible values: *and*, *or*.
  * **Example:** `"or"`
* `conditions` (*array\[object]*): Conditions to be applied for the rule. Multiple values will be evaluated according to the *operator*.
  * **Example:** See [policy conditions](#policy-conditions)

*Note: When adding conditions to a masking policy rule, the `field` will be left blank, and the condition `value` should be populated.*

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    }
```

When using a masking rule, there is an additional field that needs to be sent in the [update data source request](#update-policy-handler) in the `policyHandler.maskingConfiguration` array field.

* `name` (*string*): Name of the field being masked.
  * **Example:** `"social"`
* `type` (*string*): Type of masking to apply. Supported values are `"Consistent Value"`, `"Grouping"`, `"Regular Expression"`
  * **Example:** `"Consistent Value"`
* `metadata` (*object*): Extra metadata used when masking the value.
  * **Example:** See [masking configuration metadata](#masking-configuration-metadata)

#### Masking configuration metadata

**Consistent value**

* `constant` (*string*|*null*): Constant value to mask to. If this field is not defined, the value will be hashed.
  * **Example:** `"REDACTED"`

**Regular expression**

* `regex` (*string*): Regex to match against when masking columns.
  * **Example:** `"[0-9]{3}-[0-9]{2}"`
* `replacement` (*string*): String used to replace the matched regex.
  * **Example:** `"xxx-xx"`

**Grouping**

* `bucketSize` (*integer*): For number fields. Size of buckets to round numbers to.
  * **Example:** `100`
* `timePrecision` (*string*): For time fields. Time precision to round to. Possible values: `"MIN"`, `"HOUR"`, `"DAY"`, `"WEEK"`, `"MONTH"`, `"YEAR"`
  * **Example:** `"HOUR"`

**Example policy handler update with masking configuration metadata**:

```json
{
    "policyHandler": {
        "maskingConfiguration": [{
            "type": "Consistent Value",
            "name": "age",
            "metadata": {
                "constant": "REDACTED"
            }
        }]
    }
}
```

**Example**:

In this example, the fields `email` and `location` will be masked unless the user belongs to the group `admins`.

```json
{
    "type":"masking",
    "fields": ["email", "location"],
    "operator":"or",
    "conditions":[{
        "type":"groups",
        "group":{
            "name":"admins",
            "iam":"active_directory"
        }
    }]
}
```

### Minimization rule type

Minimization policy rules will show a limited percentage of the data, based on a high cardinality column, for everyone unless the user fulfills the policy conditions.

* `type` (*string*): Policy rule type. Must be `additional` for minimization policy rules.
  * **Example:** `"additional"`
* `name` (*string*): Name of *additional* policy. Must be `minimization` for minimization policy rules.
  * **Example:** `"minimization"`
* `operator` (*string*): Operator to be applied on conditions. Possible values: *and*, *or*.
  * **Example:** `"or"`
* `conditions` (*array\[object]*): Conditions to be applied for the rule. Multiple values will be evaluated according to the *operator*.
  * **Example:** See [policy conditions](#policy-conditions)

*Note: When adding conditions to a minimization policy rule the `field` will be left blank.*

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    }
```

When using a minimization rule, there is an additional field that needs to be sent in the [update data source request](#update-policy-handler) in the `policyHandler.additionalFilters.minimization` field.

* `percent` (*integer*): Percentage of the data to show to the users. This percentage will be based off of unique values in the `hashPhrase` column.
  * **Example:** `50`
* `hashPhrase` (*string*): Column to base the percentage off of. This should be a high cardinality column in the data source.
  * **Example:** `"name"`

**Example policy handler rule**:

In this example, 50 percent of the data, based on the `name` field, will be visible to users unless they fulfill the policy conditions.

```json
{
    "type": "additional",
    "name": "minimization",
    "operator": "or",
    "conditions": {
        "type":"groups",
        "group":{
            "name":"admins",
            "iam":"active_directory"
        }
    }
}
```

**Example data source update (partial)**:

```json
{
    "policyHandler": {
        "additionalFilters": {
            "minimization": {
                "percent": 50,
                "hashPhrase": "name"
            }
        }
    }
}
```

### Time-based rule type

Time-based rules will make a limited portion of the data available based on event time. The data source must contain an *event time* column in order for this policy type to be valid. For instance, users who do not fulfill the policy conditions will only see data from within the defined time window.

* `type` (*string*): Policy rule type. Must be `additional` for minimization policy rules.
  * **Example:** `"additional"`
* `name` (*string*): Name of *additional* policy. Must be `time` for time based policy rules.
  * **Example:** `"time"`
* `operator` (*string*): Operator to be applied on conditions. Possible values: *and*, *or*.
  * **Example:** `"or"`
* `conditions` (*array\[object]*): Conditions to be applied for the rule. Multiple values will be evaluated according to the *operator*.
  * **Example:** See [policy conditions](#policy-conditions)

*Note: When adding conditions to a time based policy rule the `field` will be left blank.*

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    }
```

When using a time based rule, there is an additional field that needs to be sent in the [update data source request](#update-policy-handler) in the `policyHandler.additionalFilters` field.

* `time` (*integer*): Age in seconds of the oldest data a user will be allowed to see. This counts backward from the present.
  * **Example:** `14400`

**Example policy handler rule**:

In this example, only data from the last 4 hours will be visible to users unless they fulfill the policy conditions.

```json
{
    "type": "additional",
    "name": "time",
    "operator": "or",
    "conditions": {
        "type":"groups",
        "group":{
            "name":"admins",
            "iam":"active_directory"
        }
    }
}
```

**Example data source update (partial)**:

```json
{
    "policyHandler": {
        "additionalFilters": {
            "time": 14400
        }
    }
}
```

## Policy conditions

There are three types of policy conditions:

1. [Groups](#group-policy-condition)
2. [Attributes](#attribute-policy-condition)
3. [Purposes](#purpose-policy-condition)

### Group policy condition

The group policy condition restricts access to the condition when a user is a member of a group.

* `type` (*string*): Type of policy condition. Must be `"groups"` for the group policy condition.
  * **Example:** `"groups"`
* `group` (*object*): Object describing group user must belong to in order to satisfy the policy condition.
  * **Example:** See [group object](#group-object)
* `field` (*string*): Data field to match group name against when checking policy.
  * **Example:** `"department"`

**Example**:

```json
{
    "type": "groups",
    "group": {
        "name": "users",
        "iam": "active_directory"
    },
    "field": "department"
}
```

#### Group object

* `name` (*string*): Name of group user must belong to in order to satisfy the policy condition.
  * **Example:** `"users"`
* `iam` (*string*): ID of the IAM containing the group.
  * **Example:** `"active_directory"`

### Attribute policy condition

The attribute policy condition restricts access to the condition when a user possesses an attribute.

* `type` (*string*): Type of policy condition. Must be `"authorizations"` for the attribute policy condition.
  * **Example:** `"authorizations"`
* `authorization` (*object*): Object describing attribute user must possess in order to satisfy the policy condition.
  * **Example:** See [group object](#group-object)
* `field` (*string*): Data field to match attribute value against when checking policy.
  * **Example:** `"department"`

**Example**:

```json
{
    "type": "authorizations",
    "authorization": {
        "auth": "accesses",
        "value": "PII",
        "iam": "active_directory"
    },
    "field": "department"
}
```

### Attribute object

* `auth` (*string*): Name of attribute to check for attribute value.
  * **Example:** `"accesses"`
* `value` (*string*): Value of attribute user must possess in order to satisfy the policy condition.
  * **Example:** `"PII"`
* `iam` (*string*): ID of the IAM user must receive the attribute from.
  * **Example:** `"active_directory"`

### Purpose policy condition

The purpose policy condition restricts access to the condition when a user is acting under a purpose.

* `type` (*string*): Type of policy condition. Must be `"purposes"` for the purpose policy condition.
  * **Example:** `"purpopses"`
* `value` (*string*): Purpose name user must be acting under in order to satisfy the policy condition.
  * **Example:** `"Purpose"`
* `field` (*string*): Data field to match purpose name against when checking policy.
  * **Example:** `"department"`

**Example**:

```json
{
    "type": "purposes",
    "value": "Purpose",
    "field": "department"
}
```