Policy Groups & Policies

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

1. Overview

Policy Groups and Policies form the granular access control layer in Fuuz, modeled after AWS Identity and Access Management (IAM) policy architecture. Individual Policies define permissions for single resources using visual builders or JSON definitions, supporting advanced field-level security, data transformation rules, and IP-based restrictions. Policy Groups aggregate these individual policies into functional collections that can be attached to roles or directly to API and Gateway access type users. This hierarchical structure (Policies → Policy Groups → Roles/Users) enables precise control over data access, screen visibility, and API operations while maintaining administrative flexibility and supporting complex security requirements.

2. Architecture & Data Flow

Definitions

• Policy: A single access control definition that grants or denies specific actions on a specific resource. Policies are the atomic unit of permission management in Fuuz.
• Policy Group: A named collection of individual policies that can be attached to roles or users, providing a logical grouping of related permissions.
• Resource: Any Fuuz entity that requires access control, including data models, screens, flows, integrations, or API endpoints.
• Action: An operation that can be performed on a resource, such as Create, Query, Update, Delete, Mutate, or Upsert.
• Field-Level Security: Granular permissions that control access to specific fields within a data model, enabling administrators to hide or restrict editing of individual attributes.
• Transform Rule: A JSONata expression that dynamically filters or transforms data based on user attributes, enabling context-aware access control.
• Allowed IPs: Whitelist of IP addresses or CIDR ranges from which users can access resources protected by the policy.
• Disallowed IPs: Blacklist of IP addresses or CIDR ranges from which users are explicitly denied access to resources.
• Visual Policy Builder: Point-and-click interface for constructing policies without writing JSON, providing resource trees, action checkboxes, and rule configuration.
• Effective Permissions: The cumulative set of permissions a user or role receives from all attached policy groups.
• GraphQL Summary: Notation showing the count of Actions, Resources, and Rules within a policy (e.g., "GraphQL: 1 Action, 13 Resources, 0 Rules").

Components

• Policy Groups Table: Master list of all policy groups with attached policies count, user count, and role count
• Policy Group Detail Form: Multi-tab interface for managing policy group properties, attached policies, users, and roles
• Visual Editor (Policy Group): Read-only cumulative view of all permissions granted by policies within the group
• Individual Policy Editor: Full-featured visual builder for creating and modifying single-resource policies
• Resource Tree: Hierarchical selector for choosing resources to apply policies to
• Action Checkboxes: Allow/Deny toggles for Create, Query, Update, Delete, Mutate, and Upsert operations
• Rules Configuration: Interface for defining Transform Rules, Allowed IPs, and Disallowed IPs
• JSON Editor: Alternative to visual builder for direct policy JSON manipulation

Policy Hierarchy & Flow

Fuuz implements a three-tier permission hierarchy:

1. Individual Policies (Tier 1): Atomic permission definitions for single resources. Policies ONLY exist within Policy Groups and cannot be attached directly to users or roles.
2. Policy Groups (Tier 2): Collections of related policies that provide functional permission sets. Policy Groups can be attached to:
   • Roles (which are then assigned to Web Access users)
   • API Access Type users directly
   • Gateway Access Type users directly
3. Roles or Direct User Assignment (Tier 3): The final attachment point where permissions become effective for end users.

3. Use Cases

• API User Provisioning: Attach policy groups directly to API Access Type users to grant them programmatic access to specific data models and operations without assigning roles.
• Gateway Data Access: Provision Gateway Access Type users with policy groups that define which data they can synchronize and transmit between on-premises systems and Fuuz cloud.
• Field-Level Data Masking: Restrict sensitive fields like product.cost or customer.creditCardNumber to specific roles while allowing broader access to other fields in the same data model.
• ITAR Compliance: Use Transform Rules to automatically hide ITAR-controlled records from users who lack the required security clearance attribute on their user record.
• Multi-Facility Restrictions: Create policies with Allowed IP rules to ensure warehouse operators can only access inventory data when connected from their facility's network.
• Read-Only Analytics Users: Build policy groups that grant Query permissions across multiple data models while explicitly denying Create, Update, and Delete operations.
• 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 data.
• External Partner Access: Create highly restrictive policy groups with IP whitelisting and limited resource access for external contractors or integration partners.
• Modular Permission Sets: Combine granular policies (InventoryModel_Query, OrderScreen_View, ShipmentFlow_Execute) into functional policy groups (WarehouseWorker, ShippingClerk) for easy role assignment.

