Policies

The Policies section is where you create, manage, and edit the rules that govern access and operations within your organization. This section provides a powerful interface to author and organize policies using the ALFA (Abbreviated Language for Authorization) language.

The ALFA language

ALFA is a domain-specific language that uses a syntax similar to popular programming languages like Java and C#. Authorization Hub enables you to divide your policies into multiple ALFA files, which are then bundled in a single policy package. This package encapsulates the primary policy, all referenced policies, and the attributes dictionary.

tip

For a deeper understanding of ALFA, its syntax, and policy authoring, visit the ALFA documentation siteOpens in a new tab.

Interface

The main Policy editor interface consists of the ALFA resources and Editor areas.

ALFA resources

This area on the left lists all the ALFA files associated with your project, including attribute-dictionary.alfa. Within this area, you can perform various actions on your ALFA files, such as:

• Open your files in the editor by double-clicking on the appropriate filename.

• Add new ALFA files by clicking the Add new file button on the upper right corner of the section.

  

• Manage your files by clicking the options button (three dots) next to their filenames and selecting between:

  • Rename: Allows you to change the name of the target file.
  • Duplicate: Creates an exact copy of the target file, adding Copy_of_ to the beginning of the filename.
  • Delete: Helps you clean up your policy set by removing unneeded files.

note

Changes performed on the ALFA resources area are saved automatically.

Finally, the ALFA resources section also helps you quickly identify files with issues by coloring them red.

You can also use the Actions menu to export your project's policies to a JSON file and import policies from a file. Imported policies are saved to My workspace as pending changes. Read Import and export for details.

attribute-dictionary.alfa

When you navigate to the Policies page, the current state of your Dictionary is made available as a read-only attribute-dictionary.alfa file in the ALFA resources area. You can also define new attributes directly within your ALFA policies, even if they aren't yet in the Dictionary.

note

Currently, the system does not automatically include attributes defined in ALFA policies back in the Dictionary. Consequently, these attributes cannot be utilized in attribute connector configurations as provided or key attributes, and no caching configuration can be applied to them.

When you save your policy, this attribute dictionary "snapshot" is saved along with the other ALFA resources.

Editor

The central area of the screen is the Editor, where you can write and modify your policies. The Editor offers three view modes, selectable from the toolbar above the editing area:

• Code: a full-width code editor (the default view).
• Split: the code editor and a graphical canvas displayed side by side, separated by a draggable divider.
• Graphical: a full-width interactive canvas with the code editor hidden.

Code editor

The code editor provides the following features:

• Syntax highlighting, including bracket matching, for improved readability and easier debugging.
• Suggestions and auto completion that speed up your coding efforts.
• Jump to definition allowing you to go quickly to the definition of a PolicySet, Policy, or Rule.
• Error checking. Syntax errors are highlighted allowing you to catch and correct them as they occur, minimizing the time spent on debugging.
• Minimap for quicker navigation in large files.
• Multi-file support. For each file you open, a new tab is added above the editor allowing you to quickly navigate between all open files. Switching files using the tabs or file explorer also updates the canvas to display the new file's policy tree.

tip

Open files with unsaved changes are indicated by a green dot next to their filename on the tab list.

Graphical policy canvas

The canvas is an interactive visualization of the policy structure in the active file. It renders a tree of namespaces, policy sets, policies and rules defined in the active file, including any references to those defined in other files. In addition to navigation, the canvas lets you create, delete, reorder, reparent, and reference policy nodes without writing ALFA directly. Each node displays the following key information:

Node type	Displayed information
Namespace	Namespace identifier
Policy set	Name (including fully qualified name), combining algorithm
Policy	Name (including fully qualified name), combining algorithm
Rule	Name, effect (Permit / Deny)
Reference	Name of the referenced element (visually distinct from direct-definition nodes)

Node types are distinguished by shape, icon, and color, making the tree easy to scan. Dotted namespaces such as acme.policies are shown as a single node rather than decomposed into acme → policies, so the same namespace segment can appear in multiple, uncross-linked nodes.

