Environment-Level Role-Based Access Control (RBAC) - Unqork

Environment-level RBAC controls who accesses Express applications (the end-user facing modules and workflows built in Unqork) and what their baseline permissions are. This is separate from Creator roles, which control access to Module Builder. This article covers managing Express Roles and Express Groups.

Environment-level RBAC consists of the following core concepts:

Permission Requirement: Managing roles and groups requires Creator permissions to access the Express Role Administration and Express Group Administration pages.

Express Roles

Express Roles are platform-wide roles that define what end-users can see and do when accessing applications. These control Express application permissions, not Module Builder access.

Role Properties

Each Express Role has the following properties:

Role Hierarchy

Roles can inherit from parent roles, creating a permission tree:

• A child role inherits the parent's default permission as a baseline.
• Child roles can have more restrictive permissions than their parent.
• Role hierarchy is visualized in the View Role Hierarchy dialog.
• Parent roles are bolded; children are indented.

Example Hierarchy:

Administrator (Write)
  └── Standard User (Read)
      └── Claims Adjuster (Write)
      └── Claims Reviewer (Read)
  └── Viewer (Read)
      └── External Auditor (Read)

Default Roles (Protected)

The following roles are system defaults and cannot be deleted. Their parent, default permission, and super user flags are locked:

• Administrator: Full access to all applications and data.
• Authenticated: Base role for logged-in end-users.
• NoAccess: No permissions (used to explicitly deny access).
• Anonymous: Unauthenticated end-users (if anonymous access is enabled).

Managing Express Roles

Viewing Existing Roles

Navigate to Express Role Administration in the Unqork IDE.

1. The role list displays:
   • Role: The unique role identifier.
   • Description: Purpose of the role.
   • Permission: Badge showing permission level:
     • Red: No Access.
     • Amber: Read-Only.
     • Green: Write.
   • Actions: Drop-down with Edit and Delete options.
2. Use the search bar to filter roles by name or description.
3. Pagination controls display at the bottom (default: 10 roles per page).

Creating a Role

Navigate to Express Role Administration.

1. Click Add Role.

2. Fill in the form:

   Role Name (required)

   • Alphanumeric characters and hyphens only.
   • Cannot begin with a hyphen.
   • Maximum 255 characters.
   • Must be unique.

   Role Description (optional)

   • Explain the role's purpose and who should be assigned to it.

   Select Parent (optional)

   • Select a parent role from the drop-down.
   • This role inherits the parent's baseline permissions.

   Select Default Permission (required)

   • Select No Access, Read-Only, or Write.
   • This permission applies to all modules unless overridden at the module or component level.
   • When Full Submission Access is enabled, this field is automatically set to Write and cannot be changed.

   Full Submission Access (optional)

   • When checked, end-users can view all submissions regardless of RBAC rules.
   • An alert warns that this setting grants unrestricted read/write access to all submissions, overriding role hierarchy, group membership, and field-level permissions. Use sparingly, typically for administrators and auditors only.

   Designer Access (Super-user) (optional)

   • When checked, end-users can create and edit applications in Module Builder.
   • Only visible in edit mode and only for roles that already have Designer Access enabled.
   • Deprecated. Administrators can retire the option environment-wide from Environment Administration.

   Add to Group(s) (optional)

   • Select one or more groups to assign to this role.
   • Multi-select combobox (type to search).

3. Click Add Role.

Editing a Role

Navigate to Express Role Administration.

1. Find the role in the list.

2. Select for the role and select Edit.

3. Update the editable fields:

   Editable:

   • Role Description.
   • Select Parent (unless the role is a default role).
   • Select Default Permission (unless the role is a default role).
   • Full Submission Access (unless the role is a default role).
   • Designer Access (Super-user) (deprecated; only shown if the role already has Designer Access enabled, and only while the environment still offers the option — see Environment Administration).
   • Group assignments.

   Read-Only:

   • Role Name (cannot be changed after creation).

4. Click Save Changes.