4. Screen Details

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

Policy Groups Table

Toolbar Actions

• Add Policy Group: Creates new policy group requiring Name (required) and Description (optional)
• Edit Policy Group: Opens selected policy group's detail form
• Delete Policy Group: Removes policy group if not currently attached to any roles or users

Table Columns

Policy Group Detail Form

DETAILS Tab

• ID: System-generated unique identifier
• Name: Display name for the policy group
• Description: Detailed explanation of policy group purpose and contents
• Effective Permissions: Read-only visual display showing cumulative permissions from all attached policies
  • VISUAL EDITOR tab: Graphical representation with resource tree, actions, and rules
  • JSON tab: Complete JSON policy definition
  • Summary notation: "GraphQL: X Actions, Y Resources, Z Rules" showing totals across all policies
• History: Audit trail with Created At, Created By User, Updated At, Updated By User

ATTACHED USERS Tab

Displays and manages users who have this policy group directly attached:

• Typically API Access Type and Gateway Access Type users
• Ability to attach additional users
• Ability to detach users

ATTACHED POLICIES Tab

Interface for managing individual policies within the policy group:

• Add Button: Opens dropdown list of available policies to attach to this group
• Policy List: Shows all currently attached policies with their names and summaries
• Edit Policy: Opens individual policy editor for modification
• Detach Policy: Removes policy from this policy group
• Policy Summary: Each policy displays its GraphQL summary (e.g., "GraphQL: 1 Action, 13 Resources, 0 Rules")

ATTACHED ROLES Tab

Shows which roles include this policy group in their permission set.

5. Technical Details

Individual Policy Configuration

Individual policies are created and edited using the Visual Policy Builder, accessed by selecting "Edit" on a policy within the ATTACHED POLICIES tab.

Policy Editor Interface

• Policy Name: Identifier for the policy (see naming conventions below)
• Description: Explanation of policy purpose and scope
• VISUAL EDITOR Tab: Point-and-click interface for policy construction
• JSON Tab: Direct JSON policy definition editing
• ATTACHED USERS Tab: Shows users receiving this policy through policy group attachments
• ATTACHED GROUPS Tab: Shows which policy groups include this policy

Visual Policy Builder Components

1. Actions Section:

• Checkboxes for: All Actions, Create, Delete, Mutate, Query, Update, Upsert
• Default Mode: All actions are "Allow" by default when checked
• Deny Mode: Use the "Switch to deny permissions" checkbox in the summary header to explicitly deny selected actions instead
• Search field to filter available actions

2. Resources Section:

• Hierarchical Tree: Expandable tree showing all application resources organized by category:
  • All Resources (root)
  • Applications
  • Documentation
  • EIM (Equipment and Time Tracking)
  • Maintenance Management
  • Materials Management
  • Mobile
  • Production Management
  • Quality Control
  • And more...
• Parent Node Selection: Selecting a parent node automatically selects all child resources
• Individual Selection: Can also select individual child resources for precise control
• Search field to quickly locate specific resources
• Best Practice: Select only the single resource this policy should govern, even though the interface allows multiple selections

3. Rules Section:

• Transform Rules: JSONata expressions for dynamic data filtering
• Allowed IPs: Whitelist of IP addresses or CIDR ranges
• Disallowed IPs: Blacklist of IP addresses or CIDR ranges
• "Add a new rule" button to create additional rule configurations

Policy Configuration Tools

• Clone Button: Duplicates the current policy configuration within the same policy, useful for creating similar permission sets with slight variations
• Trash Icon: Deletes a specific configuration from the policy
• Allow/Deny Toggle: Checkmark in summary header switches between Allow and Deny modes for selected actions

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 policy builder, expand the resource node to see individual fields
• Field Selection: Choose specific fields to include in the policy. Unselected fields will be hidden or denied based on the action configuration.
• Example Use Case: For the Product data model, restrict who can edit product.code or view product.cost while allowing broader access to other fields
• API Layer Enforcement: Field-level security is enforced at the GraphQL API layer

UI Behavior with Field-Level Security

Important consideration: Fuuz screens do not automatically disable fields based on field-level security policies.

