Policies & Policy Groups

Article Type: Concept
Audience: Application Administrators, Security Architects, Partners, Solution Engineers
Module: Fuuz Platform - Access Control
Applies to Versions: 2024.12+

1. Overview

Policy Groups and Policies form the granular access control layer in Fuuz, sitting between Roles (which define job functions) and individual Statements (which define specific API-level permissions). Together they enable precise control over data access, screen visibility, flow execution, and real-time subscriptions while maintaining a maintainable, reusable permission structure.

A Policy represents a specific job capability — for example, "Receive Inventory" or "Inventory Overrides." Policies are the unit of permission reuse: the same policy can be included in multiple policy groups. A Policy Group is a named collection of policies that maps to a functional role or access profile. Policy groups are attached to Roles (and in specific cases, directly to individual users).

The full permission hierarchy flows top-down: Roles → Policy Groups → Policies → Statements. Understanding how each layer connects — and the rules that govern them — is essential to building correct, secure permission structures in Fuuz deployments.

2. Architecture & Data Flow

Definitions

• Role: The top-level permission construct representing a job function (e.g., Warehouse Operator, Shipping Manager). Roles control not just permissions but also the side navigation menu, home screen, and other UI context presented to a user. Users may have multiple roles and switch between them.
• Policy Group: A named collection of individual policies. Policy groups are the connective layer between Roles and Policies. The recommended starting pattern is one policy group per role. Multiple policy groups can be attached to a single role to create permission supersets (see Superset Pattern below).
• Policy: Represents a specific job capability or function. Policies contain one or more statements. Naming convention: use functional job-capability names (e.g., "Receive Inventory," "Inventory Overrides") rather than technical resource or screen names. This makes policies reusable and meaningful across roles.
• Statement: The atomic permission rule within a policy. Each statement grants or denies a specific action on a specific resource. Five statement types are available: GraphQL, Orchestration, Websocket, Integration, and Screen.
• Action: The operation performed on a resource. GraphQL actions include Create, Query, Update, Delete, and Upsert. The "Mutate" action visible in the GraphQL editor is a special-case that applies only to narrow platform-level operations (e.g., user file upload, send system email) — it does not apply to standard data model CRUD operations and should be ignored in most implementations.
• Resource: Any Fuuz entity requiring access control — data models, screens, flows, integrations, or WebSocket topics. Resources are organized in a hierarchical tree (Module Group → Module → Resource → Field).
• Field-Level Security: Granular permissions restricting access to specific fields within a data model. Enforced at the GraphQL API layer — fields may appear editable on screen even when the user lacks permission; the API will reject the save attempt.
• Limited Web Access: The current default access type for new users. Grants navigate permission to zero screens by default; permissions must be explicitly added. Contrast with the legacy Full Web Access type, which grants access to all screens by default.
• Effective Permissions: The cumulative set of permissions a user receives from all attached policy groups across all roles. Deny statements take precedence over grants from any source.
• Transform Rule: A JSONata expression configured within a statement that dynamically filters or restricts whether the statement applies to a given request, based on user attributes, request context, or data values. Used for scenarios such as department isolation, ITAR compliance filtering, or warehouse-specific data restrictions. Transform rules are an advanced, complex feature — use only when simpler permission structures cannot meet the requirement.
• Allowed IPs: A whitelist of IP addresses or CIDR ranges configured within a statement. When set, only requests originating from the listed addresses are permitted to exercise the statement's permission. All other IPs are denied access to that resource.
• Disallowed IPs: A blacklist of IP addresses or CIDR ranges configured within a statement. When set, requests from the listed addresses are explicitly denied access to the resource, while all other IPs are permitted. When both Allowed IPs and Disallowed IPs are configured, Disallowed takes precedence.
• Visual Policy Builder: The point-and-click interface for constructing policy statements without writing JSON. Provides a resource tree, action checkboxes, allow/deny toggles, and the Rules configuration interface for Transform Rules and IP restrictions.
• GraphQL Summary: The notation displayed on each policy showing the count of configured actions, resources, and rules within that policy (e.g., "GraphQL: 2 Actions, 6 Resources, 0 Rules"). Used in the Attached Policies tab and policy group Visual Editor to quickly assess the scope of a policy without opening it.

Components