note

Opening a problematic file is handled gracefully. If an ALFA error still leaves part of the policy readable, the canvas shows the readable portions and gives each affected node a red badge that lists its errors, instead of hiding the whole tree. If a node declares the same child more than once, the parent node shows a warning instead of drawing each occurrence. Only a completely unreadable file shows a distinct error message, and fixing the file refreshes the graph automatically. Additionally, opening a large file (over 1000 nodes) warns you before drawing the graph, since it may become slow or unresponsive. Choose Proceed anyway to draw the graph, or Cancel to switch to the code-only view (this also applies when you opened the file in Split mode). No file is ever refused, and once you proceed for a file, the warning won't reappear for it this session.

note

Members with the Project viewer role can open nodes on the canvas and inspect their fields in the Node editor (see below), but cannot make changes. All editing controls, including Update, are unavailable to members with this role.

The tree is automatically arranged left-to-right by default. Click the layout button in the upper-left corner of the canvas to switch to a top-to-bottom arrangement.

Canvas navigation:

• Pan, zoom, and fit-to-screen - standard canvas navigation controls.
• Expand/collapse nodes - each node has a toggle to show or hide its subtree. All nodes are expanded by default when a file is opened. Collapse state is preserved per file during the session but resets on page refresh.
• Selecting a node - clicking a node on the canvas, including a reference node, selects it without changing the pan position or zoom level and highlights it where it already sits. Only reference traversal centers the target node on arrival. Back and Forward restore the exact pan, zoom, and selection you left.
• Bidirectional sync (Split mode) - clicking a node on the canvas scrolls the code editor to that node's source definition, without changing the canvas zoom level. Moving the cursor in the code editor highlights and centers the corresponding node on the canvas, also without changing the zoom level. This navigation does not by itself open the Node editor.
• Reference traversal - clicking a reference node navigates to the canonical definition of the referenced element, even if it is defined in a different file. The canvas switches file context and highlights the target node.

Canvas editing:

The canvas supports the following structural editing operations. Structural edits appear in the ALFA source immediately, but like other changes in the Editor, they do not persist until you explicitly save the file (see Save your changes, below).

• Create a node

  Right-click the canvas background or an existing node to open the context menu, then choose the node type to add. Valid child types follow the ALFA containment rules:

  • Namespace: Namespace, Policy set, Policy, Rule
  • Policy set: Policy set, Policy
  • Policy: Rule

  New nodes receive auto-generated names (ns1, ps1, p1, r1, …). The default combining algorithm for Policy sets and Policies is firstApplicable. For Rules, you choose the effect (Permit or Deny) at creation.

• Delete a node

  Right-click a node and select Delete. A confirmation dialog shows the impact as a count per node type and a total, not a list of node names. It also indicates whether the node, or any descendant, is referenced elsewhere in the package. Reference detection spans all ALFA files, not only the current one. If the node is a Namespace, the confirmation also notes that other declarations inside it (attributes, functions, and similar) aren't shown in the graph and will be deleted too. Confirm your action or click Cancel to leave the canvas unchanged.

• Reorder and reparent nodes

  Drag a node to reorder it within its parent or move it to a different valid parent in the same file. Valid reparent targets follow the same ALFA hierarchy rules as node creation. The canvas prevents moves that would create name collisions or circular structures.

  note

  The order of child nodes is significant for combining algorithms such as firstApplicable.

• Add a reference

  Right-click a node and select Reference. From a Policy set node, you can add a reference to an existing Policy set or Policy in the package. From a Policy node, you can add a reference to an existing Rule.

  Choose the target from the list of valid nodes. The reference is preserved as a reference in the ALFA code and renders as a distinct reference node on the canvas.

  note

  A target the host node already references, including a Rule that is already an inline child of the host Policy, remains visible in the dropdown but is marked as already referenced and cannot be selected again. This prevents both an invalid policy (for a Policy referencing a Rule) and duplicate obligations/advice at evaluation time (for a PolicySet referencing a Policy or PolicySet).

  This check applies to references you add from the dropdown. A duplicate reference already present in the ALFA source (for example, authored directly in the code editor) is not flagged or removed by it.

