Policy Editor

Policy Editor is a tool intended to simplify the creation and maintenance of authorization policies.

Policy Editor is accessed from the menu bar at the top of the Axiomatics Services Manager under Policy Management. This menu option provides access to the Policy Package Library as well as the Policy Editor.

The Policy Editor is divided into two sections:

• Workspace

  The Workspace occupies the left side of the frame and you can open and close it by clicking on the arrow at the top of the frame. The Workspace acts as your private work area for your policy packages. Use it to open, close, create, import, export, duplicate, or delete Policy Packages.

• Policy Design Board

  The Policy Design Board to the right of the Workspace is the large open space where policy trees can be designed and arranged. On the Design Board you place nodes representing Policy Sets, Policies, References and Rules to take full advantage of XACML in an easy to use graphical interface.

  With the Workspace to the left where current Policy Packages are kept, and the Design Board to the right, you have everything necessary to model and manage policies at whatever level of complexity and detail is required.

Workspace

The Workspace is the left pane of the Policy Editor and lists all policy packages that you are currently working on. Contrary to the Policy Package Library, which looks the same to all users, the Workspace represents your private work area. When you open a policy from the Policy Package Library, it is automatically placed on your private Workspace.

The top of the Workspace is occupied by a row of action icons:

• Open: Click on this icon to open a separate window listing Policy Packages from the Library with information on previous edits, action icons like those in the Workspace tool bar, and action buttons that permit the user to open, export, duplicate, or delete a package. If you open a package it is placed in the Policy Package List on your Workspace.

• New: Click on this icon to create a new Policy Package in the list of Policy Packages below the action icons in the Workspace. The package becomes available to others in the general Policy Package Library.

• Import: Click this icon to select a Policy Package to be imported into the Policy Editor. A standard file dialog is opened.

• Export: Only when a user selects a policy package (top level) node does the Export policy package button become enabled. Click the enabled button to download a Policy Package as a .zip file into your default download folder. All policy package content, including all policies, will be exported in the .zip file.

• Duplicate: Click this icon to make a copy of a selected Policy Package and place it in the Policy Package List. It also becomes available to others in the Policy Package Library.

Additionally, an Export policy tree button is available on each table tree node. Pressing the button exports only the selected tree in a .zip file.

Policy Package List

When a new Policy Package is created, it is added to a list of open Policy Packages. Users can name the package and expand the entry to show a line containing the top-level policy. When the top-level policy is selected, a default set of nodes appears on the Policy Design Board. The set consists of a Policy Set, Policy, and Rule node.

You can create additional Policy Trees by clicking the Add Policy Tree button. This also creates a default set of nodes on the Policy Design Board. The tree will appear as "untitled" but you can supply a name in the text box.

Remove package from Workspace

Click the X icon to the right of the Add Policy Tree button to remove the Policy Package from your Workspace. It is still available in the Policy Package Library but is no longer listed on your private Workspace.

To retrieve the Policy Package to your Workspace again, you just need to open it, either from the Policy Package Library as described above.

Policy Design Board

The Policy Design Board occupies the area to the right of the Workspace. When no policy package has been selected, the Policy Design Board appears as a blank white space. In this area policy sets, policies, and their associated rules and references can be created and assembled into policy trees of almost limitless size and complexity.

The Policy Design Board consists of the following areas:

• Target Editor
• Combining algorithm
• Obligations and Advice Editor
• Condition Editor

A menu bar stretches across the top of the Policy Design Board that includes the name of any selected Policy Package as well as icons for creating policy sets, policies, rules and references. Selected nodes can also be deleted from here.

Nodes

There are three main types of nodes: Policy Set, Policy, and Rule nodes. All of them appear by default on the Policy Design Board when a new Policy Package is created and opened. The graphical representation of XACML elements as nodes makes it easy to create and structure Policy Trees. Additionally, there is a Reference node that can refer back to another Policy or Policy Set node.

Policy Set node

