Express Role-Based Access Control (RBAC) Overview

Role-Based Access Control (RBAC) in Unqork lets Creators control who can access applications and what end-users can see or do in them. RBAC operates at three levels: Environment, Module, and Component. Each serves a distinct role in the permission hierarchy.

The Three Levels of RBAC

Unqork's Express RBAC operates at three distinct levels, each serving a different purpose:

Permission Hierarchy: Component-level permissions override Module defaults, which in turn inherit from Environment role settings.

Level 1: Environment-Level Permissions

Environment-level RBAC determines who can log in and what their default permissions are across all applications in an environment. This is managed through Express Roles and Groups.

Express Roles

Express Roles are platform-wide end-user roles that define baseline access to applications. They serve as the foundation for all permission decisions.

Express Roles are configured in the Express Role Administration page.

Key Characteristics:

• Default Permission: Each role has a baseline permission level (none, read, or write) that applies to all modules unless overridden at the module or component level.

• Role Hierarchy: Roles can inherit from parent roles, creating a permission tree (for example, "Administrator" inherits all permissions from "Standard User").

• Super User Flags: Special flags grant elevated privileges:

  • Designer Access Super User: Lets Creators create and edit applications in Module Builder.

  • Submission Access Super User: Lets end-users view all submissions regardless of RBAC rules.

Common Role Examples:

How End-Users Get Roles:

End-users are assigned one or more Express Roles by an Environment Administrator. When an end-user has multiple roles, the highest permission level from any role applies.

Groups

Groups are collections of end-users that can be assigned roles collectively. Instead of assigning roles to individual end-users, roles can be assigned to a group and all members inherit those roles.

Groups are configured in the Express Group Administration page.

Key Characteristics:

• Group Membership: End-users can belong to multiple groups (for example, "Finance Team", "Regional Managers").

• Role Assignment: Roles can be assigned to groups, and all group members receive those roles.

• Centralized Management: Updating a group's roles automatically updates permissions for all members.

Common Group Examples:

How Roles and Groups Work Together:

1. Groups are assigned Express Roles: A group like "Finance Team" might be assigned the "Finance User" role.

2. End-users join Groups: When an end-user is added to "Finance Team", they automatically receive the "Finance User" role.

3. Permissions cascade: The end-user's effective permissions are the highest permission from all roles across all groups they belong to, plus any individually assigned roles.

Example:

• End-user: Sarah

• Groups: "Finance Team" (assigned role: "Finance User" with read default), "Approvers" (assigned role: "Approver" with write default)

• Individual Roles: None

• Effective Permission: Write (highest of read and write)

Who Manages Environment-Level Permissions:

Environment Administrators configure Express Roles and Groups through the Express Role Administration and Express Group Administration pages (Administration > Express Permissions). Application builders reference these roles when setting module and component permissions, but do not create or assign them.

Application Entry-Point RBAC

In addition to environment-wide Express Roles, Administrators can assign a specific role to an individual end-user for a specific application. The assigned role overrides that end-user's default Express Role, but only for that application's entry-point module.

Security limitation: Application Entry-Point RBAC does not protect sub-modules. End-users can navigate directly to a sub-module URL and bypass this restriction. To restrict access to sub-modules, configure RBAC at the module level or component level for each sub-module.

Configure Application Entry-Point roles in Express User Administration. For full details, see Environment-Level RBAC.

When to Use Environment-Level Permissions

Use environment-level permissions when:

• Establishing default permissions across all applications in the environment.

• Managing end-user access centrally instead of on a per-application basis.

• Creating a role hierarchy that reflects the organizational structure (for example, Manager inherits from Employee).

Level 2: Module-Level Permissions

Module-level RBAC sets default permissions for all components in a module. This is the most efficient way to secure entire workflows.

Module-level RBAC uses four permission levels:

Note: Obfuscate is not available at the module level; it is a component-only permission.

When an end-user has multiple roles, the highest permission level from any role applies.

Enabling RBAC on a Module

Step 1: Open Module Permissions

1. Open the module in Module Builder.

2. Click the Module Settings tab.

3. Navigate to the Module Permissions section.

Step 2: Customize RBAC

• Toggle Customize RBAC for This Module to ON.

• When enabled, all components inherit module-level permissions.

Step 3: Configure Role Permissions

The Permissions table displays four columns:

• Role (Express): Each Express Role in the environment, shown in a hierarchy  roles have parent roles.

• Permission: Drop-down to select the permission level for this role (Write, Read, or None).

• Effective Permission: The computed permission after evaluating role defaults and inheritance.

