Access Control

Manage permissions and roles for the Form Portal.

Overview

The Form Portal uses a multi-layered access control system:

  1. Privileges - Module-level permissions
  2. Roles - Form-level access groups
  3. Workgroups - Data isolation boundaries
  4. Ownership - User-specific access

Privileges

Required Privileges

Privilege Purpose Required For
mod-form-portal Basic portal access All users
mod-form Form features Creating and viewing forms
mod-checklist Checklist features Creating and viewing checklists

Role-Based Access

Understanding Roles

Roles determine which forms users can access:

  • Forms are configured with access.roles list
  • Users must belong to at least one role in the list
  • Roles are managed separately from privileges

Configuring Form Access

Forms specify which roles can access them:

In Form Designer: 1. Open form definition 2. Set access.roles field 3. Add role IDs 4. Save form

Example Form Configuration:

{
  "name": "Leave Request",
  "access": {
    "roles": ["employee", "manager", "hr"]
  }
}

Access Logic: - User must belong to at least one role in the list - Empty access.roles means no role-based restrictions - Combined with workgroup and ownership checks

Role Categories in Portal

The portal organizes forms by role:

Owner Category: - Forms where user is the owner - Always accessible regardless of roles

Role Categories: - One category per role user belongs to - Shows forms accessible via that role - Organized alphabetically

Configuring Form Workgroups

In Form Designer: 1. Open form definition 2. Set workgroup assignments 3. Save form

Example:

{
  "name": "Leave Request",
  "workgroups": ["main-office", "remote-office"]
}

Access Logic: - User must be in at least one matching workgroup - Forms without workgroups are accessible to all - Combined with role and ownership checks

Ownership-Based Access

Form Ownership

Each form has an owner:

{
  "name": "Leave Request",
  "owner": "user-id-123"
}

Owner Access: - Owners always see their forms - Appears in “Owner” category - Bypasses role restrictions - Still subject to workgroup restrictions

Setting Form Owner

When Creating Form: - Owner is set to creating user automatically - Cannot be changed by user

Changing Owner: - Requires admin access - Update owner field in form definition - Use Ownership module

Access Control Matrix

How different access controls combine:

Privilege Role Workgroup Owner Result

| ✓ | ✓ | ✓ | - | Access granted | | ✓ | - | ✓ | ✓ | Access granted (owner) | | ✓ | ✓ | - | - | No access (workgroup mismatch) | | - | ✓ | ✓ | - | No access (no privilege) | | ✓ | - | ✓ | - | No access (no role) |

Access Requirements: 1. Must have mod-form-portal privilege 2. Must have mod-form or mod-checklist privilege 3. Must match workgroup OR be owner 4. Must match role OR be owner

Troubleshooting Access Issues

User Can’t Access Portal

Check: 1. User has mod-form-portal privilege 2. User has mod-form or mod-checklist privilege 3. User is logged in 4. Session is valid

Solution:

user.addPrivilege("mod-form-portal")
user.addPrivilege("mod-form")

User Can’t See Any Forms

Check: 1. User assigned to at least one role 2. User in at least one workgroup 3. Forms exist for user’s roles 4. Forms enabled

Solution:

user.addRole("employee")
user.addWorkgroup("main-office")

User Can’t See Specific Form

Check: 1. Form’s access.roles includes user’s roles 2. Form’s workgroups match user’s workgroups 3. Form is enabled 4. Form not marked internal

Solution: - Update form’s access.roles - Add user to matching workgroup - Enable form - Set internal = false

User Can’t Create Forms

Check: 1. User has mod-form privilege 2. Templates exist for user’s roles 3. Templates enabled 4. Workflow exists (for workflow forms)

Solution: - Grant mod-form privilege - Assign to roles with templates - Enable templates - Create/enable workflow

Best Practices

Privilege Management

  • Grant minimum required privileges
  • Use role-based privileges when possible
  • Regular privilege audits
  • Document privilege assignments

Role Management

  • Use descriptive role names
  • Organize roles by function
  • Avoid role proliferation
  • Regular role reviews

Security

  • Principle of least privilege
  • Regular access reviews
  • Audit access changes
  • Monitor access patterns

Access Audit

Regular Audits

Perform regular access audits:

Monthly: - Review user privileges - Check role assignments - Verify workgroup memberships

Quarterly: - Comprehensive access review - Remove unused roles - Clean up workgroups - Update documentation

API Access Control

REST API endpoints enforce the same access control:

Endpoint Access: - Requires valid session - Checks privileges - Filters by roles and workgroups - Respects ownership

Example:

GET /form-portal/forms/mycurrent
- Requires: mod-form-portal, mod-form
- Returns: Forms user can access
- Filtered by: roles, workgroups, ownership

See REST API for details.

Next Steps: - Installation - Deploy and configure - REST API - API reference - Administration - Admin overview

Next: REST API