The Policy Set node appears as a rectangular box on the Policy Design Board. It contains a space for a description of the Policy Set and a drop-down menu marked with an abbreviation of the combining algorithm currently set for the node. Click on the drop-down menu to select a different combining algorithm.

Clicking on the node itself opens an edit panel where the user can enter a policy set description, set a Target, create an Obligation or Advice, and select the combining algorithm. Arrows in the upper right of the window can be used to expand and minimize the window size.

The combining algorithm section of the window has the same functionality as the drop-down box on the node itself.

Below the Target Editor and the Combining algorithm drop-down menu is the Obligations and Advice Editor. Use this in conjunction with the Obligations and Advice Dictionary to create Obligations and Advice.

Policy node

The Policy node functions exactly like the Policy Set node. It also contains a policy description space and a drop-down menu for the combining algorithm. Selecting the node opens an edit panel just like that described for the Policy Set node, where a policy description can be written, Targets, Obligations and Advice added, and a combining algorithm set.

Rule node

The Rule node has a space for a rule description and an icon in the lower right corner that indicates whether the rule is set for permit or deny. The default setting is Deny. Selecting the node opens an edit panel that allows the user to provide the rule description, set deny or permit, and add Targets, Conditions, Obligations and Advice.

There is also a Condition Editor available that can be used to write more complex expressions. See the Condition Editor section below for more information.

Reference node

Use the Reference node to select either a policy set or policy as a destination node to which a policy set or policy may refer.

Interface

Status bar icons

To the left of the status bar at the bottom of the window, you have a set of extra controls to help navigate on the Design Board.

From left to right these icons are used to:

• Left align the nodes on your Design Board

• Enable drag mode in which you can move the entire Design Board in any direction you want.

• Select nodes that you want to work with

• Zoom out or zoom in

• Open or close the Bird's-eye-view pane

Bird's-eye-view pane

The entire scope of a large policy tree will generally not be entirely visible on the Policy Design Board. To give an overview of the entire layout of the policy tree currently open, a Bird's-eye-view pane has been provided in the lower right corner of the Design Board.

Target Editor

In the Target Editor you define the scope of applicability for the current node through a predicate, an expression that evaluates to True or False.

A target expression is a combination of an attribute, an attribute value and a function or an operator between the attribute and the value. The functions that are available depend on the data type of the attribute that is selected. There is only one target per node, but multiple predicates can be combined with logical AND or OR operators.

To open the Target Editor:

1. Select the node in the policy tree that you want to edit.
2. In the edit panel that opens, click the Add Target button.
3. Start adding target expressions.

The edit panel can be maximized to full size. This will resize the frame around the Target Editor to accommodate long attribute names. Use the buttons below the Target Editor to add additional target expressions combined with a logical AND or OR.

Statements combined with a logical AND are stored inside a sequence of XACML AnyOf and AllOf elements. Statements combined with a logical OR are rendered with an added sequence of AllOf and AnyOf.

::note An attribute can be a "Bag" of values and the operators "==", "\<", etc. handle bags as well as single-valued attributes. If attributes are bags, the operator returns true if at least one of the values matches. :::

In the example below, the applicability is limited to requests in which the actor has a subject attribute called clearanceLevel with a value greater than 2 and the resource has an attribute called documentType which is called Classified. A Policy Set, Policy, or Rule with this target will be applicable only if both of these conditions are met. The Authorization Service to which this policy has been deployed will disregard this node during policy evaluation if the Target does not match the values of attributes passed in the XACML request context.

Attribute constraints

An attribute in the Attribute Dictionary may be defined with certain constraints regarding the attribute values. See Setting attribute constraints for more information.

If there is a constraint defined in the Attribute Dictionary for the attribute selected for a target expression, this is indicated in the Target Editor via an icon.

Hover with the mouse pointer over the constraint icon to display a tooltip with the definition of the constraint and a sample of the type of value or format allowed. For enumeration constraints, a drop-down menu is populated with selectable values as defined for the attribute in the Attribute Dictionary.

