Skip to content

You are viewing documentation for Immuta version 2.8.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

Advanced Data Policy Builder

Audience: Data Owners

Content Summary: The Advanced Data Policy Builder allows you to author custom Data Policies with the same DSL used by Immuta under the covers. Both Masking (by making null) and Row Restriction By User Entitlements policies are supported. This page details the rules that can be entered in the Advanced Data Policy Builder. For instructions on using the Advanced Subscription Policy Builder, navigate to the Subscription Policy Advanced Rules DSL section of the Local Policy Builder Tutorial.

Note: The policies described on this page are intended for advanced users and should only be used when policy logic is needed beyond what is available with existing Immuta features. Please contact an Immuta professional for assistance authoring these policies.

Warning

Immuta-defined functions or object fields that are not explicitly documented here are NOT intended for direct customer use and may be modified or removed without warning.

Example: Row Restriction by User Entitlements Policy

Advanced DSL Builder

This image illustrates the following policy:

rule myExample {
    when {
        m : RowLevelModel User(m).From("bim").HasGroup(Data(m).Visibility("country").Value());
    } then {
        UserCanSee(m)
    }
}

Essentially, this rule checks whether or not the querying user — defined in RowLevelModel m — is a member of a group from the bim IAM whose name matches the value in column country for the visibility defined in m. If true, the UserCanSee function is invoked on this model, which will ultimately permit this user to see all rows/objects matching the model's visibility.

Models

A model is an object class whose instances are used in the evaluation of DSL rules. In the example above, the snippet "when { m : RowLevelModel ..." denotes that this rule will only be applied to RowLevelModel models.

In your custom rules, you can define your own models or you can use either of the pre-defined Immuta models: MaskingModel and RowLevelModel. However, only the Immuta models will already be instantiated and have access to information about the querying user (i.e., their groups, attributes, purposes, and profile) and visibility data. Both models have a user property with the following structure:

{
    userAttributes: {
        [attribute]: string[]  // list of values for each attribute
    },
    authsIam: string,  // IAM for userAttributes
    userGroups: string[],
    groupsIam: string,
    userProfile: {
        name: string,
        email: string,
        phone: string,
        about: string,
        location: string,
        organization: string,
        position: string,
        hdfsUser: string,
        id: integer
    },
    profileIam: string,
    purposes: string[],
}

Note: Users should not directly modify any of these object properties.

Functions

All pure JavaScript functions are available for use in Advanced DSL Policies, including a number of helper functions and shortcuts defined by Nools. (See the Constraints section.) Custom functions can also be defined using traditional JavaScript syntax.

There are two types of pre-defined Immuta functions available:

Policy Response Functions

UserCanSee(rowLevelModel)

This function returns a user's query with rows that match the visibility defined in the specified model.

Parameters:

# Parameter Type Required Description
1 model RowLevelModel Required A model whose user should see all rows matching the model's data visibility

MaskedFields(maskingModel, fields)

This function returns a user's query with the specified fields/columns masked (by making null).

Parameters:

# Parameter Type Required Description
1 model MaskingModel Required A model that masks all fields in fields
2 fields string[] Required A list of field/column names to mask

User/Data Functions

User(model)

This function pulls a user's groups, attributes, purposes, and profile. Example usages are demonstrated below:

 User(m).Attribute(attribute).Contains(valueOrArray)
 User(m).HasGroup(groupNameOrArray)
 User(m).HasPurpose(purposeOrArray)
 User(m).Profile()
 ```

 Furthermore, you can also chain `From(iam)` to require that the user's IAM match the specified IAM:

 ```javascript
 User(m).From(iam).Attribute(attribute).Contains(valueOrArray)
 User(m).From(iam).HasGroup(groupNameOrArray)
 User(m).From(iam).Profile() // Returns {} if no IAM match

Data(rowLevelModel)

This function pulls a model's visibility data. Example usages are demonstrated below:

Data(m).Visibility(field).Contains(valueOrArray)
Data(m).Visibility(field).Value()