• Screen Appearance: Fields may appear editable on the screen even when the user lacks permission
• API Enforcement: When the user attempts to save, the GraphQL API will reject the request and return a permissions error
• Best Practice: Configure screen field visibility settings to match policy restrictions, providing better user experience and preventing confusion
• Error Handling: Implement appropriate error messaging in screens to inform users when they lack field-level permissions

Transform Rules

Transform Rules use JSONata expressions to dynamically filter or transform data based on user attributes, query context, or other runtime conditions. This enables sophisticated, context-aware access control beyond simple allow/deny permissions.

Transform Rule Use Cases

• ITAR Compliance: Hide records marked as ITAR-controlled from users who lack the required security clearance attribute on their user record
• Warehouse Filtering: Automatically restrict inventory queries to show only items in warehouses assigned to the user
• Department Isolation: Filter production data to show only records where record.department = user.department
• Type-Based Filtering: Show users only specific product types, order statuses, or category classifications based on their role attributes
• Geographic Restrictions: Limit data visibility to records associated with the user's assigned locations or regions
• Customer Segmentation: For partner portals, restrict data to records associated with the partner's customer accounts

JSONata Transform Syntax

Transform Rules are written using JSONata expressions that evaluate to filter criteria:

/*
    The payload for this transform is highly dependent on the context it is ran in.
    The payload will always include at least:
    - user's claims (user attributes and properties)
    - actionId (the GraphQL action being performed)
    - resourceId (the resource being accessed)
    
    For more help and examples please refer to the documentation for
    Access Control Policy Rules.
*/