• Undo / Redo

  Use Ctrl+Z (Win or Linux) / Cmd+Z (Mac) to undo a canvas operation, and Ctrl+Y / Shift+Cmd+Z to redo. Undo history is shared with the code editor and is preserved when switching between files within the same session.

Node editor

Selecting a node also opens the Node editor, a panel for viewing and editing that node's core properties (see Fields per node type below) without writing ALFA directly.

Panel behavior:

• Closing the Node editor returns focus to the canvas and clears the node selection.
• With the panel open, selecting a different node replaces its contents with the newly selected node's fields. If there are unsaved (pending) changes, a warning appears before those changes are discarded.
• Switching files, or clearing the current selection, closes the Node editor.
• Returning to a previously open file restores which node was selected and reopens its editor. Any pending, unsaved edits are not restored. Instead, they are discarded, the same as if you had clicked Cancel.

Committing changes:

• Changes apply with an explicit Update action. This is separate from, and does not replace, saving the file with Save / Save all (see Save your changes).
• Update is unavailable (disabled) when there are no pending changes, or when the form has an error. Only an untouched name, combining algorithm, or effect that already had an error when you opened the node is exempt: it is flagged in place but does not prevent you from updating the rest of your edits. Most target, obligation and advice, and condition errors block Update even if they were already in the file.
• After clicking Update, the Node editor stays open showing the applied state, and Update becomes unavailable again until you make a further change. No success or confirmation message is shown, to avoid confusion with the separate file Save action.
• Cancel discards any pending changes and closes the Node editor.
• Typing in a Node editor field has its own in-field undo/redo which does not interact with the canvas/code editor's shared undo/redo history.

Fields per node type:

Node type	Editable fields
Namespace	Name. Accepts dot-separated segments (for example com.acme.policies).
Policy set	Name, policy combining algorithm (see Combining algorithms, below).
Policy	Name, rule combining algorithm (see Combining algorithms, below).
Rule	Name, effect (Permit / Deny).
Reference	A dropdown that lists the valid targets in scope: Policies and Policy sets for a reference from a Policy set, or Rules for a reference from a Policy. The editor also offers an action to jump to the referenced element's canonical definition, which opens that node's own editor.

For Policy set, Policy, and Rule nodes, the name field is optional. An unnamed node is valid ALFA, but cannot be referenced by other policies until it is named.

If a combining algorithm or reference inherited from ALFA doesn't resolve to a valid choice (for example, after an edit made directly in the code editor), the field shows that value marked as invalid instead of appearing empty. A Rule with no effect is the exception: no button is selected, a red ring shows, and a message highlighting the missing decision displays. Choosing a valid option from the field resolves the problem (the code editor is not required).

Naming rules and validation:

Identifiers (node names and each namespace segment) must match the following format and validation rules.

• Starting character: an ASCII letter (a–z, A–Z) or an underscore (_)

• Allowed characters: ASCII letters (a–z, A–Z), numbers (0–9), or underscores (_)

• Separators: segments within a namespace must be separated by single dots (.)

• No empty segments: leading dots, trailing dots, or consecutive dots (..) are not allowed

• ALFA reserved words: identifiers cannot match any ALFA reserved keyword from the Reserved words section

  note

  Matching is case-sensitive. For example, Permit is allowed, while permit is not.

A name must also be unique among nodes of the same kind: specifically, a duplicate is another node of the same kind that already has the same fully qualified name (namespace path + name), compared case-sensitively, anywhere in the loaded policy project, not only among immediate siblings. Unnamed (anonymous) Policy sets, Policies, and Rules are exempt from this check. Namespaces are the exception: a Namespace name only counts as a duplicate when it is declared twice within the same file. The same namespace may be declared across multiple files, since those declarations are additive.