Note: Default roles (Administrator, Authenticated, NoAccess, Anonymous) have their parent, default permission, and super user flags locked.

Deleting a Role

Navigate to Express Role Administration.

1. Find the role in the list.
2. Select for the role and select Delete.
3. Confirm deletion in the dialog that displays.

Restrictions:

• Cannot delete default roles (Administrator, Authenticated, NoAccess, Anonymous).
• Cannot delete roles currently assigned to end-users (backend validation prevents this).
• Deletion is permanent: the role must be recreated from scratch if needed.

Promoting Roles

Promotion copies roles from the current environment to a target environment (for example, Dev → QA → Production).

Navigate to Express Role Administration.

1. Select the More actions button in the top toolbar and select Promote Roles.
2. The Promote Roles dialog opens:
   • All roles are selected by default.
   • Use Select All / Deselect All buttons to manage selection.
   • Check/uncheck individual roles to include or exclude them.
3. Select the target environment from the drop-down.
   • Shows client name and level (for example, "Acme Corp - Production").
4. Click Promote.

Result: Selected roles are copied to the target environment with all properties preserved.

Viewing Role Hierarchy

Navigate to Express Role Administration.

1. Select View Role Hierarchy in the top toolbar.
2. The Role Hierarchy dialog opens:
   • Parent roles in bold.
   • Child roles indented beneath their parent, joined to it by a guide line.
   • Default permission badge for each role.
   • Every role appears, including roles with no parent and no children.
   • Select a parent role to collapse or expand its children.

Use Case: Understand permission inheritance and visualize role relationships before making changes.

Express Groups

Express Groups define data access rules between end-users based on role hierarchy. Groups control whether end-users can access each other's submissions and data.

Group Properties

Each Express Group has the following properties:

Group Types Explained

Group type determines whether end-users in the same group can access each other's data:

Badge Colors:

• Blue: role_descendents.
• Amber: own_role_and_descendents.
• Green: ignore_role.

Managing Express Groups

Viewing Existing Groups

Navigate to Express Group Administration in the Unqork IDE.

1. The group list displays:
   • Name: The unique group identifier.
   • Description: Purpose of the group.
   • Type: Badge showing data access rule.
   • Actions: Drop-down with Edit and Delete options.
2. Use the search bar to filter groups by name or description.
3. Pagination controls display at the bottom (default: 50 groups per page).

Creating a Group

1. Navigate to Express Group Administration.

2. Click Add Group.

