Files
James MaesandClaude Sonnet 5.5 607935ab2b
QRun-IO/ci-policy: ci / fork-guard (pull_request) Skipped
QRun-IO/ci-policy: native / fork-deny (pull_request) Skipped
QRun-IO/ci-policy: native / dotnet-0 (pull_request) Skipped
QRun-IO/ci-policy: ci / Scoped workflow [workflow 60e5a80ed7a5a67877bfb3e129b1929c83464b6e] (pull_request) Successful in 12s
QRun-IO/ci-policy: ci / head-profile (pull_request) Skipped
QRun-IO/ci-policy: ci / repository-policy (pull_request) Skipped
QRun-IO/ci-policy: ci / application-template-0 (pull_request) Skipped
QRun-IO/ci-policy: ci / gradle-1 (pull_request) Skipped
QRun-IO/ci-policy: ci / java-core-2-head (pull_request) Skipped
QRun-IO/ci-policy: ci / java-docker-3 (pull_request) Skipped
QRun-IO/ci-policy: native / native-result (pull_request) Successful in 8s
QRun-IO/ci-policy: ci / java-docker-3-head (pull_request) Skipped
QRun-IO/ci-policy: ci / java-docker-4 (pull_request) Skipped
QRun-IO/ci-policy: ci / java-frontend-browser-5 (pull_request) Skipped
QRun-IO/ci-policy: ci / java-maven-6-head (pull_request) Skipped
QRun-IO/ci-policy: ci / java-maven-7 (pull_request) Skipped
QRun-IO/ci-policy: ci / java-maven-7-head (pull_request) Skipped
QRun-IO/ci-policy: ci / node-8 (pull_request) Skipped
QRun-IO/ci-policy: ci / node-9 (pull_request) Skipped
QRun-IO/ci-policy: ci / node-10 (pull_request) Skipped
QRun-IO/ci-policy: ci / node-playwright-11 (pull_request) Skipped
QRun-IO/ci-policy: ci / repository-policy-12 (pull_request) Skipped
QRun-IO/ci-policy: ci / source-config-13 (pull_request) Skipped
QRun-IO/ci-policy: ci / source-config-14 (pull_request) Skipped
QRun-IO/ci-policy: ci / android-0 (pull_request) Skipped
QRun-IO/ci-policy: ci / original-business (pull_request) Skipped
QRun-IO/ci-policy: ci / original-mcp (pull_request) Skipped
QRun-IO/ci-policy: ci / original-voyage (pull_request) Skipped
QRun-IO/ci-policy: ci / original-cli (pull_request) Skipped
QRun-IO/ci-policy: ci / not-enrolled (pull_request) Skipped
QRun-IO/ci-policy: ci / shared-pipeline (pull_request) Skipped
Shared Java Maven CI / secrets (push) Successful in 42s
QRun-IO/ci-policy: Shared Java Maven CI / secrets (pull_request) Successful in 40s
Shared Java Maven CI / gate (push) Canceled after 0s
Shared Java Maven CI / verify (push) Canceled after 0s
qrun-release / release (push) Canceled after 7m0s
qrun-release / postpublish (push) Canceled after 0s
QRun-IO/ci-policy: Shared Java Maven CI / verify (pull_request) Successful in 1m5s
QRun-IO/ci-policy: Shared Java Maven CI / gate (pull_request) Successful in 23s
QRun-IO/ci-policy: ci / java-maven-6 (pull_request) Successful in 43m55s
QRun-IO/ci-policy: ci / ci-result (pull_request) Successful in 10s
Release candidate / release-rc (pull_request) Skipped
build: require the published QQQ 4.1 core (4.1.0-RC.21)
Import qqq-bom-pom 4.1.0-RC.21 unconditionally ahead of the parent's BOM
and remove the opt-in qqq-snapshot profile and its Sonatype snapshot
repository. State the minimum QQQ version as 4.1.0+ in the README. The
development revision and the parent are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-05 05:44:19 -06:00

3.7 KiB

qbit-user-role-permissions

Role-based access control for QQQ applications.

For: QQQ developers who need to restrict what users can see and do based on their assigned roles
Status: Stable

Why This Exists

Most business applications need access control. Without it, every user sees everything and can do anything. Building RBAC from scratch means creating tables, writing permission checks, building admin UIs, and wiring it all together.

This QBit provides a complete RBAC system that integrates directly with QQQ's security layer. Define roles, assign permissions, and QQQ enforces them automatically across entities, processes, and dashboard screens.

Features

  • Role Management - Create roles with hierarchical inheritance
  • Entity Permissions - Control read, insert, update, delete per entity per role
  • Field-Level Security - Hide or make specific fields read-only by role
  • Process Permissions - Restrict which roles can execute which processes
  • Record-Level Filtering - Apply automatic filters so users only see their own data
  • Dashboard Integration - Navigation and screens respect permissions automatically

Quick Start

Prerequisites

  • QQQ application (v4.1.0+)
  • Database backend configured

Installation

Add to your pom.xml:

<dependency>
    <groupId>com.kingsrook.qbits</groupId>
    <artifactId>qbit-user-role-permissions</artifactId>
    <version>0.32.0</version>
</dependency>

Register the QBit

public class AppMetaProvider extends QMetaProvider {
    @Override
    public void configure(QInstance qInstance) {
        // Register the QBit
        new UserRolePermissionsQBit().configure(qInstance);
        
        // Your entities, processes, etc.
    }
}

Define Roles

new QRoleMetaData()
    .withName("admin")
    .withLabel("Administrator")
    .withPermissions(QPermission.allTablesFullAccess());

new QRoleMetaData()
    .withName("viewer")
    .withLabel("Read Only")
    .withPermissions(QPermission.allTablesReadOnly());

Usage

Entity Permissions

// Full access to orders, read-only for customers
new QRoleMetaData()
    .withName("sales")
    .withPermission("order", QPermission.fullAccess())
    .withPermission("customer", QPermission.readOnly());

Field-Level Restrictions

// Hide salary field from non-HR roles
new QFieldPermission()
    .withTable("employee")
    .withField("salary")
    .withRoles("hr", "admin")  // Only these roles can see it
    .withOthersCanRead(false);

Record-Level Filtering

// Users only see their own records
new QRecordSecurityLock()
    .withTable("order")
    .withFieldName("createdByUserId")
    .withLockType(RecordSecurityLock.LockType.READ_AND_WRITE);

Process Permissions

// Only admins can run data import
new QProcessMetaData()
    .withName("dataImport")
    .withPermissionRoles("admin");

Configuration

The QBit creates these tables automatically:

Table Purpose
role Role definitions
user_role User-to-role assignments
permission Role-to-entity permissions

Override table names in configuration if needed:

new UserRolePermissionsQBit()
    .withRoleTableName("app_role")
    .withUserRoleTableName("app_user_role");

Project Status

Stable and production-ready. Used across multiple QQQ deployments.

Roadmap

  • Permission caching improvements
  • Audit logging for permission changes
  • UI for permission matrix editing

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Run tests: mvn clean verify
  4. Submit a pull request

License

Apache-2.0 - See LICENSE and NOTICE.