Component-Level Role-Based Access Control (RBAC)

Component-level RBAC provides fine-grained control over individual fields and components in a module. It lets Creators override module-level defaults and set specific permissions for sensitive data, different role types, or specialized workflows.

How Component-Level RBAC Works

When a permission is set explicitly on a component, it takes precedence over all inherited values. The sections below explain how this override behavior works and how permissions propagate through nested component trees.

Permission Override Behavior

When a permission is set on a component:

1. Explicit permission: The component uses the explicitly set permission.
2. Module override ignored: Module-level settings do not apply to this component.
3. Role default ignored: Environment-level defaults do not apply to this component.
4. Highest permission wins: If an end-user has multiple roles, the highest permission applies.

Nested Components

For components inside containers (panels, grids, repeaters):

TextField (child)
  └── Column (parent)
       └── DataGrid (grandparent)
            └── Panel (great-grandparent)
                 └── Module (root)

Permission walkup:

1. If the TextField has an explicit permission, that permission applies.
2. If not, the system checks the Column's permission.
3. If not, the system checks the DataGrid's permission.
4. If not, the system checks the Panel's permission.
5. If not, the system checks the Module's permission.
6. If not, the role default applies.

The system walks up the component tree until it finds the first explicit permission.

Component Permission Options

Component-level RBAC offers five permission options, including one unique to components:

The Inherit Permission

When a component's permission is set to Inherit, the system walks up the component tree looking for the first explicit permission:

1. If a parent or ancestor component has an explicit permission set, that permission applies.
2. If no ancestor has an explicit permission, the role's default permission from environment settings applies.
3. If none of the above are set, the system defaults to None.

Storage: When set to Inherit, the permission is stored as the literal value "inherit" in the component schema.

The Obfuscate Permission

Obfuscate is a unique permission option available only at the component level.

How it works:

• The field is delivered when requested by the API.
• The system replaces the value with asterisks (********) before sending to the client.
• End-users cannot write to the field.
• End-users cannot inspect the real value through browser DevTools.

When to use:

• Social Security numbers, where the field is visible but the value is hidden.
• Credit card numbers visible only to billing administrators.
• Salary information visible to HR but hidden from other roles.
• Internal reference IDs that end-users should know exist but cannot copy.

Example:

• Role: Standard User
• Permission: Obfuscate
• User sees: SSN: ********; the end-user cannot edit the field or see the real value.

Configuring Component Permissions

Component permissions are configured at the component level, but they depend on a module-level setting. Customize RBAC for This Module, found in User Permissions under Settings, must be enabled before component permissions take effect. See Module-Level Role-Based Access Control (RBAC) to enable it.

1. Open the module in Module Builder.
2. Click the component to configure. The settings panel opens on the right.
3. In the settings panel, select and select Permissions.
4. For each Express Role, select a permission from the Permission drop-down:
   • Inherit: Use parent, module, or role default.
   • No Access: Block access completely.
   • Read-Only: View only; the end-user cannot edit.
   • Write: Full access to view and edit.
   • Obfuscate: Mask value with asterisks.
5. Review the Effective Permission column to verify the computed result.
6. Click Save.

Note: If Customize RBAC for This Module is OFF, component permissions are ignored.

Permission Inheritance Examples

The following examples show how the Inherited From column reflects the source of the computed permission.

Example 1: Component Inherits from Module

Module Configuration:

• Customize RBAC: ON
• Standard User Permission: Read-Only

Component Configuration:

• Standard User Permission: Inherit

Result:

• Component inherits Read-Only from the role's default permission.
• Inherited From: Role Defaults

Example 2: Component Overrides Module

Module Configuration:

• Customize RBAC: ON
• Standard User Permission: Read-Only

Component Configuration:

• Standard User Permission: Write

Result:

• Component uses Write, overriding the module default.
• Inherited From: blank (the component has an explicit permission set).

Example 3: Nested Component Inherits from Parent

Module Configuration:

• Customize RBAC: ON
• Standard User Permission: Read-Only

Panel Configuration:

• Standard User Permission: Write

TextField inside Panel Configuration:

• Standard User Permission: Inherit

Result:

• TextField inherits Write permission from the Panel.
• Inherited From: "Component: panel"

Example 4: Obfuscated Field

Module Configuration:

• Customize RBAC: ON
• Standard User Permission: Write

SSN TextField Configuration:

• Standard User Permission: Obfuscate

Result:

• Standard User sees ******** instead of the actual SSN.
• The end-user cannot edit the field.
• Inherited From: blank (the component has an explicit permission set).

Special Cases

The following component types and role configurations have behaviors that differ from the standard permission model.

Complex Component Types

Certain component types receive special permission handling:

DataGrids and Repeaters