Target expressions with inconsistency warnings are indicated in the UI. Hover with the mouse pointer over the indicated field to display an explanatory message. Values not fitting the constraint can still be entered, and a policy with warnings in the target expression can be saved.

note

A warning about, for example, an out-of-range value for a constraint does not necessarily mean that the target expression is invalid in terms of the XACML structure. The warning displays to alert you that the policy, as it stands, may lead to valid but unwanted results.

Create a new target expression

1. Click the node for which you want to add a target expression. The edit panel for the node is displayed.

2. Click the Add Target button. The Target Editor interface is displayed. When you move the cursor over a field that can be edited the cursor icon changes to an index finger.

3. If the target expression is empty, <click here\> is shown in the Attribute field.

4. Point to the field, and click to select it.

5. Select an attribute from your current Attribute Directory in either of the following ways:

   

   • Type the first letters of the attribute name in the field to filter by name and then select the attribute from the filtered list of attributes.
   • Click the arrow to open the drop-down list and scroll to select the attribute.

6. Place the cursor in the operator field and select an operator using the same logic as before.

7. Finally point to the value field and type the value that the attribute should match.

Delete a target definition

To delete the entire target definition in one go, click the trash can icon in the upper right-hand corner of the Target Editor.

Add, delete, copy, or cut expressions from the Target Editor

To add, delete, copy, or cut expressions in the Target Editor:

1. Select the expression(s) that you want to edit:

   • Click on an individual attribute to select that attribute.
   • Click on the AND/OR operator to select that branch of the expression.
   • Click on the target editor window itself to select the entire expression.

2. Click on the menu icon that appears towards the far right of the row to display an action menu.

3. Choose the action you want to perform on the selected part of the expression.

   

4. Alternatively, to DELETE or to add AND or OR operators, you can use the buttons at the bottom of the Target Editor.

note

Hovering with the mouse pointer towards the far right of the row also reveals the menu icon.

Copy or cut and paste expressions

1. Select and copy or cut a portion of an expression as explained above in Add, delete, copy, or cut expressions from the Target Editor.
2. Select the position where you want to insert the cut or copied expression.
3. Click on the menu icon on the far right of the row to show the available actions.
4. Click Paste to insert the copied expression at the current location.

Expand or collapse expressions

If you have many expressions on multiple lines, you can expand/collapse the logical AND/OR operator of the block.

1. Click on the logical AND/OR expression.

2. If it is collapsed a plus symbol is added to the icon:

   

3. If it is expanded a minus symbol is added to the icon.

4. Click again to toggle between the expanded and collapsed state.

Combining algorithm

A combining algorithm determines how elements in a policy tree will be combined to render a final result. In the Policy Editor, it is selectable from a drop-down menu in the right-hand corner of the policy and policy set nodes, and also in the edit panel of the currently selected node, where it is presented as a drop-down menu in its own section.

There are two types of combining algorithms:

• Policy-combining algorithms - these are selected inside a policy set and are used to combine the results of policies and policy sets.

• Rule-combining algorithms - these are selected inside a policy and are used to combine the results of rules.

The following table provides a brief description of the behavior of each combining algorithm. Note that some of them are not applicable for rules. For complete information, please refer to the eXtensible Access Control Markup Language (XACML) Version 3.0.

