Write an Advanced Data Policy

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.

Example: Row Restriction by User Entitlements Policy

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: change how data appears to the querying user.
• User/Data Functions: examine information about the model's user or visibility data.

Policy Response Functions

UserCanSee(rowLevelModel)

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

Parameters:

MaskedFields(maskingModel, fields)

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

Parameters:

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()

What's Next

Now that you've written a data policy, you can choose to continue to the next page or to this tutorial: Manage Data Sources.