• Policy Groups Table: Master list of all policy groups showing attached policy count, direct user count, and attached role count.
• Policy Group Detail Form: Multi-tab interface with Details (including a read-only cumulative Visual Editor), Attached Users, Attached Policies, and Attached Roles tabs.
• Visual Editor (Policy Group): Read-only view showing the merged effective permissions of all policies in the group. Editing is not possible here — navigate to the Attached Policies tab to modify individual policies.
• Individual Policy Editor: Full visual builder for creating and modifying a single policy's statements. Accessed from the Attached Policies tab by selecting a policy and clicking Edit.
• Statement Builder: Within the policy editor, each statement is configured by selecting a type (GraphQL, Orchestration, Screen, Websocket, Integration), then choosing actions and resources from hierarchical trees.
• Rules Section: Optional advanced configuration within a statement for Transform Rules (JSONata expressions for conditional logic), Allowed IPs, and Disallowed IPs. Transform rules are a complex, discouraged feature — prefer simpler permission structures where possible.

Permission Hierarchy & Flow

Fuuz implements a four-tier permission hierarchy:

1. Roles (Tier 1): Top-level job function assignment. Users are assigned roles; they receive only the permissions of their currently active role.
2. Policy Groups (Tier 2): Collections of policies attached to roles. A role can have multiple policy groups (enabling the superset pattern). Policy groups can also be attached directly to gateway and API access type users for extended permissions.
3. Policies (Tier 3): Job capability definitions containing statements. Policies can be included in multiple policy groups for reuse.
4. Statements (Tier 4): Atomic API permission rules — the actual grant or deny of a specific action on a specific resource.

Permission Hierarchy — Visual Example

The diagram below illustrates the full hierarchy using a Warehouse Manager and Warehouse Operator example. It shows how the superset pattern works in practice, and demonstrates function-based policy naming with approval workflows that gate ERP integration.

Operators submit counts and adjustments for review. Managers approve them, which triggers the ERP integration flow. This enforcement happens at the permission level — operators do not have Orchestration execute permission for the approval flows.

The Superset Pattern

When a manager or supervisor role needs all the permissions of an operator role plus additional capabilities, attach multiple policy groups to the manager role:

• Create a Warehouse Operator policy group containing the "Receive Inventory" and "Move Inventory" policies.
• Create a Warehouse Manager policy group containing the "Inventory Overrides" policy.
• Assign only the Warehouse Operator policy group to the Operator role.
• Assign both the Warehouse Operator and Warehouse Manager policy groups to the Manager role.

The manager inherits everything the operator can do plus the additional capabilities. Changes to the Operator policy group automatically propagate to the Manager role — no duplication required.

Direct User Attachment

Policies and policy groups can be attached directly to individual users. This is the accepted and recommended approach for gateway users (Edge Gateway user accounts) that need capabilities beyond the Gateway access type baseline. For example, if a gateway user needs to execute a specific backend flow from an edge flow, create a targeted policy with that Orchestration permission and attach it directly to the gateway user via the policy's Attached Users tab.

For regular end users, route permissions through Roles. Direct attachment to regular users creates fragmented, hard-to-audit configurations and should be avoided.

3. Use Cases

• View-Only Inventory Access: Grant a supervisor read-only access to inventory data. Create a policy with a GraphQL Query statement on the Inventory Tracking model, including adjacent models used for display (Products, Locations, Areas, Statuses). Add a Screen statement for the inventory view screen. Attach to an "Inventory Viewer" policy group and role.
• Inventory Edit Access: Allow a warehouse associate to modify inventory records. Add GraphQL Update AND Query statements on the Inventory Tracking model (both required — mutations fail without accompanying Query permission).
• Manager Inheriting Operator Permissions: A shipping manager needs all permissions of a shipping operator plus the ability to override shipment statuses. Use the superset pattern: attach both the Shipping Operator and Shipping Manager policy groups to the Manager role.
• Privileged Action via Backend Flow: Allow a user to perform inventory adjustments only through a controlled workflow with validation. Grant Orchestration → Execute permission on the specific "Inventory Override" backend flow. Do not grant broad GraphQL Update permissions. The flow enforces business rules internally.
• Gateway User Extended Permission: A gateway user needs to call a backend flow in another tenant from an edge flow. Create a policy with the specific Orchestration execute permission and attach it directly to the gateway user's profile.
• Read-Only Analytics Role: Build a policy group granting Query permissions across multiple data models (Production, Inventory, Quality) while explicitly denying Create, Update, and Delete — giving analysts data visibility without modification rights.
• Field-Level Data Masking: Restrict sensitive fields such as product cost or customer credit terms to specific roles while allowing broader access to other fields in the same data model.
• Multi-Facility IP Restrictions: Create policies with Allowed IP rules ensuring shop floor operators can only access inventory data when connected from their facility's network.
• ITAR Compliance via Transform Rules: Use Transform Rules to automatically hide ITAR-controlled records from users who lack the required security clearance attribute on their user record. (Note: Transform Rules are a complex, advanced feature — validate thoroughly before deploying.)
• External Partner Portal: Create a restrictive policy group with IP whitelisting and minimal resource access for external contractors or integration partners, ensuring they can only reach the data relevant to their engagement.
• Real-Time Screen Subscriptions: Data-change WebSocket subscriptions (live screen updates when queried records change) do not require explicit Websocket statement configuration — they are automatically permissioned by the GraphQL Query permission for the same resource.
• Department Data Isolation: Use Transform Rules to filter data based on user department attributes, ensuring production users only see production data and quality users only see quality records.

