Article Type: Concept
Audience: Application Administrators, Solution Architects, Partners
Module: Fuuz Platform - Access Control
Applies to Versions: 2024.12+
Roles are the foundation of role-based access control (RBAC) in Fuuz, defining what users can see, access, and do within your application. Application Administrators create and manage roles that are unique to their specific Fuuz application and customer requirements. Roles serve multiple purposes including navigation control through role-based menus, data access restrictions, screen visibility, and even IP-based physical access controls. Each role can be associated with one or more Policy Groups that define granular permissions, and can have a default home screen that users are automatically navigated to when they activate that role. Users can be assigned multiple roles, with one designated as their default for initial login.
Note: Roles are application-specific and customer-unique. While some application accelerators and pre-built Fuuz applications may include starter roles, most organizations will customize or create roles specific to their operational needs. The role management process is evolving toward a more unified approach where roles and policies will be more tightly integrated.
Role: A named collection of permissions, menu configurations, and policy associations that define what a user can access and do within the Fuuz application.
Role-Based Access Control (RBAC): A security model where access decisions are based on the roles assigned to users rather than individual user permissions.
Policy Group: A collection of security policies that define data access controls, screen permissions, and other granular restrictions. Policy Groups are attached to roles to enforce these permissions.
Role-Based Menu: A navigation menu structure that appears in the Fuuz interface based on the user's assigned roles. Different roles can present different menu items and navigation paths.
Home Screen: The default screen or landing page that a user is automatically navigated to when they activate a specific role or log into the system with that role as their default.
Default Role: The primary role assigned to a user that determines their initial landing experience when logging into Fuuz.
Role Switching: The ability for users with multiple roles to switch between different roles during their session, automatically navigating to the new role's home screen and applying its permissions.
Attached Users: The count and list of users who have been assigned a specific role.
Application Accelerator: Pre-built Fuuz applications or templates developed by Fuuz or partners that may include starter role configurations.
Effective Permissions: The complete set of permissions a user receives when a role is assigned, derived from all policy groups attached to that role.
Roles Table: Master list displaying all roles with their descriptions, attached user counts, policy group counts, and configured home screens
Role Details Form: Multi-tab interface for configuring role properties, viewing attached users, and managing policy group associations
Menu Configuration: Visual editor for defining role-based menu items and navigation structure
Policy Group Associations: Interface for attaching one or more policy groups to a role
Effective Permissions Viewer: Visual and JSON-based display of all permissions granted by a role's associated policy groups
Attached Users List: Expandable view showing all users assigned to each role
Understanding how users, roles, policy groups, and policies connect is fundamental to configuring effective access control in Fuuz. The system uses a hierarchical relationship chain where each level builds upon the previous:
| Level | Entity | Purpose in Chain |
|---|---|---|
| 1 | User | Individual person with email, authentication credentials, and profile. Starting point for all access control. |
| 2 | Role | Organizational identity defining menu structure and aggregating policy groups. Users are assigned to Roles. |
| 3 | Policy Group | Container grouping one or more Policies together. Attached to Roles to provide flexible permission combinations. |
| 4 | Policy | Actual permission rules defining GRANT or DENY access to specific resources (screens, data models, orchestration, integrations). |
How the Chain Works:
User Assignment: Users are assigned to one or more Roles based on their job function and responsibilities.
Policy Group Attachment: Each Role has one or more Policy Groups attached to it, defining what users in that Role can access.
Policy Definition: Each Policy Group contains one or more Policies that specify exact permission rules for resources.
Permission Inheritance: When a user activates a Role, they inherit ALL permissions from ALL Policy Groups attached to that Role, and those permissions come from ALL Policies within those Policy Groups.
Important: This separation of concerns allows Policy Groups to be reused across multiple Roles, and Policies to be reused across multiple Policy Groups. For example, a "Warehouse Supervisor" Role and "Production Supervisor" Role might both attach the "Inventory Read Access" Policy Group, but only the Warehouse Supervisor attaches the "Inventory Write Access" Policy Group.
Roles in Fuuz can serve different purposes based on organizational needs:
| Role Purpose | Description | Example Roles |
|---|---|---|
| Navigational Only | Provides menu structure without enforcing data or screen access controls | Everyone, Basic User |
| Data Access Control | Restricts which data records users can view and modify through policy groups | Warehouse Manager, Production Supervisor |
| Screen Access Control | Defines which screens and features users can access within the application | Inventory Control, Maintenance Technician |
| IP-Based Restriction | Restricts physical access to Fuuz based on IP address or network location | Shop Floor Operator (facility-only), Remote Access |
| Mobile Access | Grants access to mobile menu actions with specific permissions | Mobile Auditor, Mobile Inventory, Mobile Shipping |
| Functional Role | Comprehensive role combining navigation, data access, and screen permissions for a job function | Training Coordinator, Receiving Supervisor, Dispatch Supervisor |
Note: Some roles provide purely navigational support with no access control, while others combine multiple control mechanisms. The flexibility allows organizations to design role structures that match their security and operational requirements.
Operational Role Segmentation: Create distinct roles for different operational functions such as Warehouse Manager, Production Supervisor, Quality Inspector, and Maintenance Technician, each with appropriate menu access and data visibility.
Multi-Facility Access Control: Design roles that restrict users to specific facilities or locations using IP-based policies, ensuring shop floor operators can only access systems from their designated work areas.
Mobile Workforce Enablement: Create mobile-specific roles that grant access to mobile menu actions and field-appropriate data, enabling technicians, auditors, and inspectors to work efficiently on mobile devices.
Training and Onboarding: Establish training-specific roles with limited permissions for new employees, allowing them to learn the system without affecting production data.
Context Switching: Enable power users with multiple responsibilities to switch between roles during their workday, automatically navigating to role-appropriate home screens (e.g., switching from Production Supervisor role to Quality Inspector role).
Departmental Segregation: Create role-based menus that present different navigation structures for different departments (Production, Warehouse, Maintenance, Quality) while sharing a common application.
Data Isolation: Use policy groups attached to roles to ensure users can only view and edit data relevant to their responsibilities, maintaining data security and reducing cognitive load.
Application Accelerator Deployment: Deploy pre-built Fuuz applications with starter roles, then customize them to match specific organizational workflows and security requirements.
/app/[tenant]/admin/access-control/roles
The main Roles page displays a comprehensive table with action buttons in the toolbar:
Toolbar Actions:
Add Role: Creates a new role with required name and optional description, home screen, and policy group associations
Edit Role: Opens the selected role's detail form for modification
Delete Role: Removes role from system (only available for roles that have never been used or assigned to users)
Table Columns:
| Column | Description |
|---|---|
| Name | The unique identifier for the role, displayed as a clickable link to the role detail form |
| Description | Brief explanation of the role's purpose and intended users |
| Attached Users | Count of users assigned to this role with expandable arrow to view user list |
| Attached Policy Groups | Count of policy groups associated with this role with expandable arrow to view policy group list |
| Home Screen | The default screen users are navigated to when this role is active (displayed as clickable link) |
Expandable Details: Clicking the arrow icon next to Attached Users or Attached Policy Groups expands an inline view showing complete list of user names and email addresses assigned to the role, or list of policy group names associated with the role.
Clicking a role name opens the detailed role configuration form with three primary tabs:
DETAILS Tab
The Details tab provides core role configuration including:
ID: System-generated unique identifier for the role (e.g., developerRole)
Name: Display name for the role shown to users and administrators
Home Screen: Dropdown selector to choose the default landing screen for users with this role
Description: Rich text editor for documenting the role's purpose, permissions, and intended use. This description helps administrators understand when to assign this role and what capabilities it provides.
Effective Permissions: Read-only visual display of all permissions granted to users through this role's attached policy groups
• VISUAL EDITOR: Graphical representation of permissions showing what users with this role can access
• JSON: Raw JSON policy statements showing allowed/denied actions and resources
Note: This is a summary view only - to change permissions, you must edit the attached policy groups directly.
Menu Configuration: Right-side panel showing role-based menu structure using a JSON editor with drag-and-drop capabilities
• Menu Icon: Visual icon selector using FontAwesome icon library - administrators can choose from any icon available in the FontAwesome collection
• Title: Display text for menu item
• Submenu Items: Hierarchical list showing menu structure (e.g., App Components → Application, Schema, Flows, Screens, Organization, Integrations, Menu Data)
• Path: Navigation path for each menu item using screen routes. Paths can include query strings and metadata in URLs. Roles can even navigate to screens outside of Fuuz by specifying external URLs.
CRITICAL: Always Use Relative URLs
When configuring menu paths, always use relative URLs that start with a forward slash. This ensures your role-based menus work correctly across all environments (build, QA, production) without requiring updates after migration.
Example - Correct Relative URL:
/inventory/management
/inventory/management?view=list (with query string)
Example - INCORRECT Absolute URL:
https://qa.customerapp.fuuz.app/inventory/management
How to Create Relative URLs: Navigate to the desired screen in your application, copy the URL from the browser address bar, and extract everything after the domain name including the leading forward slash. For example, from https://qa.customerapp.fuuz.app/inventory/management?view=list, extract /inventory/management?view=list
• Submenu Style: Choose between two display styles for child menu items:
| Style | Behavior |
|---|---|
| Submenu (Dropdown) | Child items appear in a dropdown list beneath the parent item when clicked. Use this for simple hierarchies where users need to see all options at once. |
| Group (Flyout) | Child items appear in a flyout panel to the right of the parent item when hovered or clicked. Use this for complex hierarchies with many items or multiple nesting levels. |
• Menu Data: The complete JSON object representing the menu structure, enabling copy and paste of menu configurations between roles for rapid deployment
History: Right-side panel showing audit trail with Created At timestamp, Created By User with email link, Updated At timestamp, and Updated By User with email link.
ATTACHED USERS Tab
This tab displays all users who have been assigned this role, providing searchable and filterable list of users with names and email addresses, ability to add or remove user assignments, and indication of whether this is each user's default role.
ATTACHED POLICY GROUPS Tab
This tab manages the policy groups associated with the role: list of attached policy groups, button to attach additional policy groups (policy groups must be created before they can be attached), ability to detach policy groups, and policy group descriptions and permission summaries.
Note: Policy groups are where actual data access controls and screen permissions are defined. Roles serve as containers that associate users with one or more policy groups. This separation allows policy groups to be reused across multiple roles. A role can function without any policy groups attached, but users assigned to that role will only receive navigational capabilities (if menu is defined) without any data or screen access permissions.
Understanding role creation, modification, and deletion constraints:
Role Deletion Constraints: Roles can only be deleted if they have never been used or assigned to any users. Fuuz does not have protected "system roles" - all roles are user-created and customer-specific. Access control at the system level is managed through Access Types (Application Administrator, Developer, Web Access) rather than roles. Once a role has been assigned to a user or used in any configuration, it cannot be deleted to preserve audit trails and data integrity. If a role is no longer needed but cannot be deleted, remove all user assignments and policy group associations to effectively disable it.
Role Deactivation: Currently, Fuuz does not provide a native "deactivate" or "disable" feature for roles. To effectively retire a role without deleting it: remove all user assignments from the role, detach all policy groups from the role, update the role description to indicate it is deprecated or retired, and consider prefixing the role name with "DEPRECATED" or "ARCHIVED" for clarity.
Role Cloning & Duplication: Fuuz does not include a native "clone role" feature, but administrators have alternative methods: view the role's JSON definition in the role details page, copy the entire JSON object, create a new role, and paste the JSON to duplicate the configuration. Use the "Menu Data" JSON object to copy menu configurations between roles. Organizations can develop custom data flows to automate role duplication if this becomes a frequent need. When cloning roles, remember to update the role name, ID, and description to avoid confusion.
CRITICAL SECURITY CONCEPT:
Role-based menus control navigation visibility but do NOT enforce actual permissions. Understanding this distinction is essential for secure access control configuration.
How Menu Visibility Works:
• Role-based menus determine which navigation links appear in the user's sidebar
• If a screen is not in a user's menu, they won't see the navigation link to reach it
• This provides a simplified, role-appropriate navigation experience
How Permission Enforcement Works:
• Permissions are defined in Policies, which are grouped in Policy Groups, which are attached to Roles
• Policies specify actual GRANT or DENY rules for screens, data models, orchestration, and integrations
• These permissions are enforced by the platform regardless of how users navigate
The Security Gap:
Users can potentially access screens via methods that bypass menu navigation:
• Direct URL Entry: Typing a screen's URL directly in the browser address bar
• Global Search: Using the platform's search bar to find and navigate to screens
• Bookmarks: Using saved browser bookmarks to screens from previous sessions
• Hyperlinks: Following links embedded in other screens or documents
If a user accesses a screen through any of these methods, their permissions from attached Policy Groups determine whether they can actually view and interact with that screen—not whether it appears in their menu.
Best Practice for Secure Configuration:
| Configuration Principle | Implementation |
|---|---|
| Alignment | If a screen appears in a Role's menu, ensure the attached Policy Groups GRANT access to that screen |
| Restriction | If a screen does NOT appear in a Role's menu, ensure the attached Policy Groups DENY access to that screen (or don't grant access) |
| Security First | Always configure Policies to provide actual security enforcement; menus should reflect permissions, not replace them |
| Testing | Test access by attempting direct URL navigation to verify Policy enforcement, not just menu visibility |
Example Scenario: A Warehouse Supervisor Role has "Inventory Management" in its menu and has a Policy Group that grants access to that screen (aligned and secure). However, "Financial Reports" is not in the menu but the Policy Group does not explicitly DENY access to it. A user could still access Financial Reports via direct URL or search. To properly secure this, add a DENY rule for Financial Reports screen in the Policy attached to the Warehouse Supervisor's Policy Group.
Roles and policy groups work together to provide comprehensive access control:
| Component | Purpose | Configuration Level |
|---|---|---|
| Role | Defines menu structure, home screen, and aggregates policy groups | High-level container |
| Policy Group | Defines granular data access controls and screen permissions | Detailed policy enforcement |
| User Assignment | Users are assigned to roles; roles aggregate policy groups | User-to-role mapping |
Current Architecture: Roles and policy groups are currently managed separately. Application Administrators create roles and then associate them with policy groups. The effective permissions a user receives are the cumulative result of all policy groups attached to all roles assigned to that user.
Future Evolution: The Fuuz platform is evolving toward a more unified approach where role creation and policy definition will be more tightly integrated, streamlining the administrative process.
When multiple policy groups are attached to a role, or when a user has multiple roles with different policy groups, potential conflicts may arise:
Administrator Responsibility: Conflict resolution is the responsibility of the Application Administrator. Since Fuuz applications are customized for specific use cases, the administrator must ensure there are no conflicting roles or policies granting users access to resources they should not have.
Validation Tools: Administrators can generate queries using the API Explorer and export results to external tools like Claude AI to validate and identify potential conflicts quickly.
Best Practice: Design clear role hierarchies and policy groups with distinct purposes to minimize the risk of conflicts. Thoroughly test role and policy combinations using dedicated test users before deploying to production users.
Important: The cumulative nature of permissions means users receive ALL permissions from ALL policy groups across ALL their assigned roles. If one policy group grants broad access, it can override more restrictive policies from other groups. Carefully review the effective permissions for each role to ensure appropriate access control.
Users can be assigned multiple roles to support various scenarios:
Default Role Assignment: One role must be designated as the user's default role. This determines which role is active when the user first logs into Fuuz, which home screen they are navigated to upon login, and which role-based menu structure they initially see.
Role Switching: Users with multiple roles can switch between them during their session. When switching roles, the system automatically navigates to the new role's home screen, the role-based menu updates to reflect the new role's navigation structure, and permissions from all assigned roles remain active (cumulative permissions).
Permission Accumulation: Users receive the cumulative permissions from all policy groups across all their assigned roles.
Important: Always designate one role as the default for each user. Without a default role, users may experience unpredictable login behavior or be navigated to an inappropriate starting screen.
Each role can have an associated home screen that serves as the landing page:
Purpose: Automatically navigate users to the most relevant starting point for their role and responsibilities
Configuration: Select from any screen configured in the application using the Home Screen dropdown
Role-Specific Navigation: Different roles can have different home screens (e.g., Production Supervisor → Work Order Production Status, Warehouse Manager → Inventory Management, Maintenance → Asset Details Form)
Context Awareness: Home screens should be chosen to match the primary workflow or most frequently accessed data for each role
Optional Configuration: Roles do not require a home screen assignment, though it is recommended for optimal user experience
Roles control which menu items appear in the Fuuz navigation interface:
Menu Configuration: Each role defines its menu structure including top-level items and submenu hierarchies
Visual Customization: Menu items can have custom icons, titles, and submenu styles (dropdown or group)
Path Definition: Each menu item specifies the navigation path to the target screen or feature
Conditional Display: Menu items only appear if the user has an active role that includes them in its menu configuration
Navigation Simplification: Role-based menus reduce complexity by showing only relevant navigation options for each user type
Pre-built Fuuz applications and templates may include starter roles:
Starter Roles: Pre-configured roles designed for common job functions in the application domain
Customization Required: These roles typically require customization to match specific organizational needs, workflows, and security requirements
Best Practice Template: Accelerator roles serve as examples and starting points, demonstrating recommended role structures
Policy Group Inclusion: Some accelerators include pre-defined policy groups that can be attached to roles
Modification Freedom: All accelerator roles can be freely modified, renamed, or deleted to suit customer requirements
Effective role names improve manageability and user understanding:
Job Function Based: Name roles after actual job functions (Warehouse Manager, Production Supervisor, Quality Inspector)
Department Based: Use department names for broader roles (Production, Warehouse, Maintenance, Quality)
Location Based: Include location identifiers for facility-specific roles (Plant1_Operator, Warehouse2_Manager)
Access Level Based: Indicate access level in role name (Operator_ReadOnly, Supervisor_FullAccess)
Avoid Ambiguity: Choose names that clearly communicate the role's purpose to both administrators and users
Proper testing of roles and RBAC configurations is critical before deploying to production users:
Recommended Testing Approach:
• Create dedicated test users: It is highly recommended to create separate user accounts specifically for testing RBAC configurations. These should be Web Access Type users with the roles you want to test.
• Test each role independently: Create a test user for each role to verify permissions, data access, screen visibility, and menu navigation work as expected
• Test multiple role combinations: If users will have multiple roles in production, create test users with those same combinations to verify cumulative permissions
• Login as test users: Log in as the test users (not just viewing as admin) to experience exactly what end users will see
Self-Assignment for Menu Testing:
• Quick menu validation: Application Administrators and Developers can assign roles to themselves for quick testing of menu navigation without needing to create test users
• Limited scope: This approach is suitable for verifying menu structure and navigation but not recommended for testing data access controls or comprehensive RBAC
• Remember to remove: After testing, remember to remove test role assignments from your admin/developer account
Moving roles between environments or tenants requires careful planning:
Package Management Method (Recommended): Use Fuuz's package management capabilities to bundle roles and policy groups together for migration between environments (build → qa → production). Benefits include maintaining relationships, including dependencies, and providing version control. Packages can include roles, policy groups, and related configurations in a single deployable unit.
JSON Copy/Paste Method: Copy the role's JSON object from the role details page and paste into a new role in the target environment. Similarly, use the Menu Data JSON object to quickly copy menu configurations between roles. Limitations include that policy group associations must be recreated manually and policy groups themselves must exist in target environment. Best for quick prototyping or when only moving menu configurations without full role structure.
Roles can be assigned to users from multiple locations within Fuuz:
From the Role Detail Form: Navigate to the role and open the ATTACHED USERS tab. Click the add/attach button to select users to assign this role. Useful when configuring a role and want to assign multiple users at once.
From the App Users Screen: Navigate to Access Control → App Users. Select and edit the user to open their detail form. Click the Roles tab. Click the plus (+) button to attach a new role to the user. Click the pencil icon to edit role settings (such as changing the default role designation). Select a role and click the trash icon to remove it from the user. Useful when managing a specific user and assigning multiple roles to them.
Related KB Article: Access Control Policies
Related KB Article: Access Control Policy Groups
Platform Information: Fuuz Industrial Operations Platform - www.fuuz.com
| Issue | Cause | Fix |
|---|---|---|
| User has role assigned but cannot access expected features | Role may not have appropriate policy groups attached, or policy groups lack necessary permissions | Review Attached Policy Groups tab and verify policy groups grant required data and screen access permissions |
| User sees no menu items after login | Role may not have menu configuration defined, or user has no roles assigned | Verify user has at least one role assigned; check role's menu configuration in Details tab using the JSON editor; ensure menu items are properly configured with paths |
| User redirected to wrong screen after login | Default role's home screen is incorrectly configured | Edit the default role and verify the Home Screen field points to the correct screen; ensure user's default role designation is correct |
| Role switching does not navigate to new home screen | Target role may not have a home screen configured | Edit the role and configure appropriate Home Screen in the Details tab |
| Cannot see which users have a specific role | User list is in collapsed state | Click the arrow icon next to the Attached Users count in the Roles table to expand the user list, or open the role detail form and view the ATTACHED USERS tab |
| Multiple roles assigned but user only sees one role's menu | Only active role's menu is displayed; cumulative menus not supported | This is expected behavior; users must switch between roles to see different menus. Consider consolidating menu items into a single role if users need access to all items simultaneously |
| Effective Permissions shows no permissions | No policy groups are attached to the role | Navigate to ATTACHED POLICY GROUPS tab and add appropriate policy groups to define permissions. Note that roles without policy groups can still provide menu navigation |
| Cannot delete role | Role has been previously used or assigned to users | Roles can only be deleted if they have never been used. Remove all user assignments and policy group attachments, then prefix the role name with "DEPRECATED" to indicate it's retired |
| Cannot edit Effective Permissions | Effective Permissions is a read-only summary view | To change permissions, navigate to the attached policy groups and edit their definitions directly. Effective Permissions automatically updates based on policy group changes |
| Need to clone a role but no clone button exists | Fuuz does not have native role cloning feature | Copy the role's JSON definition from the Details page, create a new role, paste the JSON, and update the role name and ID. Alternatively, use Menu Data JSON to copy menu configurations |
| User can access data they should not see despite correct role assignment | User may have multiple roles with cumulative permissions; one role may grant broader access | Review all roles assigned to the user and all policy groups attached to those roles. Use API Explorer to export permission analysis and validate with external tools. Remember that permissions are cumulative across all roles |
| Conflicting policies between role's policy groups | Multiple policy groups attached to role have contradictory rules | This is administrator's responsibility to resolve. Review all attached policy groups, use API Explorer to analyze conflicts, and restructure policy groups to eliminate contradictions. Test thoroughly with dedicated test users |
| Menu icons not displaying correctly | Invalid FontAwesome icon name or version incompatibility | Verify icon name is valid from FontAwesome library; check FontAwesome documentation for correct icon identifier format |
| External URL in menu path not working | URL may be malformed or browser blocking external navigation | Verify URL includes proper schema (https://); test URL directly in browser; check browser security settings |
| Version | Date | Editor | Description |
|---|---|---|---|
| 1.0 | 2024-12-26 | Craig Scott | Initial Release |
| 1.1 | 2025-01-06 | Ed Sosnowski | Enhanced with: Access Control Relationship Chain table, Sub-Menu vs Group distinction, Relative URL guidance, Menu vs. Permissions security section |