Combining algorithm	Abbreviation	Description
Deny overrides	DO	Even if multiple policies or rules are evaluated to Permit, one single Deny leads to a Deny decision.
Deny unless permit/Permit unless deny	DuP/PuD	There are four possible outcomes to an authorization request: Permit, Deny, NotApplicable, and Indeterminate. Sometimes, it is desirable to hide the NotApplicable and Indeterminate decisions to only allow for Permit or Deny. By using one of these combining algorithms we guarantee that either Permit or Deny will be returned.
First applicable	1stA	The final decision returned is the first one produced either of Permit or Deny.
On permit apply second	oPAS	In some cases, it may be useful to have a Condition at the policy or policy set level, as a Condition allows for more expressive matching than a Target, which can only match against constant values. The "On permit apply second" combining algorithm makes it possible to define a policy structure which behaves as if there was a condition at the policy or policy set level, without changes to the XACML 3.0 schema. This combining algorithm only applies for policy sets to combine policy sets and policies; it is not available for rules.
Only one applicable	1A	For either of a Permit or Deny to be returned, then only one of the children must produce a valid decision -- whether Deny or Permit. This combining algorithm only applies for policy sets to combine policy sets and policies; it is not available for rules.
Ordered deny overrides/Ordered permit overrides	oDO/oPO	Works the same way as "Deny/Permit overrides", but with the difference that policies, policy sets, and rules are considered in the order in which they are defined in the policy.
Permit overrides	PO	Even if multiple policies or rules are evaluated to Deny, one single Permit leads to a Permit decision.

Obligations and Advice Editor

Use the Obligations and Advice Editor to apply an obligation or advice to a Policy Set, Policy, or Rule. In the Obligations and Advice Editor, you can add or delete an obligation or advice, link an obligation or advice to an effect choice (permit/deny), and write attribute assignment expressions for selected attributes.

Add an obligation or advice

1. Select the node in the policy tree to which you wish to add an obligation or advice.

2. At the bottom of the edit panel that is displayed, click the arrow next to Obligations and Advice to expand the view.

3. Click the Add Obligation or Advice button.

   A dialog box displays that presents a list with the obligations and advice entities created in the Obligations and Advice Dictionary. See the Obligations and Advice Dictionary topic for more information.

4. Select an obligation or advice and click Add .

Adding an obligation or advice from the list returns the user to the edit panel where the selected obligation or advice now appears in the expanded view beneath Obligations and Advice.

Clicking on the arrow next to the added obligation or advice expands the display to allow the user to set the effect for the obligation or advice and create an optional attribute assignment.

note

The Add Obligation or Advice button is always visible at the bottom of the expanded view of the Obligations and Advice Editor so that you can add additional obligations and advice at any time.

Link an effect to an obligation or advice

1. Click the Permit / Deny switch to set the desired effect to the obligation or advice.

At this point the obligation or advice requires no additional modification and is ready for use in the Policy Set, Policy, or Rule with which it is associated.

However, it is possible to go further and make an attribute assignment in the space provided beneath the Permit/Deny toggle button.

Add an attribute assignment

Attribute assignments can be added to an obligation or advice, as a way of including arguments in obligation and advice expressions.

1. In the Attribute Assignment(s) section of the edit panel, click the Attribute assignment button.

2. Click anywhere in the blue space next to the equal sign to open the assignment editor.

3. Select an attribute from the drop-down menu.

   The assignment expression for it is written in the editor.

   

   The expressions are written in the same way as expressions in the Condition Editor, although with greater freedom since condition expressions must be Boolean and attribute assignment expressions are not limited in this way. See the Condition Editor for details.

4. Optionally, click the drop-down menu on the right to remove the assignment or exclude the category from the attribute.

   

5. To make an additional attribute assignment, click the Attribute assignment button again. This will extend the editing area to accommodate more assignments.

Delete an obligation or advice

An obligation or advice can be deleted from within the editor at any time. Clicking on the trash can icon will remove the obligation or advice from the node in question. Identifying information for the obligation or advice, including its name, description, namespace and ID is available under Show Details.

Condition Editor

The Condition Editor is used to create a condition inside a Rule. To open the Condition Editor, select the rule that you want to edit in the policy tree. This opens an edit panel where the user can enter a description for the rule, set an effect, and create an obligation or advice.

The section of the panel "Applies when" holds two buttons. Click the Add Condition button to open the Condition Editor.

The Condition Editor is displayed in the panel, and attributes, functions and data types can be arranged with the use of operators to construct predicates that can be combined into advanced expressions.

Arrows in the upper right of the edit panel can be used to expand and minimize the panel size. Maximizing the edit panel to full size provides access to more editing tools. See Functions in the Condition Editor.