/* 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

Transform Rule Configuration

• Add Transform Rules in the Rules section of the policy editor
• Write JSONata expressions that return boolean values or filter objects
• Test expressions thoroughly with representative user attributes and data
• Document complex transform rules in the policy description for maintainability

IP Restrictions

IP restrictions control physical network access to Fuuz resources, enabling administrators to restrict access based on user location or network connectivity.

IP Restriction Types

Allowed IPs vs Disallowed IPs

• Allowed IPs (Whitelist): Only specified IPs can access the resource. All other IPs are denied.
• Disallowed IPs (Blacklist): Specified IPs cannot access the resource. All other IPs are allowed.
• Both Allowed and Disallowed: Policies can include both lists simultaneously. If conflicts occur, the most restrictive rule wins (Disallowed takes precedence over Allowed).
• IP Format Support:
  • Single IP addresses: 192.168.1.100
  • CIDR ranges: 192.168.1.0/24
  • Multiple entries: List multiple IPs or ranges as needed

When to Use Each Level

• Use Identity Provider IP Restrictions When: You want to prevent login completely from unauthorized locations (e.g., block access from outside company network or specific countries). Configured by Enterprise Administrator in identity provider or SSO settings.
• Use Policy-Level IP Restrictions When: You want users to authenticate but restrict access to specific resources based on location (e.g., shop floor operators can access production screens only from facility network, but can still login remotely to view their schedule). Configured by Application Administrator in policies.

Policy Conflict Resolution

When users have multiple policy groups (through multiple roles or direct attachments), or when policy groups contain multiple policies, conflicts may arise.

Conflict Detection

• No Automatic Detection: Fuuz does not automatically detect or flag policy conflicts
• Administrator Responsibility: Application Administrators are responsible for identifying and resolving conflicts
• Validation Tools: Use external tools for conflict detection:
  • Export policy JSON from the JSON tab in policy editor
  • Use API Explorer to generate permission analysis queries
  • Send JSON definitions to LLM tools (Claude, ChatGPT) for conflict analysis
  • Request identification of conflicting rules, overlapping permissions, or security gaps

Conflict Resolution Rules

When conflicts remain after administrator review, Fuuz applies the most restrictive rule:

• Allow vs Deny: If one policy allows an action and another denies it, DENY wins
• IP Restrictions: If one policy has Allowed IPs and another has Disallowed IPs for the same address, Disallowed wins
• Field Access: If one policy grants field access and another restricts it, RESTRICTION wins
• Transform Rules: Multiple transform rules are evaluated with AND logic (all must pass)

Policy Naming Conventions

Well-structured policy names improve discoverability, maintainability, and understanding of permission structures.

Recommended Format

Pattern: Resource - Actions - Rules

Example Policy Names

• Product_CreateUpdate - Allows creating and updating products
• Inventory_Query_IPRestricted - Read-only inventory access with IP whitelist
• OrderScreen_All - Full access to order management screen
• ShipmentFlow_Execute - Permission to run shipment workflow
• Customer_Query_PartnerFiltered - Read customer data with partner-specific transform rule

Policy Group Naming

Policy group names should reflect functional requirements or business use cases that make sense for your organization:

• User-specific: User without Flow Deployment, Limited Customer User
• Function-based: Warehouse Operations, Production Scheduling
• Role-aligned: Material Request User, Penn Engineering
• System-specific: MES Employee Administration, Supplier Portal

Package Management & Portability

Moving policy groups and policies between environments requires careful planning due to resource dependencies.

Package Import/Export

• Create Packages: Bundle policy groups and their associated policies into deployable packages
• Resource Dependency: Packages can only be imported into applications that have ALL the same resources referenced in the policies
• Use Case: Deploy permission structures from build to qa to production as application evolves
• Limitation: If target environment lacks resources (data models, screens) referenced in policies, import will fail

Manual Policy Group Recreation

Since policy groups cannot be cloned directly:

• Create new policy group in target environment
• Attach the same set of policies to the new policy group
• Ensure all referenced policies already exist in target environment
• Alternatively, use JSON copy/paste for individual policies if needed

Policy Group Lifecycle Management

• Deletion: Policy groups can only be deleted if not attached to any roles or users
• No Deactivation: Fuuz does not provide native policy group deactivation; remove all attachments to effectively retire a policy group
• Modification Impact: Changes to policies within a policy group immediately affect all users and roles that have the policy group attached
• Audit Trail: History tab tracks creation and modification timestamps and users

6. Resources

• Fuuz Industrial Operations Platform

7. Troubleshooting

• Issue: User has policy group attached but cannot access resources • Cause: Policy group may not contain policies granting required permissions, or policies have Deny rules • Fix: Review policies in ATTACHED POLICIES tab; verify actions are allowed; check for Deny configurations; review transform rules and IP restrictions
• Issue: Cannot edit permissions in policy group visual editor • Cause: Policy group visual editor is read-only by design • Fix: Navigate to ATTACHED POLICIES tab, select the policy to edit, and modify the individual policy directly
• Issue: Field appears editable on screen but save fails with permission error • Cause: Field-level security enforced at API layer; screen field visibility not configured • Fix: Update screen configuration to hide or disable fields that match policy restrictions
• Issue: Transform rule not filtering data as expected • Cause: JSONata expression syntax error or incorrect user attribute reference • Fix: Test JSONata expression with sample data; verify user attributes are correctly named; check API Explorer for actual user claims
• Issue: User can login but gets permission errors on all operations • Cause: Policy-level IP restriction blocking user's current IP address • Fix: Review Allowed IPs and Disallowed IPs in policies; verify user is connecting from permitted network; temporarily remove IP restrictions to test
• Issue: Cannot delete policy group • Cause: Policy group is attached to roles or users • Fix: Navigate to ATTACHED ROLES and ATTACHED USERS tabs; remove all attachments before deleting
• Issue: Cannot import policy package • Cause: Target environment missing resources referenced in policies • Fix: Ensure all data models, screens, flows referenced in policies exist in target environment before importing package
• Issue: Conflicting permissions between policy groups • Cause: User has multiple policy groups with contradictory rules • Fix: Export policy JSON from all affected policy groups; use LLM tool to analyze conflicts; restructure policies to eliminate contradictions; remember most restrictive rule wins
• Issue: Cannot attach policy to policy group • Cause: Policy may already be attached or policy does not exist • Fix: Check ATTACHED POLICIES list for duplicate; verify policy exists in system; create policy if needed before attaching
• Issue: API user has no data access despite policy group assignment • Cause: Policy group may be attached to user's role rather than directly to user; API users require direct policy group attachment • Fix: Attach policy group directly to the API Access Type user in ATTACHED USERS tab of policy group
• Issue: Parent resource selection not selecting all children • Cause: Some child resources may be explicitly excluded • Fix: Manually expand parent node and verify all child checkboxes are selected; re-select parent to refresh selection
• Issue: Allowed IPs and Disallowed IPs both configured - unclear which wins • Cause: Overlapping or conflicting IP rules • Fix: Most restrictive rule wins - Disallowed IP takes precedence over Allowed IP. Simplify configuration by using only one type when possible.

8. Revision History