• Inherited From: Displays where the permission comes from (for example, "Role Defaults" if using the role's default permission).

Set the default permission level for each role using the Permission drop-down.

Click Save.

Step 4: (Optional) Allow Anonymous Access

• Toggle Allow Access to Anonymous Users to ON if unauthenticated end-users should access this module.

• When enabled, specific permissions can be configured for the Anonymous role in the permissions table.

• Note: This toggle only displays when Customize RBAC for This Module is enabled.

When to Use Module-Level Permissions

Use module-level permissions when:

• All fields in the module should have the same access rules.

• You want a quick, module-wide security baseline.

• You plan to override only a few specific fields at the component level.

Level 3: Component-Level Permissions

Component-level RBAC provides fine-grained control over individual fields. These permissions override module defaults.

Component-level RBAC uses five permission levels:

Permission Hierarchy: Write > Read > Obfuscate > None

Inherit is a special value that means "use the parent component's permission, or the role's default permission." When set to Inherit, the value "inherit" is stored in the component schema.

When an end-user has multiple roles, the highest permission level from any role applies.

Configuring Component Permissions

Step 1: Select the Component

1. In Module Builder, click the component to configure.

2. The configuration panel opens on the right.

Step 2: Open the Permissions Tab

• Navigate to the Permissions tab in the component configuration panel.

Step 3: Set Role-Specific Permissions

The Permissions table displays four columns:

• Role (Express): Each Express Role in the environment.

• Permission: Drop-down to select the permission level (Inherit, None, Read, Write, or Obfuscate).

• Effective Permission: The computed permission for this component after evaluating inheritance.

• Inherited From: Displays the source: "Role Defaults" (inherited from the role default) or "Component: {type}" (inherited from an ancestor component).

Set the permission level for each role using the Permission drop-down.

Click Done to save.

When to Use Component-Level Permissions

Use component-level permissions when:

• Certain fields contain sensitive data (PII, financial info).

• Different roles need different access to specific fields.

• You want to display a field but hide its value (obfuscate).

How Permissions Are Resolved

When an end-user opens a module, Unqork evaluates permissions in this order:

1. End-user's Express Roles: Determines which roles apply to the end-user.

2. Highest Role Permission: If an end-user has multiple roles, the highest permission wins.

3. Component Override Check: If the component has explicit permissions set, they override module defaults.

4. Module Default: If no component override exists, the module's permission for that role applies.

5. Role Default: If neither component nor module sets a permission, the role's default permission applies.

Example:

• End-user: Jane (Roles: Administrator, Claims Reviewer).

• Module Default: Administrator: Write, Claims Reviewer: Read.

• Component Override (SSN field): Administrator: Write, Claims Reviewer: Obfuscate.

Result:

• On most fields: Jane has Write (highest of Write vs. Read).

• On SSN field: Jane has Write (component override applies, highest of Write vs. Obfuscate).

Testing Your Permissions

Testing ensures that effective permissions match the intended design across all roles. Start with the most restricted roles and work up.

Testing Different Roles

To test how the module displays to different roles:

1. Create test accounts with different role assignments.

2. Log in as each test account to verify the module displays correctly for that role.

3. Verify that fields with different permissions (Read, Write, Obfuscate, None) behave as expected.

Tip: Test every role to ensure fields display, hide, and behave as expected. Pay special attention to obfuscated fields to confirm values are masked correctly.

Common Issues

Issue: All fields are visible to all end-users.

Solution:

• Verify Customize RBAC for This Module is toggled ON in the User Permissions section under Settings.

• Confirm that module-level or component-level permissions are configured.

Issue: A field is hidden when it should be visible.

Solution:

• Check the component's Permissions tab; it might have an explicit None permission overriding the module default.

• Verify the end-user has been assigned the correct Express Role in User Management.

Issue: End-user can see obfuscated data in the browser console.

Solution:

• Obfuscation replaces the actual value with ******** server-side before sending data to the client. The end-user cannot retrieve the original value, even through DevTools. If the real value displays in the browser console, verify that the component permission is set to Obfuscate (not just Read).

Best Practices

The following practices help maintain a secure, maintainable permission structure across modules and roles.

1. Begin with Module Defaults

• Set module-level permissions first to establish a baseline.

• Override at the component level only for exceptions.

2. Use the Principle of Least Privilege

• Grant the minimum permission required for each role.

• Default to None or Read for most users; grant Write only when necessary.

3. Document Role Definitions

• Maintain a role matrix documenting which roles can access which modules and fields.

• Share this with stakeholders before building the application.

4. Test with Real User Accounts

• Preview mode is helpful, but create test accounts with actual role assignments.

• Test end-to-end workflows to catch permission gaps.

5. Avoid Over-Obfuscating

• Obfuscation is useful for sensitive data, but overuse degrades end-user experience.

• If a field should be hidden, use None instead of Obfuscate.

6. Audit Permissions Regularly

• Review permissions when roles change or new regulations are introduced.

• Use the Permissions Summary report (if available in the environment) to spot gaps.