• Child components like columns and rows can have their own permissions.
• If a column has Inherit, it walks up to the grid, then module, then role default.
• If a column has an explicit permission, it overrides the grid's permission.

SelectBoxes with Promote to Top Level

When promoteDataToTopLevel is enabled:

• Creates separate fields for each checkbox value.
• Each inherits permissions from the parent component.
• Additional fields created: noneValue, otherValue, otherTextboxKey.

DataViewer with Yes/No

When displayYesNo is enabled:

• Creates field {key}Questions with parent permissions.
• Creates field qid with merged permissions from all Yes/No ADG components.
• Uses the highest permission level across all instances.

When to Use Component-Level RBAC

Component-level RBAC is most effective when specific fields need tighter or looser permissions than the module default, or when sensitive data must be visible but protected. The following scenarios illustrate where component-level control adds the most value.

Certain Fields Contain Sensitive Data

Set stricter permissions on fields containing PII, financial info, or confidential data.

Example: In an employee profile module, set SSN and salary fields to Obfuscate for Standard Users while allowing Write for HR Managers.

Different Roles Need Different Field Access

Override module defaults for specific roles that need different permissions on certain fields.

Example: A claims module where Claims Adjusters can edit all fields (Write), but Claims Reviewers can only view claim amounts (Read-Only on specific fields).

Showing a Field While Hiding Its Value

Use the Obfuscate permission to indicate a field exists without revealing its value.

Example: Credit card number visible to billing admins (Write) but masked for customer service (Obfuscate).

Progressive Disclosure Is Required

Show different levels of detail based on end-user role by setting component-level permissions.

Example: Basic Users see summary fields (Read-Only), Advanced Users see detailed fields (Write), Auditors see all fields (Write).

Module Defaults Are Too Permissive

If module-level RBAC grants Write to most roles, restrict sensitive fields with component-level permissions.

Example: Module-level RBAC sets Write for Authenticated end-users, but payment info components are restricted to Read-Only for non-finance roles.

Effective Permissions Display

The Effective Permission column shows the final computed permission after evaluating the entire inheritance chain.

Computation:

1. If the component has an explicit permission, the component permission applies.
2. If not, and the module has an explicit permission, the module permission applies.
3. If not, and the role has a default permission, the role default applies.
4. If none of the above are set, None applies.

Special cases:

• Admin roles always show Write.
• The NoAccess role always shows No Access.
• When an end-user has multiple roles, the highest permission applies.

Inherited From Column

Shows the source of the effective permission:

Use this column to understand why a component has a certain permission.

Permission Storage

Component permissions are stored in the component's schema:

{
  "key": "ssnField",
  "type": "textfield",
  "label": "Social Security Number",
  "permissions": {
    "Administrator": "write",
    "Standard User": "obfuscate",
    "Viewer": "no-access"
  }
}

key Fields:

• permissions: Map of role names to permission values. The system stores this in the database. No Access is stored as "no-access", Inherit is stored as "inherit".
• effectivePermissions: Computed client-side at runtime by the permissions panel. Not stored in the database.

Best Practices

The following practices keep component permissions manageable and reduce the risk of unintended access.

1. Override Only When Necessary

• Begin with module defaults.
• Only set component permissions when different behavior is needed.
• Avoid over-configuring permissions on every field.

2. Use Obfuscate for Sensitive Data

• Prefer Obfuscate over No Access for fields that should be acknowledged but not revealed.
• Use No Access when the field should be completely hidden.
• Document which fields are obfuscated and why.

3. Test with Multiple Roles

• Use Preview mode's role selector to test each role.
• Verify obfuscated fields display asterisks.
• Check that read-only fields cannot be edited.
• Verify No Access fields are not visible.

4. Check the Inherited From Column

• Before setting a component permission, check the source of its inherited permission.
• If the inherited permission is correct, leave it as Inherit.
• Only override when the inherited permission is incorrect.

5. Document Complex Permission Logic

• Add comments in Module Builder explaining why certain components have specific permissions.
• Maintain a permission matrix for complex modules.
• Share with stakeholders for review.

6. Avoid Data Model Binding Conflicts

• If using data models, manage permissions at the data model level.
• Do not attempt to override permissions on bound components.
• Use the link in the warning message to navigate to the data model.

Permission Merging for Nested Components

When the same field displays in multiple contexts, like a column in multiple grids, the system merges permissions by using the highest permission level.

Hierarchy:

write (highest) > read > obfuscate > none (lowest)

Example:

A column "name" displays in:

• DataGrid1: Manager role has Read.
• DataGrid2: Manager role has Write.
• DataGrid3: Manager role has Read.

Result: Field "name" gets Write permission for Manager (the highest level).