4. Screen Details

/app/[tenant]/admin/access-control/policy-groups

Policy Groups Table

The main list screen displays all policy groups with the following columns:

Policy Group Detail Form — Tabs

DETAILS Tab: Shows the policy group name, description, and a read-only Visual Editor displaying the cumulative effective permissions from all attached policies. The JSON tab shows the merged policy definition. This view is for reference only — to make changes, use the Attached Policies tab.

ATTACHED USERS Tab: Displays users who have this policy group directly attached. Typically used for gateway and API access type users requiring permissions beyond their access type baseline.

ATTACHED POLICIES Tab: The primary management interface. Attach existing policies to the group, edit individual policies (which opens the full policy editor), or detach policies. Each policy displays a summary notation (e.g., "GraphQL: 1 Action, 6 Resources, 0 Rules").

ATTACHED ROLES Tab: Shows which roles include this policy group, providing a reverse-lookup for understanding where permissions flow.

Individual Policy Editor

Accessed from the Attached Policies tab by selecting a policy and clicking Edit. The Visual Editor presents statement configuration in sections:

Statement Types — select one per statement block:

Actions (GraphQL): Create, Query, Update, Delete, Upsert. The Mutate action appears in this list but applies only to a narrow set of custom platform operations (user file upload, send system email) — use it only when specifically required for those operations.

Resources: Hierarchical tree organized by module group → module → individual resource → individual fields. Select at the module level for broad access or expand to the field level for precise field-level security.

Rules: Optional section for Transform Rules (JSONata), Allowed IPs, and Disallowed IPs. Transform rules are a complex advanced feature — use with caution and document thoroughly.

5. Technical Details

GraphQL Permission Rules

Mutations Require Query Permission: Any mutation action (Create, Update, Delete, Upsert) requires accompanying Query permission on the same resource. This is because the mutation returns the updated record as output — without Query permission, a mutation could be exploited to extract data the user is not supposed to see. If a user experiences unexpected save failures despite having mutation permission, check for a missing Query statement on the same resource.

The Mutate Action: The Mutate action visible in the GraphQL statement editor applies exclusively to a narrow set of custom platform-level operations such as user file upload and send system email. It does not apply to standard data model CRUD operations and cannot be used as a substitute for Create, Update, Delete, or Upsert. Ignore the Mutate action for standard data model work.

Field-Level Security

Field-level security enables administrators to control access to specific fields within a data model, providing granular data protection beyond model-level permissions.

How Field-Level Security Works:

• Configuration: When selecting a resource in the Visual Policy Builder, expand the resource node to reveal individual fields. Each field has its own checkbox.
• Field Selection: Check only the fields this policy should allow access to. Unselected fields will be denied based on the action configuration — users cannot read or write those fields through the API.
• Example Use Case: For the Product data model, restrict who can view product.cost or edit product.code while allowing broader access to other product fields such as name and description.
• API Layer Enforcement: Field-level security is enforced at the GraphQL API layer. The restriction applies regardless of how the API is accessed — through a Fuuz screen, the API Explorer, or an external API client.

UI Behavior with Field-Level Security:

• Screen Appearance: Fields restricted at the API layer may still appear editable on a Fuuz screen. The screen does not automatically hide or disable fields based on field-level security policies.
• API Enforcement: When the user attempts to save a record containing a restricted field, the GraphQL API rejects the request and returns a permissions error. The data is not saved.
• Best Practice: Configure screen element visibility settings (show/hide or enable/disable) to match the policy restrictions. This prevents users from attempting actions they are not permitted to complete and avoids confusing error messages at save time.
• Error Handling: Implement appropriate error messaging in screens to clearly inform users when they lack field-level permission, rather than displaying a generic save failure.

Web Flows vs. Backend Flows (Orchestration)

This distinction is critical and commonly misunderstood:

Web Flows: Run in the permission context of the user. No Orchestration execute permission is needed to trigger a web flow. However, any GraphQL actions performed within the web flow (queries, mutations) require the user to have the corresponding GraphQL permissions. If a web flow mutation step fails with a permission error, add the required GraphQL permission to the user's policy — or convert the step to call a backend flow.

Backend/System Flows: Permission is checked once at the start ("does this user have permission to execute this flow?"). If yes, everything the flow does internally runs without further user permission checks. This encapsulation enables the Custom API Pattern: create a backend flow that performs a privileged operation with built-in validation, grant users execute permission on that specific flow rather than broad GraphQL mutation rights, and the flow enforces all business rules. Users cannot bypass the flow's logic by calling the API directly.

WebSocket Permissions

Data-change subscriptions — the mechanism that makes screens update in real time when a queried record changes — are automatically permissioned by the GraphQL Query permission for the same resource. You do not need to configure a separate Websocket statement for standard real-time data updates. Configure Websocket statements explicitly only when using custom publish/subscribe topics beyond standard data change events.

Deny Statements

Any statement can be toggled from Grant to Deny. An explicit Deny takes precedence over any Grant from anywhere in the user's entire policy set. Use Deny statements deliberately. With Limited Web Access (the new default for new users), screen Deny statements are rarely needed — simply omit the screens you don't want the user to access.

Gateway User Permissions

Gateway users should always be assigned the Gateway access type — never Administrator. The Gateway access type grants the minimum permissions required to operate the Edge Gateway. If an API key associated with an administrator account is compromised, the attacker has full access to create, modify, or delete all data in the tenant. A gateway-scoped key limits the blast radius to only what that key is authorized to do.

To extend a gateway user's permissions beyond the baseline, create a targeted policy with the specific capability needed (e.g., an Orchestration statement granting execute permission on a specific backend flow). Attach this policy directly to the gateway user via the policy's Attached Users tab. Do not elevate the gateway user's access type to Administrator.

Naming Conventions

Name policies after what a user can do, not after a screen name or data model. Function-based naming makes policies reusable across roles and meaningful to administrators who are auditing or troubleshooting.

Access Type Defaults

Transform Rules

Transform Rules use JSONata expressions to conditionally apply or restrict a statement based on user attributes, request context, or data values. Use cases include filtering data by user's assigned warehouse, hiding ITAR-controlled records, and department-level data isolation.

Transform rules are a complex, advanced feature. The implementation is modeled after AWS IAM conditional policy logic. Use only when simpler permission structures cannot meet the requirement, document the logic thoroughly in the policy description, and test with representative user attribute sets before deploying.

IP Restrictions

IP restrictions control physical network access to Fuuz resources at the statement level. There are two distinct levels of IP restriction in the platform — understanding the difference is important for correct implementation.

Allowed IPs vs. Disallowed IPs within a policy statement:

• Allowed IPs (Whitelist): Only the listed IP addresses or CIDR ranges can access the resource. All other IPs are denied.
• Disallowed IPs (Blacklist): The listed IP addresses or CIDR ranges cannot access the resource. All other IPs are allowed.
• Both configured simultaneously: If an IP address appears in both lists (or falls in conflicting ranges), Disallowed takes precedence. Simplify configurations by using only one type where possible.
• Supported formats: Single IP addresses (e.g., 192.168.1.100) and CIDR ranges (e.g., 192.168.1.0/24).

When to use each level: Use Identity Provider IP restrictions when you want to block login entirely from unauthorized locations (e.g., prevent all access from outside the corporate network). Use policy-level IP restrictions when users need to authenticate from multiple locations but should only access specific resources from approved networks (e.g., shop floor operators can log in remotely to check schedules, but can only access production inventory data when connected from the plant floor network).