There are some similarities between a condition and a target. But a condition can be much more complex and is more free form. In a condition you can compare the values of attributes and use complex nesting of attributes and functions in ways that would not be allowed in a target.

ALFA syntax

To simplify editing, the Condition Editor uses ALFA language syntax. The ALFA syntax dramatically simplifies the construction of complex statements. This expression, for instance, checks that the user's clearance level is higher than or equal to the classification of the resource:

Attributes.access_subject.userClearance >= Attributes.resource.resourceClassification

Inside a Target, all the values in a Bag are automatically tested to find a match. In a Condition, things may be a bit more complex. First of all, you may have bags on both sides of the operator and secondly, you can use a broader set of functions which you want to apply to the values. Therefore, you may have to specify how the function should be applied, if all the values on one side are to be compared with all the values on the other side, etc.

Using operators

For instance, in ALFA the '==' operator means "compare all the values to the left with all the values to the right and if at least one match is found, return True".

Functions

The notation from the above example is equivalent to the following, complete ALFA syntax for the same expression:

System.anyOf(function[System.stringEqual],Attributes.access_subject.my_projects,Attributes.resource.related_projects)

While this second ALFA syntax example is easier and more compact than regular XACML, as you can see, using operators to compare the left side and the right side is preferable. The syntax is shorter and overall easier to read.

However, only the most commonly used combinations of functions have a shorthand notation through the use of operators. Since there are more than 250 XACML functions available for you to use in the Policy Editor, you will also have to use the complete ALFA syntax for XACML functions.

Atomic attributes and bags

Attributes return bag values. Yet, some functions require atomic values. For conversion, use the appropriate one-and-only function. For instance, the following example checks that users are not approving payments exceeding their limits.

integerOneAndOnly(Attributes.access_subject.approval_request) - integerOneAndOnly(Attributes.access_subject.approval_limit) < 0

This assumes that the attributes approval_request and approval_limit contain exactly one value. If there are no values or multiple values, then the one-and-only function will return an Indeterminate result.

Functions in the Condition Editor

To call a function, use the function name followed by the arguments enclosed in parenthesis. Here is an example of a condition which uses function calls:

allOf(function\stringRegexpMatch], ".*fishing.*", Attributes.access_subject.clubMembership) && Attributes.access_subject.age > 25

If this expression renders True you know that at least one of the names of clubs to which the user belongs contains the string 'fishing'. In addition, a logical AND is used to ensure this fisher is more than 25 years old.

To select the function to use, type the function name in the condition editor edit box.

Alternatively, if you don't know the function name:

1. Maximize the Condition Editor.

2. Select the Functions tab to the left.

3. Browse the list or filter it by entering a search term in the Filter field.

4. Select the desired function.

   

5. Click the Insert button to include the function in the edit box.

Add parameters to the function statement

To include a comma-separated list of parameters enclosed in parentheses after the function name, if the parameter is:

• used to call yet another function, type function[<function name>]
• an Attribute, type the attribute name or select the attribute from the Attribute tab in the maximized Condition Editor.
• a string, type it enclosed in double quotation marks.
• an integer value, just type the number you need.

Operator precedence

Operator precedence is fixed in the ALFA grammar. The operators are listed below from lowest (1) to highest (6) precedence:

Precedence	Operator	Associativity (info)
1	'|'	Right associative
2	'&'	Right associative
3	'=', '<', '>' or '$'	Left associative
4	'@' or '^'	Right associative
5	'+' or '-'	Left associative
6	'*', '/' or '%'	Left associative

Parenthesis can be used to control the evaluation order of operators, for instance you can write "(2+3) * 5" to perform the addition between 2 and 3 before the multiplication with 5.

Associativity of operator

If operators have the same precedence, the order of evaluation is determined by their associativity. Operators can be left associative or right associative (or non-associative for that matter). If ¤ is a right associated operator the expression x ¤ y ¤ z is the same as x ¤ (y ¤ z).