A name inherited from ALFA that is invalid, or a duplicate, is flagged as soon as the Node editor opens, not only after you edit it. Validation of new input runs on Update and fields that fail validation are highlighted inline. Renaming a node that is referenced elsewhere, or a Namespace whose descendants are referenced, triggers a warning identifying the affected references. This is a warning only and references are not rewritten automatically.

Combining algorithms:

Abbreviation	Algorithm	Policy set combining	Policy combining	Description
DO	Deny overrides	✔️	✔️	If any child element returns Deny, the final decision is Deny.
PO	Permit overrides	✔️	✔️	If any child element returns Permit, the final decision is Permit.
1ST	First applicable	✔️	✔️	The first child element that returns Permit or Deny determines the final decision.
DUP	Deny unless permit	✔️	✔️	Defaults to Deny unless at least one child element returns Permit.
PUD	Permit unless deny	✔️	✔️	Defaults to Permit unless at least one child element returns Deny.
ODO	Ordered deny overrides	✔️	✔️	Same as Deny overrides, except the order of child elements is strictly enforced during evaluation.
OPO	Ordered permit overrides	✔️	✔️	Same as Permit overrides, except the order of child elements is strictly enforced during evaluation.
OOA	Only one applicable	✔️	❌	Requires that exactly one child element is applicable (returns Permit or Deny) and that decision is the overall decision. Multiple applicable children result in Indeterminate.
OPAS	On permit apply second	✔️	❌	If the first child returns Permit, the second child is evaluated. If the second child's condition is not met, it falls back to evaluating the third child.

Target:

From the Node editor, a Policy set, Policy, or Rule node's target can be built without writing ALFA:

• A node with no target opens empty (no target means the node always applies).

• Add a match

  An attribute, an operator, and a value.

  • The attribute list combines entries from the Dictionary and the project's ALFA files into a single, categorized view. Attributes falling outside the standard categories (Subject, Resource, Action, or Environment) are grouped under a single fallback heading. Attributes present in both sources are listed only once.
  • The available operators are derived from ALFA's comparison functions for the attribute's type and are displayed using standard ALFA syntax: the infix symbol where one exists (==, <, <=, >, >=), otherwise the function name with its type prefix removed (for example startsWith, endsWith, contains, regexpMatch, equalIgnoreCase, match). Functions declared within the policy follow the same rules and appear under their respective names.
  • Changing the attribute or operator preserves the value where it remains valid, and clears it otherwise.
  • The value is validated against the operator (for example, dates require YYYY-MM-DD, time and date-time values require an explicit time zone). Blank values and date or time format errors appear when you leave the field, not while you type. Leading and trailing whitespace is preserved exactly as typed. Whitespace-only values are rejected for string == and equalIgnoreCase-type operators, and accepted only with startsWith, endsWith, contains, and regexpMatch. All other data types reject empty values.

  A match is written attribute-first, using the infix operator where ALFA has one. An operator with no infix form is written as a function call with the value first (for example, stringStartsWith("adm", user.role)).

• Combine matches with AND / OR

  Matches combine using a fixed, three-tier hierarchy:

  1. top-level "all of" (AND) set
  2. optional alternatives where any one may hold ("any of", OR)
  3. within an alternative, a further "all of" (AND) set

  A fourth level is not supported.

• Remove matches

  Remove a single match, or a whole alternative (with everything it contains), or clear the target entirely. The builder tidies up automatically: an alternative left with no matches is removed, an "any of" group reduced to a single alternative is unwrapped, and removing the last item returns the target to the empty state.

• Edit an existing target

  The builder also reads targets that were written manually in the code editor, regardless of whether the match is written attribute-first, value-first, or as a function call, and shows each as one canonical attribute-operator-value row. Modifying a match or group does not reformat, reorder, or retype other untouched matches or groups.

All target changes take effect in the ALFA source on Update, the same as other Node editor fields.

If a match becomes invalid after being authored (for example, because its attribute was removed from or retyped within the project), the Target builder flags it instead of showing it empty. It indicates the error, and lets you fix it in place by picking a different attribute, changing the operator or value, or removing the match without using the code editor. Until the match is fixed, Update is unavailable.