Transform Rule Configuration

Transform Rules use JSONata expressions evaluated at request time. The payload always includes user claims (user attributes and properties), the actionId (the GraphQL action being performed), and the resourceId (the resource being accessed).

/*
  Example: Filter inventory by user's assigned warehouse
*/
warehouseId = $user.assignedWarehouse

/*
  Example: Hide ITAR records from unauthorized users
*/
$user.itarCleared = true or itarControlled = false

/*
  Example: Show only records in user's department
*/
department = $user.department

Always test transform rule expressions thoroughly with representative user attribute sets before deploying to production. Document the logic in the policy description field — these expressions are difficult to debug without documentation.

Conflict Resolution

When a user has multiple policy groups with potentially conflicting statements, Fuuz applies the most restrictive rule: Deny overrides Grant, Disallowed IPs override Allowed IPs, field restrictions override field grants. No automatic conflict detection exists — administrators are responsible for auditing effective permissions.

Package Management & Portability

Policy groups and policies can be bundled into packages and deployed across environments (build → QA → production) as an application evolves.

• Create Packages: Bundle policy groups and their associated policies into deployable packages from the App Admin interface.
• Resource Dependency: Packages can only be imported into applications that have all of the same resources (data models, screens, flows) referenced in the policies. If the target environment is missing any referenced resource, the import will fail.
• Recommended sequence: Deploy application packages first (which create the data models, screens, and flows), then import permission packages.
• Manual recreation: Since policy groups cannot be cloned directly, manual recreation in the target environment requires: creating the policy group, then attaching the same set of policies. Individual policy JSON can be copied from the JSON tab in the policy editor as an alternative.

Policy Group Lifecycle Management

• Deletion: A policy group can only be deleted if it is not currently attached to any roles or users. Remove all attachments before attempting deletion.
• No native deactivation: Fuuz does not provide a deactivate or disable function for policy groups. To effectively retire a policy group, remove all role and user attachments — the group will then have no effect without being deleted.
• Modification impact: Changes to policies within a policy group take effect immediately for all users and roles that have the policy group attached. There is no staging or approval workflow for permission changes.
• Audit trail: The History tab on each policy group and individual policy records creation timestamp, creation user, last modified timestamp, and last modified user.

6. Resources

• Fuuz Industrial Operations Platform
• Related KB Article: Access Control Overview
• Related KB Article: Roles
• Related KB Article: Access Type Overview
• Related KB Article: App Users
• JSONata documentation: docs.jsonata.org — for writing Transform Rule expressions

7. Troubleshooting

Best Practices

• Name Policies After Job Functions: Use capability-based names ("Receive Inventory") rather than technical names ("InventoryModel_Update"). This keeps policies meaningful and reusable.
• Start with 1-to-1 Mapping: Begin with one policy group per role. Add complexity (superset pattern, multiple groups) only when the use case requires it.
• Always Pair Mutations with Query: Whenever you add a Create, Update, Delete, or Upsert statement, add a corresponding Query statement on the same resource.
• Use Limited Web Access for New Users: Avoids the need for Deny statements and results in a cleaner, more auditable permission structure.
• Use Backend Flows for Privileged Actions: When an operation requires validation or constraints the user should not be able to bypass, implement it as a backend flow and grant Orchestration execute permission rather than broad GraphQL mutation rights.
• Keep Gateway Users on Gateway Access Type: Never elevate a gateway user to Administrator access type. The least privilege principle minimizes the blast radius of any credential compromise.
• Keep Attached Users at Zero for Regular Policy Groups: The Attached Users count on a policy group should be 0 for all groups used by regular users — permissions should flow through roles. Non-zero counts should only appear for gateway/API-specific policies.
• Test Iteratively: Build the role and policy structure, then test the screen or flow, observe permission errors, add the missing permissions, and repeat. Do not attempt to pre-configure all permissions in one pass without testing.
• Avoid the "All Resources" Shortcut: Granting permission to all resources resolves permission errors quickly but creates excessive access. Always scope permissions to the minimum required resources.
• Document Transform Rules: If transform rules are used, document the logic, the user attributes they reference, and the expected behavior in the policy description field. These are difficult to debug without documentation.
• Review Access Types Before Go-Live: Check that developer and test users set to Administrator access type during development are reconfigured appropriately before handing off to customers.

8. Revision History