Flowable task authorization: what the engine enforces and what your application must
Flowable routes work to candidate users, candidate groups and identity links, but it does not decide, on its own, who may start a process or complete a task in your business. That decision belongs to your application. Teams need this design before go-live, as soon as a process runs in a shared environment with real users, assigns work by role or department, or exposes the Java or REST APIs to callers other than the engine itself. Routing a task to a group is not the same as enforcing that only members of the group can act on it. Confirm in the docs for your exact Flowable version which parts of the task model the engine checks and which it simply stores.
The main design points are the identity model and the checks your API layer performs. Candidate users and groups on a user task say who should see the work, and identity links record who has a relationship with it. Your application must confirm that the caller is the assignee or a candidate before it claims or completes a task, and that the candidate group comes from the same directory your organization trusts. The potentialStarter setting on a process definition describes who may start the process, but the engine does not enforce it, so your start endpoint must check the caller against the same rule. The Flowable docs say identity management can be replaced by implementing the IdmIdentityService interface, with an LDAP reference implementation, which is one way to source group membership from your directory.
Decisions also need an audit trail. Record who started each process instance, who claimed or completed each task, the outcome of each authorization check and the request that triggered it, using your application log or a store your auditors can query. Flowable history can show what happened inside the engine, but confirm what your configuration captures and how long it is kept. Negative tests matter as much as happy-path tests: a user outside the candidate group should be refused, and so should a caller who guesses a task ID. The Flowable open source page notes that security controls are part of the commercial products, so open-source deployments usually need these checks built and tested by the implementation team.
Which authorization checks your API layer must perform
Flowable enforces task and process access only as far as your application asks it to. The four checks below sit in your API layer, in front of the engine calls that start processes, claim or complete tasks, read or write variables and query instances. Each one closes a gap that the engine will not close for you.
Process definition start permission
Before calling the engine to start a process instance, confirm the caller is allowed to start that specific process definition, keyed by definition key and version where your rules differ. Do not rely on the potentialStarter setting to do this, because the engine does not enforce it. Without this check, any authenticated caller who can reach the start endpoint can create instances of processes meant for other roles, such as payment approvals or access requests. Confirm the mapping from your identity provider groups to permitted definitions with your security team.
Candidate or assignee check before claim
Before a claim call, verify that the caller belongs to the task's candidate groups or candidate users, or is already the assignee. Compare the caller's identity against the identity links stored on the task, not against the names in the form data. Without this check, a user outside the intended pool can take ownership of work that belongs to another team, and the audit trail will show that user as the owner.
Assignee and candidate check before complete
Completing a task is a separate decision from claiming it, so repeat the candidate or assignee check on the complete call. Confirm the caller is the current assignee and that the task still exists in the state the caller expects. A caller who was removed from a group after claiming should not be able to finish the work. Without this check, a stale session or a direct API call can advance a process past an approval step that the caller was never entitled to decide.
Variable-level read and write access
Process variables often hold personal data, amounts or decision inputs that some callers must not see or change. Filter variable reads and reject variable writes in the API layer, using a per-variable allow list by role and task. Include variables passed in complete requests, since those can alter routing decisions. Without this check, a caller authorized to complete a task can also overwrite the values that a gateway or decision table uses to choose the next step.
Tenant and case scope
Where one engine serves several tenants or several business units, check that the process instance, task or case belongs to the caller's tenant before any read or action. Apply the same check to CMMN case instances and their plan items, which can be reached through separate endpoints. Without this check, an identifier taken from one tenant's URL can expose or change another tenant's work. Confirm with your architects how tenant IDs are assigned and carried in your identity tokens.
Why potentialStarter does not control who starts a process
The potentialStarter setting in a Flowable process model does not stop anyone from starting the process. The engine does not enforce it. A model that lists candidate starters documents who the designers expected to start the process, but a start request that is not checked against that list will still create an instance. Teams that read the model as a access control rule end up with an open start endpoint, and the gap is usually found only after a user starts a process they should not have been able to reach.
Design the starter check in the application layer, before the call reaches the engine. The API service that accepts a start request should resolve the caller's identity and groups from your identity provider or the IDM service you have configured, decide whether that caller may start the given process definition, and only then call the runtime service. Keep the rule in one place, keyed by process definition key and tenant where relevant, so that the REST API, custom front ends and any integration that starts processes all pass through the same decision. Record the decision, allowed or denied, with the caller and the definition, so that starts can be reviewed later.
Confirm the current wording and behavior of potentialStarter in the Flowable BPMN documentation for the version you run, since the setting's meaning should be checked against your release rather than assumed from this summary. Ask your implementation team to test a start by a user who is not listed in the model, and to confirm that the start is refused by your application rather than by the engine. Put that test in your regression suite so that a future model change or API refactor does not quietly remove the check.
How candidate groups shape Flowable task authorization
With the built-in identity management engine, users, groups and memberships live in the Flowable IDM tables in the same database as the runtime. Candidate groups in BPMN user tasks refer to these group IDs, and the engine resolves them to identity links when a task is created. Administrators maintain membership through the Java or REST APIs, so the engine is the single source of truth for who can claim a task.
- Assignment timing: A task receives candidate group identity links at creation, so a membership change does not rewrite links on tasks that already exist.
- Open task impact: Removing a user from a group stops that user from seeing new tasks for the group, but existing claimed or assigned tasks need a review step.
- Operational ownership: Your team must manage IDM accounts, password storage and onboarding and offboarding procedures inside Flowable.
- Scale of duplication: Any HR or directory change must be re-entered or synchronized into IDM by a process you own.
- Password exposure: Passwords in the IDM tables need an encoder before production use, as described in the Flowable security topics.
Before relying on this model, confirm with your security team who can change group membership and whether those changes are logged.
Flowable lets you replace identity management by overriding IdmIdentityServiceImpl or implementing the IdmIdentityService interface. The Flowable docs include an LDAP identity service implementation as a reference. With this model, the engine asks your service for users and groups, so candidate groups map to directory groups rather than to rows you maintain in IDM.
- Resolution path: Candidate group names in tasks are passed to your service, which decides which users belong to them at query time.
- Open task impact: Because membership is read from the directory when queried, changes often apply to open tasks the next time a candidate list is evaluated, but confirm this against your implementation and any caching you add.
- Sync trade-off: You avoid copying memberships, but the engine and your API layer must agree on the same directory result, which requires consistent caching and error handling.
- Failure behavior: If the directory is unreachable, decide whether task queries fail closed or return an empty list, and test both paths.
- Build effort: Writing and testing the service is project work with its own review cycle.
Check the Flowable identity service documentation for the exact interface methods in the version you run, and test group changes against open tasks before go-live.
In this model an identity provider authenticates users and issues tokens containing group or role claims. Flowable does not need to know the directory at all if your API layer maps those claims to the user ID and groups it passes into engine calls. Your gateway or service enforces who can claim, complete or start work, and the engine stores the identity links your application writes.
- Assignment timing: Group claims are read at login or token issue, so a group change appears only after the token refreshes or expires.
- Open task impact: Tasks keep the identity links written earlier, so removing a claim does not revoke an open task unless your API layer re-checks membership on each action.
- Sync trade-off: The IdP and the engine can disagree between token lifetimes, so define how long a stale assignment may persist.
- Claim governance: Agree which claim names and group values the IdP issues and who controls them.
- Token size: Large group lists in tokens can cause problems at the gateway, so confirm limits with your IdP.
Confirm your IdP's token lifetime and claim format, and decide which actions re-check the directory before they run.
Setup sequence for task and process authorization
This sequence turns Flowable's loose authorization defaults into a documented model in which every task claim, process start and decision is checked by your application and can be shown to an auditor. Each step closes with a check your team can run before moving on.
Inventory processes, starters and task owners
List every deployed BPMN, CMMN and DMN definition, the people or systems allowed to start each one, and the groups that should work its user tasks. Include processes started by REST calls, timers, messages and other services, because each start path needs its own rule. Process owners and the business analysts who model the work should review the list. The step is done when every definition has a named owner and a recorded starter rule, and any definition without one is flagged for review before go-live.
Map business roles to candidate groups
Translate each role in the inventory into the group identifiers used in task candidate groups and identity links. Decide which tasks need a single assignee and which can be claimed by a group, and record the mapping in a version-controlled table kept alongside the process models. Confirm with your identity team where those groups come from, such as an identity provider or the Flowable IDM tables, and how group membership changes are propagated. The step is done when every candidate group in the models appears in the mapping and no model references a group the mapping does not define.
Confirm which starter checks the engine enforces
Test the potentialStarter setting in your engine version and record whether it restricts process starts in your deployment, rather than assuming it does. Treat it as a record of intent unless your own test shows otherwise, and design the start check in your application layer. The owner of the platform should document the result in the authorization design. The step is done when a written note states, for each start path, which layer performs the check and which tests prove it.
Implement API-layer checks before task and start calls
Add checks in the service layer or API gateway that run before any call to claim, complete, delegate or reassign a task, and before any call to start a process or case. Each check should confirm that the authenticated principal belongs to a permitted candidate group or identity link for that task, or to a permitted starter role for that definition. Load the task from the engine before deciding, so the decision is based on the stored state and not on the client's request. The step is done when every write path in the API reaches the check and the check is in code review.
Write tests for denied actions
Build automated tests that call each protected operation as a user who should be refused, including a user outside the candidate group, a user who already completed the task, a user without the starter role, and a user attempting to reassign a task they do not own. Assert that each refusal happens and that no engine state changes. Run these tests in the same pipeline as the functional tests so a later change to the models or the API cannot remove a check silently. The step is done when every protected operation has at least one denial test and the pipeline fails when one is removed.
Enable decision logging and audit records
Record each authorization decision with the principal, the action, the task or process identifier, the outcome and the time, in a log store the security team can search. Confirm which events the Flowable history already captures for task claims and completions, and add application logging for refusals, which the engine history may not hold. Decide the retention period with your compliance owner and restrict who can alter these records. The step is done when a test denial appears in the log store with all required fields and an administrator can reconstruct who completed a given task.
Review the design before each model release
Repeat the inventory and mapping steps whenever a process definition is added or changed, and rerun the denial tests against the new version. Ask the process owner to confirm the starter and candidate rules for the changed model, and keep a record of that approval with the deployment. Review the audit output periodically with the security team to find refusals that point to a wrong group mapping or an attempted bypass. The step is done when each release has a recorded authorization review and the denial tests pass on the deployed version.
Security risks in Flowable authorization designs
Flowable's engines track who may act on a task or start a process, but the checks that enforce those rules sit largely in your application. The risks below cluster around where those checks can fail: in model settings, in stale identity data, in broad API privileges, in variables and in direct data access.
Relying on model-level settings
Candidate users and groups defined in a BPMN model look like access control, but they only describe who is expected to act. The engine does not stop a caller who is outside those lists from completing a task through the API. Treat the model as routing information and verify every completion or start against your own policy in the API layer. Check that no endpoint completes a task without an explicit authorization decision.
Stale group membership on open tasks
Candidate groups are resolved when tasks are created or claimed, so a user who leaves a team or changes role can keep access to tasks already in their queue. Identity links stored on the task persist until something removes them. Your design needs a path that re-evaluates or revokes these links when memberships change, and a periodic review of open tasks against the directory. Confirm how your identity source and the engine synchronize.
Overly broad REST privileges
A service account or integration user with broad REST privileges can read and act on far more process data than its job requires. Flowable grants access through privileges, so a single account that can administer deployments, instances and tasks becomes a high-value target. Map each integration to the narrowest privileges it needs, separate administrative accounts from runtime callers, and review the list whenever a new integration is added.
Variables exposing sensitive data
Process variables are visible to anyone who can query the instance or task, which often includes every candidate on a task. A variable holding a national identifier, salary or health detail can therefore reach users who should only see a summary. Keep sensitive values out of variables where possible, or store references and retrieve the detail through a service that applies its own checks. Review variable names in each model before go-live.
Direct database and admin access
Anyone with direct write access to the engine tables or the admin console can change assignments, identity links and history without passing through your authorization logic, and those changes may not produce the audit events your API generates. Restrict database credentials to operators, route routine changes through the API, and monitor writes to task and identity tables. Confirm with your DBA which roles can reach these schemas in each environment.
Audit trail for authorization decisions in Flowable
A usable authorization decision record answers one question after the fact: who asked to do what, to which process or task, what the system decided, when, and on the basis of which group data. The record should capture the caller identity, the action (claim, complete, start, delegate or read), the process instance or task identifier, the outcome (allowed or denied), the timestamp, and the candidate groups or identity links the check evaluated at that moment. Group membership changes over time, so the groups must be captured as they were at decision time, not reconstructed later from the current directory. Decide the record format and retention with your compliance and security teams before the first API release, because the engine will not write these records for you.
Flowable history and audit data cover part of this record. The history services keep records of task creation, claiming, assignment and completion, along with process instance start and end times and the variables set during execution, and the identity links on a task show which users and groups were attached to it. The level of detail depends on the history configuration in your deployment, and the events recorded for each action depend on the Flowable version you run. Confirm in the Flowable configuration docs which history level you have set, and test that a claim or a denied attempt produces the entries your design needs. Note that a denied request usually never reaches the engine, so history alone cannot show refused attempts.
Your application layer must log what the engine does not: the authenticated caller, the result of each authorization check, and rejected calls, written to a log store your security team controls and protected from edits by the application's own administrators. Write these entries in the same request path as the check, and include the Flowable task or process identifier so the two sources can be joined during an investigation. Before go-live, run a test in which an authorized user, an unauthorized user and a group member who has just been removed each attempt a claim and a completion, and confirm that the application log and the Flowable history tell the same story.
Limits to confirm before you design authorization
Flowable leaves several authorization decisions to your application and its identity setup, so the design depends on facts about your version, identity source and history store. The cards below list the questions to settle with the vendor, the docs or your own test environment before you commit to a model.
Flowable version and REST privileges
Confirm which Flowable major version you will run and how its REST application maps callers to privileges. Privilege names and the verify-privilege behavior are the foundation for any check you rely on at the REST layer. Version 8.0.0 changed the Spring and Jackson baseline, so privilege behavior tested on version 7 should be retested before you rely on it. Ask the vendor which privilege model applies to your chosen release and whether any mode lets authenticated users bypass checks.
Group data from your identity service
Confirm that the identity service you plan to use can supply the group and role membership your candidate group rules need. Flowable's identity management can be replaced with a custom service or an LDAP reference implementation, so the data available depends on what you build. Check whether group membership is returned per user at query time, whether nested groups are resolved, and whether the service can answer the questions your task lists will ask.
Effect of group changes on open tasks
Confirm how a change in group membership affects tasks that already exist. Candidate groups and identity links are stored on the task, so a user removed from a group may still hold an assignment or an identity link that the engine has not rechecked. Test a removal in a non-production environment, then decide whether your application must reassign, re-check or clear links before it completes a task. Write the answer down as a rule the API layer enforces.
Database support for history retention
Confirm which database you will use for runtime and history data, since the authorization audit trail depends on how history is stored and retained. Flowable documents support for H2, MySQL, Oracle, PostgreSQL, DB2 and Microsoft SQL Server, and notes that MySQL versions below 5.6.4 lack millisecond precision. Timestamp precision affects how you order decisions in an audit. Confirm retention settings and backup scope with your database team before you define what evidence the design preserves.
Scope of commercial security controls
Confirm whether the security controls in Flowable's commercial products are part of your plan or whether you will build the equivalent in your own application. Commercial products such as Flowable Work, Engage, Orchestrate and Design add security controls and governance on top of the same engines, and open source users receive a community forum with professional services offered separately. Ask the vendor which controls are included in each product, whether they cover task-level checks, and what they cost to license before you assume they close any gap.
Ownership of the authorization decision
Confirm which team owns the authorization rules and where they are tested. The engine stores candidate data and enforces some constraints, but many checks, such as whether a caller may start a process or complete a specific task, must run in your API layer. Agree on the owner, the test cases and the review process for rule changes before implementation, so that a change to a group or a process definition does not silently widen access.
Questions teams ask before outsourcing Flowable authorization
What drives the cost of designing Flowable authorization?
The main driver is how many distinct roles, candidate groups and process or case types the application has, because each one needs a decision about who may claim, complete, start or view it. Cost also rises with the number of entry points that call the engine, such as REST endpoints, custom APIs, message handlers and external workers, since each needs a check. Integration with your identity provider or LDAP directory adds work, and so does an audit trail that must explain every decision. Ask for a written scope that lists these items individually, so each one can be priced and reviewed.
How long does the design and build of task authorization take?
Duration depends on the same factors as cost: the number of process and case models, the role model, how many API paths must enforce checks, and how many identity sources feed group membership. The work usually runs in phases, starting with a written authorization model, then the enforcement layer, then tests and audit logging. No duration is stated here, so ask the partner to tie each phase to deliverables and dates in the written scope, and to name which of your teams must approve each phase.
What does the work need from our identity and security teams?
You will need to provide the source of truth for users and groups, whether that is an identity provider, LDAP or the Flowable identity tables, along with how group membership is issued and removed. Security teams should review the authorization model, the privileges given to service accounts, and the logging requirements. Expect requests for test accounts in each role and for access to a non-production environment. Confirm named owners and response times for these requests before work starts, since they often set the pace of the project.
Can our internal team build Flowable authorization without a partner?
Yes, many teams do, especially when they already run Java services and know the Flowable API well. The questions to answer honestly are whether someone has written checks against candidate groups and identity links before, whether the team has time to test the edge cases, and whether they can keep the model current as processes change. A partner is most useful when the authorization model needs review from several parties, or when the team lacks capacity to maintain it after go-live. Compare both options against the same written scope.
What does a fixed-scope engagement cover for Flowable authorization?
A fixed-scope engagement sets out, in writing before work starts, which process and case models, API paths and identity sources are covered, along with the deliverables and timelines. For this topic, expect the written scope to name the authorization model, the enforcement checks in your API layer, the test cases and the audit logging design. Anything outside those items, such as a later migration or new roles, would need a change to the scope. Ask what happens when a change is requested and how it would be quoted.
What recurs after go-live, and what is one-time?
The design, the enforcement code and the initial tests are one-time work. Recurring work includes reviewing role changes, updating checks when new process definitions are deployed, and reviewing audit records. Engine upgrades can also require retesting authorization behavior. Ongoing support and continuous testing are available as retainers, so ask whether support is included in the fixed scope or quoted separately, and what response commitments, if any, apply.
How do we confirm the authorization checks work before launch?
Start with a test plan that covers each role against each task, start action and API path, including negative cases where a user should be refused. Verify that unassigned users cannot complete tasks through direct API calls, and that the potentialStarter setting is not relied on for enforcement. Check that the audit records show who decided what and when. Ask the partner to show which tests run automatically and which need manual review, and who signs off the results on your side.
How DeployOpen scopes and delivers Flowable authorization
DeployOpen treats task and process authorization as application design work that sits in your API layer, not as a setting to switch on in the engine. We scope the authorization model against your roles, deliver the checks and audit trail in your Flowable application, and hand over documentation your team can maintain. Engagements are fixed-scope and agreed in writing before work starts.
How we scope
- Map which roles may claim, complete and start each process, case and task in your organization.
- Document how candidate groups and identity links will be populated from your identity source.
- Record where the engine's built-in checks stop and where your API layer must enforce authorization.
- Agree in writing the deliverables, test scope and timeline before any build work begins.
How we build
- Implement authorization checks in your API layer for task completion and process start requests.
- Configure identity service integration so group and user data match your directory or identity provider.
- Build audit logging of authorization decisions that records who acted, on what, and why it was allowed.
- Test denied, permitted and edge cases, including tasks reassigned or claimed by users outside their group.
How we hand over
- Deliver a written authorization model that lists every role, group and enforced check in the application.
- Provide test cases and results that your team can rerun after each process or dependency change.
- Document operational steps for adding users, changing group membership and reviewing audit records.
- Walk your engineers through the code paths so ownership of authorization logic stays with your team.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover.
- Review authorization checks again when you add processes, change roles or upgrade Flowable versions.
- Retest the authorization model as part of routine security testing of your Flowable applications.
- Confirm with your team which support scope and response arrangements fit your operating model.
