Skip to main content

Policy Builder

The Policy Builder aims to provide a guided approach to policy authoring for occasional policy authors or users with less technical background. It provides the full power and flexibility of Rego with a point-and-click editor. By using the Policy Builder, you can make existing policies more readable for a broader spectrum of users, write policies without having to remember all the details of Rego, and also understand the policies being enforced.

Features​

The Policy Builder provides the following features:

  • Rule types: The Policy Builder helps you choose what kind of rule you want to write and provides an english description of what decision that rule makes.

  • Condition types: The Policy Builder also helps you choose what kind of condition you want to write. It gives you the flexibility to write the core expressions you want while helping you to use the less common ones.

  • Intellisense: The Policy Builder helps you write long dotted expressions like data.foo.bar.baz by providing a list of potential fields at each level of the expression. Fill in your data, and the Policy Builder helps you navigate it. Intellisense also auto-completes your local variables, constants, rules, functions, and Rego built-in functions.

  • Readability: The Policy Builder presents Rego in a form that is easier to read for non-experts. It interleaves english phrases so that someone new to policy authoring can start from existing policies and learn quickly how to adapt them, and it provides a more readable format for non-policy-authors.

Using Policy Builder​

Conceptually, the Policy Builder works by helping you to add or delete rules, and then for each rule it guides you through the structure of the conditions in the body of those rules. Use the Policy Builder to define imports and create, update, and delete complete rule definitions.

To try out the Policy Builder, create a new DAS system and a policy:

  1. Create a new System in your Styra DAS SaaS environment.

  2. Navigate to your SYSTEM >> policy >> rules.rego.

  3. Click the Builder icon to write policies without having to remember all the details of Rego.

As you begin to use the Policy Builder, there are a few things to keep in mind:

  • You edit one rule and one condition within that rule at a time. You use Save to store your edits and Cancel to discard your edits.

  • You use the (+) button to add and the (-) button to delete.

  • When you add comments in the Code Editor, those comments will not appear in the Policy Builder.

When you start using the Policy Builder, there are several top-level statements, described by each of the following subsections.

Imports​

An import is a way to alias a path such as data.foo.bar.baz to a shorter name.

To add an import, click the Add import (+) button.

For example, enter data.dataset and then click the Save button. When you write rules, the variable dataset will be shorthand for data.dataset.

Constants​

A constant is a simple rule that assigns a variable to a value without any conditions.

To add constants, click the Add constant (+) button.

For example, enter mw_users is {"alice": {"type": "administrator"}, "bob": {"type": "free-subscriber"}, "charlie": {"type": "paid-subscriber"}}.

Rules​

A rule is a statement assigning the contents of a variable to one or more values under certain conditions. Some rules assign a variable to a single value; others assign one or more values to a set; others assign one or more keys to values in an object.

To add a rule, click the Add rule (+) button. For example, enter allow is true (which is the most common rule definition). There are several types of rules in Rego. You choose the one you want from the Form: drop-down list and then click Next after filling out the head of that rule.

  • Complete: Rule that assigns a variable to a single value.

  • Partial set: Rule that adds values to a set.

  • Partial object: Rule that adds key-value pairs to an object.

Once you have chosen the type of rule to write, you can add assignments, conditions, and expressions to the body of that rule. For example, enter the conditions in the rule body to be input.method=="GET" and input.parsed_path == []. OPA evaluates these conditions and if they are true, the rule is assigned the values you specified in its definition.

In the first condition, you have another Form: drop-down list, to select which type of condition you want to write:

  • Expression: Evaluate a combination of references, variables, operators, or function calls to produce a value.

  • Negated expression: Assert that the result of evaluating a given expression should not exist.

  • Local variables: Declare a list of variables local to the enclosing rule, overriding any global references that share the same name. Declaring a local variable (via some under the hood) suffices to cause iteration over the possible values for that variable.

  • Mock data: Override values in the data or input documents. Mock data is useful for writing test rules in your system >> tests >> tests.rego. The Validate action in the policy editor runs your tests and shows you the results.

The following additional operations are available in the Add rule row:

  • To delete a rule, click the Delete rule button.

  • To add more conditions, click the Add condition button.

  • To add OR condition, click the Add or/else button. (Technically, this will produce a separate Rego rule underneath, but it will be shown in the Policy Builder as an OR).

  • Define the default rule in the Otherwise field. This is what the rule evaluates to when its conditions are not met. For example, set the default allow rule to allow is false. Then click the Save button.

Functions​

A function in Rego is like a function in a traditional programming language: given some inputs it returns an output.

To add a function, click the Add function (+) button.

For example, enter user_owns_pet(petid) and click the Next button to apply the conditions. The conditions in a function work the same as the conditions in a Rule, which are described above.

Viewing Policies with Policy Builder​

Policy Builder makes it easier to view the logic of policies. To view policies with Policy Builder, click the Builder button.

For example, MusicWorld is a new music subscription service with an HTTP API service supporting the following calls:

  • GET /songs.

  • GET /songs/<songID>/details.

  • POST /songs/<songID>/details.

  • GET /songs/<songID>/playSample.

  • GET /songs/<songID>/play.

The MusicWorld policy enforces:

  • Anyone in the world can view all the songs or a song’s details.

  • Anyone can play a sample of a song.

  • Only MusicWorld paid subscribers can play any song.

  • Only MusicWorld paid and free subscribers can play a free song.

  • Only a MusicWorld administrator can create a song with its details.

Fragment of the Policy Builder based on the above example:

Figure 1 - Policy BuilderFigure 1 - Policy Builder

View the Rego Code​

To see the underlying Rego code that is being generated and managed by the Policy Builder, click the <> Code button. You can edit the code and see the results appear in the Policy Builder. If you have followed along with the examples above, then the following Rego is displayed in the Code Editor.

default allow = false
allow {
    input.method == "GET"
    input.path == ["songs"]
}
allow {
    input.method == "GET"
    input.path = ["songs", songID, "details"]
}

default is_subscriber = false
is_subscriber {
    user_type := mw_users[input.user].type
    endswith(user_type, "subscriber")
}

For more information on how to write rules, see the OPA Rules page.