If the Target builder cannot show every match in a target as an editable row (for example, an incomplete clause, or a form it doesn't support), it shows the whole target read-only, exactly as written in the file, and points you to the code editor to change it there, instead of appearing empty. A read-only target does not change when you click Update, and does not prevent updating the node's other fields.

Obligations and advice:

From the Node editor for a Policy set, Policy, or Rule, you can attach one or more Obligation or Advice entries:

• Each entry selects an existing Obligation or Advice definition (of the type you're adding) and links it to an outcome (Permit or Deny). Either directive type can be linked to either outcome.

• For each entry, you can add, edit, and remove attribute assignments that provide the values the directive carries. Each assignment pairs a declared attribute with a value of one of three kinds:

  • a constant
  • another attribute's value, resolved at decision time. If that attribute has more than one value, every value is returned. To return exactly one, use an expression instead.
  • an ALFA expression, written in an embedded editor with the same completion, hover, and error-checking as the code editor. The editor accepts a value only. Anything that would change the structure of the policy is rejected with a message pointing you to the ALFA editor, and blocks Update.

  An entry with no assignments is valid. It shows a "No assignments" empty state with an Add an assignment action.

• All three value kinds are checked against the declared type of the assignment's attribute. A mismatch is shown inline (for example, "hr.headcount expects integer. This expression returns string.") and blocks Update.

• Problems stay visible even when the Obligations and advice section is collapsed. The section header shows the number of issues (for example, "2 issues"), and every row that blocks Update gets a red border.

• Switching an assignment between value kinds clears the previous value. You are asked to confirm only when the value being discarded is already saved in the policy, including a saved value you have edited. Values you entered but have not saved are discarded without a prompt.

• If you change an assignment's attribute and the existing value no longer fits its type, the value is kept and flagged, never cleared automatically. Update the value to match.

• You can move through the whole panel with the keyboard. Tab and Shift+Tab move through every field, including the attribute dropdowns, up to Cancel and Update, and Enter or Arrow Down opens a dropdown. This also applies to the Target builder's attribute dropdown.

• Added, removed, or edited entries and assignments are written to ALFA on Update.

Condition:

For a Policy set, Policy, or Rule node, the Node editor's Condition section contains an embedded editor for authoring boolean condition logic that a target cannot express. The editor comes with autocomplete, hover, and inline diagnostics like the code editor.

• A node with no condition shows a "No condition" placeholder instead of a live editor.
• The condition is only written to the ALFA source on Update, in the position ALFA requires (for a Policy set or Policy, that's between the target and the combining algorithm). Committing over an existing condition replaces it rather than adding a second one.
• Clicking Cancel or closing the panel discards a pending edit.
• Update stays disabled while the condition has an unresolved error.
• A pre-existing, hand-written condition on any of the three node types opens in the editor rather than being hidden or reported as a problem.

To remove an existing condition, clear the embedded editor's contents.

Save your changes

Authorization Hub requires an explicit action to save changes made to your ALFA files. The following options are available in the upper right corner:

• Save: Saves changes to the ALFA file currently active in the Editor. Files open in other editor tabs are not affected.

• Save all: Saves changes to all ALFA files open in the Editor, including both the active file and those in background tabs. Click the downward arrow next to Save and then Save all.

note

attribute-dictionary.alfa is saved along with your other ALFA files with every save, whether you use Save or Save all.

note

Saving a file also stages it in My workspace. Files with staged changes show a vertical orange line in the ALFA resources list until you save to project or discard the change. This is separate from the green dot on the tab, which only indicates unsaved edits still in the editor.

note

Saving changes made through the canvas or the Node editor is captured in the audit trail the same way as changes made directly in the code editor, with the same user, timestamp, and change information.

Problems panel

The Editor, in addition to its core editing capabilities, includes a dedicated Problems panel. This panel displays all errors and warnings in your ALFA files, providing a description of what went wrong. It also offers line numbers that pinpoint the exact location of each issue for quick resolution.