3. Fill in the form:

   Group Name (required)

   • Alphanumeric characters and hyphens only.
   • Cannot begin with a hyphen.
   • Maximum 255 characters.
   • Must be unique.
   • A warning displays below this field: "The group name is permanent and cannot be changed after creation."

   Group Description (optional)

   • Explain the group's purpose and which end-users and roles should belong to it.

   Group Type (required)

   • Select one of the following options:
     • Data access to role descendants only: Hierarchical access (higher roles can see lower roles' data).
     • Data access to own role and role descendants only: Hierarchical access including peers at the same role level.
     • Data access to all roles in hierarchy: All members can see each other's data.

4. Click Add Group.

Result: The new group displays in the group list and can be assigned to roles.

Editing a Group

Navigate to Express Group Administration.

1. Find the group in the list.

2. Select for the role and select Edit.

3. Update the editable fields:

   Editable:

   • Group Description.
   • Group Type.

   Read-Only:

   • Group Name (cannot be changed after creation).

4. Click Save Changes.

Note on Member Management:

• Group membership (which end-users and roles belong to the group) is managed through:
  • Express Role Administration: Assign roles to groups when creating or editing roles.
  • User Management: Assign end-users to roles that belong to groups.

Deleting a Group

Navigate to Express Group Administration.

1. Find the group in the list.
2. Select for the role and select Delete.
3. Confirm deletion in the dialog:
   • "Remember, deleting a group is permanent. To make a group available again, you must re-add it from scratch and reassign all members."

Restrictions:

• No default groups exist (unlike roles).
• Deletion is immediate if the group is not in use.
• All role assignments to this group will be removed.

Promoting Groups

Promotion copies groups from the current environment to a target environment (for example, Dev → QA → Production).

Navigate to Express Group Administration.

1. Click Promote Groups in the top action bar.
2. The Promote Groups dialog opens:
   • All groups are selected by default.
   • Use Select All / Deselect All buttons to manage selection.
   • Check/uncheck individual groups to include or exclude them.
3. Select the target environment from the drop-down.
   • Shows client name and level (for example, "Acme Corp - Production").
4. Click Promote.

Result: Selected groups are copied to the target environment with all properties preserved.

Application Entry-Point RBAC

Application Entry-Point RBAC lets Administrators assign a specific Express Role to an individual end-user for a specific application. The assigned role overrides the end-user's default Express Role, but only for that application's entry-point module.

Configure Application Entry-Point roles in the Application Roles section when editing an individual end-user in Express User Administration.

Settings

Each application in the environment has a row in the table. The table includes the following columns:

Security Limitation

Important: Application Entry-Point RBAC gates access only to the application's entry-point module. End-users can navigate directly to a sub-module URL and bypass this restriction.

To restrict access to sub-modules in an application, configure RBAC at the module level or component level for each sub-module.

How Roles and Groups Work Together

Relationship Overview

1. Roles are assigned to Groups.

   • Roles are assigned to one or more groups when creating or editing the role.
   • Roles have a groups: string[] property listing all group memberships.

2. End-users inherit Group memberships through Roles.

   • An end-user assigned to a role automatically belongs to all groups assigned to that role.
   • End-users can belong to multiple groups if they have multiple roles.

3. Groups control data access.

   • Group type determines how end-users with different roles can access each other's data.
   • Role hierarchy (parent-child relationships) is independent of group membership.
   • Groups layer additional data-access control over the role hierarchy.

Example Scenario

Setup:

• Role: claims-reviewer (parent: standard-user, default permission: read).
• Role: claims-adjuster (parent: claims-reviewer, default permission: write).
• Group: claims-team (type: role_descendents).
• Both roles are assigned to the claims-team group.

End-users:

• Alice has the claims-reviewer role (higher in hierarchy).
• Bob has the claims-adjuster role (child of claims-reviewer, lower in the hierarchy).

Result:

• Alice can view Bob's submissions (she's higher in the hierarchy).
• Bob cannot view Alice's submissions (he's lower in the hierarchy).
• Both end-users can create and edit their own submissions.
• If the group type were ignore_role, both could view each other's submissions regardless of hierarchy.

Best Practices

Role Management

1. Define a clear role hierarchy.

   • Begin with broad roles (for example, "Standard User") and create specialized child roles.
   • Document role relationships and inheritance chains.

2. Use descriptive role names.

   • Use hyphens instead of spaces (for example, claims-adjuster).
   • Keep names short but meaningful.

3. Limit super user flags.

   • Grant Designer Access and Full Submission Access only to trusted administrators.
   • Regularly audit who has these elevated permissions.

4. Test before promoting.

   • Create roles in a Dev or Test environment first.
   • Validate permissions work as expected before promoting to Production.

5. Assign groups during role creation.

   • Think about data access rules when creating roles.
   • Assign roles to groups that match their data access needs.

Group Management

1. Choose the right group type.

   • Use role_descendents for hierarchical teams (managers see staff data).
   • Use own_role_and_descendents for peer collaboration (team members at same level share data).
   • Use ignore_role sparingly: only when all members truly need equal data access.

2. Keep group membership organized.

   • Assign roles to groups, not individual end-users.
   • Update group type if data access rules change.

3. Document group purposes.

   • Use clear descriptions explaining who should belong to the group.
   • Note any special data access considerations.

4. Review group assignments regularly.

   • Audit which roles belong to which groups.
   • Remove inactive or obsolete groups.