26. Administration & RBAC

BPMN Central uses a dynamic, database-driven Role-Based Access Control (RBAC) system. Unlike hardcoded role checks, all authorization rules are stored in the database and can be modified at runtime through admin screens — no application restart required.

This guide will help you understand the security model, establish best practices, and troubleshoot common administrative issues.

Security Architecture Overview

BPMN Central evaluates security in four distinct layers. A request must pass all applicable layers to succeed.

┌──────────────────────────────────────────────┐
│ Layer 1: Authentication                      │
│ - Spring Security form login                 │
│ - CSRF, XSS, Clickjacking protection         │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 2: Page Authorization (Role-Page)      │
│ - URL-based: can this role access /path?     │
│ - Configured via Role-Page Management screen │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 3: Workflow Start Authorization        │
│ - Process-Role: can this role start workflow?│
│ - Configured via Process Roles screen        │
└──────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────┐
│ Layer 4: Task Authorization                  │
│ - Assignee/candidate group validation        │
│ - Driven by BPMN assignment rules            │
└──────────────────────────────────────────────┘

Access to a URL is decided entirely by Page permissions. Because permissions are matched by URL pattern, a page permission also protects every button and action on that page: if a role can't reach /admin/tags/delete/{id}, the "Delete" button is hidden and a direct request to that URL is rejected. Granular actions therefore get their own page permission (e.g. Workflow Delete), while pages whose buttons should all travel together share a single parent permission (e.g. Connectors covers create/edit/delete/toggle).

Best Practices for Administrators

1. Design Roles by Business Function: Do not create a role for every individual user. Create roles like ROLE_HR_MANAGER, ROLE_IT_SUPPORT, or ROLE_FINANCE_CLERK. Roles are just arbitrary text labels—they have no hardcoded meaning until you map them to pages and processes.
2. Page Protection is the First Line of Defense: Use Role-Page Management to block URL access entirely. If a user doesn't have access to the /workflows/list page, they will receive a 403 Forbidden error even if they try to guess the URL. The same permission governs the buttons on that page — grant Process Instance Stop and the "Stop Instance" button appears; withhold it and the button is hidden and the action is blocked.

Common Administrative Workflows

1. Onboarding a New Department

When a new team (e.g., Marketing) starts using BPMN Central, follow this sequence:

1. Go to Role Management and create ROLE_MARKETING.
2. Go to Role-Page Management and grant ROLE_MARKETING access to the core pages (/workflows/list, /tasks/my, /instances/my-active).
3. Go to User Management and map ROLE_MARKETING to the new employees.
4. Go to Process Roles and give ROLE_MARKETING permission to start the "Marketing Campaign Approval" workflow.

2. Troubleshooting: "I can't see the workflow!"

If a user complains that they cannot see a specific workflow in their "Start Workflow" list, check these three things:

• Check 1: Do they actually have the correct role? (Verify in User-Role Management)
• Check 2: Does their role have access to the /workflows/list and /workflows/{id}/start pages? (Verify in Role-Page Management)
• Check 3: Is the workflow explicitly mapped to their role? (Verify in Process Roles). Note: If a workflow has zero roles assigned to it, nobody can start it!

3. Monitoring System Health

As an administrator, your daily/weekly routine should involve checking the health of the engine:

• Engine Admin (/admin/engine): Check for Stuck Tasks. If a Script Task failed because of a typo in your Javascript, the task will pause and appear here. You can fix the BPMN script and click "Retry" directly from this console. You should also monitor Deadletter Jobs for permanently failed background tasks.
• Error Logs (/admin/error-logs): Review unhandled Java exceptions. The Smart Summary feature will automatically scan the StackTrace and attempt to pinpoint the exact line of code or missing BPMN variable that caused the crash, saving you hours of debugging.

Admin Screens Reference

• User Management (/admin/users): Search, enable, disable, or delete user accounts. (Disabled users cannot log in).
• Role Management (/admin/roles): Create and delete arbitrary role labels.
• User-Role Assignment (/admin/user-role): Assign roles to users. A user's effective permissions are the union of all their assigned roles.
• Role-Page Management (/admin/role-page): Map roles to specific URL endpoints (this is where every permission is granted or revoked).
• Process Roles (/admin/process-roles): Control which roles are allowed to start specific workflows.
• System Settings (/admin/settings): Configure email language (en or tr) and email sender display names.
• HTTP Connectors (/admin/connectors): Manage external API integrations for Service Tasks.
• Tag Management (/admin/tags): Create colored badges to categorize workflows.
• API Keys (/admin/api-keys): Generate and revoke wf_ prefixed tokens for REST API access.
• Scheduled Workflows (/admin/schedules): Manage background cron jobs that automatically trigger workflows.