Camunda allows users to authorize access to the data it manages. This makes it possible to configure which user can access which process instances, tasks, etc…
Authorization has a performance cost and introduces some complexity. It should only be used if required.
When is Authorization required?
Not every Camunda setup needs to enable authorization. In many scenarios, Camunda is embedded into an application and the application itself ensures that users can only access data they are authorized to access. Generally speaking, authorization is only required if untrusted parties interact with the process engine API directly. If you embed the process engine into a Java application, you usually do not need to enable authorization. The application can control how the API is accessed.
Situations in which authorization is required:
- Camunda Rest API is made accessible to users who should not have full access, even after authentication.
- Camunda Webapplication is made accessible to users who should not have full access, even after authentication.
- Other situations in which an untrusted user can directly construct the queries and commands executed on the process engine.
Situations in which authorization is not required
- An application completely controls the API methods invoked on the process engine.
- Camunda Webapplication is made accessible to users who can have full access after authentication.
Assume that you have the following authorization requirement: As a regular user, I can only see the tasks that are assigned to me.
If the engine is embedded into a Java application, the application can easily ensure this by restricting the task query on the
assignee property. The application can guarantee this since the Camunda API is not directly exposed to the user.
An Authorization assigns a set of Permissions to an identity to interact with a given Resource.
- User ‘jonny’ is authorized to create new users
- Group ‘marketing’ is not authorized to delete the Group ‘sales’
- Group ‘marketing’ is not allowed to use the tasklist application.
Camunda BPM distinguishes between two types of identities: users and groups. Authorizations can either range over all users (userId = ANY), an individual user or a group of users.
A Permission defines the way an identity is allowed to interact with a certain resource.
The basic permissions available in the engine are:
Please note that the permission “None” does not mean that no permissions are granted, it stands for “no action”. Also, the “All” permission will vanish from a user if a single permission is revoked.
For detailed list of available permissions please check Permission by resource section.
A single authorization object may assign multiple permissions to a single user and resource:
authorization.addPermission(Permissions.READ); authorization.addPermission(Permissions.UPDATE); authorization.addPermission(Permissions.DELETE);
Resources are the entities the user interacts with.
The following resources are available:
|Resource Name||Integer representation||Resource Id|
|Application (Cockpit, Tasklist, ...)||0||admin/cockpit/tasklist/*|
|Decision Definition||10||Decision Definition Key|
|Decision Requirements Definition||14||Decision Requirements Definition Key|
|Group Membership||3||Group Id|
|Process Definition||6||Process Definition Key|
|Process Instance||8||Process Instance Id|
|Tenant Membership||12||Tenant Id|
Note: The Resource Id should be ‘*’ when you create new authorization with CREATE permissions only.
There are three types of authorizations:
|Authorization type||Description||Integer representation|
|Global Authorization (
||Ranges over all users and groups (
|Grant Authorization (
||Ranges over users and groups and grants a set of permissions. Grant authorizations are commonly used for adding permissions to a user or group that the global authorization revokes.||1|
|Revoke Authorization (
||Ranges over users and groups and revokes a set of permissions. Revoke authorizations are commonly used for revoking permissions to a user or group that the global authorization grants.||2|
Performance of REVOKE Authorizations
See the Performance Considerations section on this Page.
Authorizations may range over all users, an individual user or a group of users, or they may apply to an individual resource instance or all instances of the same type (resourceId = ANY). The precedence is as follows:
- An authorization applying to an individual resource instance precedes over an authorization applying to all instances of the same resource type.
- An authorization for an individual user precedes over an authorization for a group.
- A Group authorization precedes over a GLOBAL authorization.
- A Group GRANT authorization precedes over a Group REVOKE authorization.
- A User GRANT authorization precedes over a User REVOKE authorization.
When are Authorizations checked?
Authorizations are checked if
- the configuration option
authorizationEnabledis set to
true(default value is
- there is a currently authenticated user.
The last item means that even if authorization is enabled, authorization checks are only performed if a user is currently authenticated. If no user is authenticated, then the engine does not perform any checks.
When using the Camunda Webapps, it is always ensured that a user is authenticated before the user can access any restricted resources. When embedding the process engine into a custom application, the application needs to take care of authentication if it needs authorization checks to be performed.
Authentication vs. Authorization
Authentication and Authorization are two distinct concepts as explained here.
Permissions by Resource
This section explains which permissions are available on which resources.
Read, Update, Create, Delete
The permissions Read, Update, Create and Delete are available for most of the resources. The following table gives an overview for which resources they are available:
|Decision Requirements Definition||X|
To execute an operation asynchronously, only a “Create” permission on the Batch Resource is required. However, when executing the same operation synchronously, the specific permissions (e.g. “Delete” on Process Instance Resource) are checked.
For example, a user without the “Update” permission on the Process Instance Resource and granted “Create” permission on the Batch Resource can modify multiple Process Instances asynchronously by creating a batch, although he could not execute this operation synchronously.
Additional Task Permissions
In Addition to Update, Read and Delete, the following permissions are available on the Task Resource:
- Read History
- Task Assign
- Task Work
- Update Variable
A user can perform different actions on a task, like assigning the task, claiming the task or completing the task. If a user has “Update” permission on a task (or “Update Task” permission on the corresponding process definition) then the user is authorized to perform all these task actions. If finer grained authorizations are required, the permissions “Task Work” and “Task Assign” can be used. The intuition behind “Task Work” is that it only authorizes the user to work on a task (i.e., claim and complete it) but not assign it to another user or in another way “distribute work” to colleagues.
If a user has “Update Variable” permission on a task (or “Update Task Variable” permission on the corresponding process definition) the user is authorized to perform set/remove task variable actions.
The table below shows a detailed overview on which permissions authorize a user to perform which task actions:
|Task Work||Task Assign||Update Variable||Update|
|Add Candidate User||X||X|
|Delete Candidate User||X||X|
|Add Candidate Group||X||X|
|Delete Candidate Group||X||X|
|Set Task Priority||X||X|
|Set Task Variable||X||X|
|Remove Task Variable||X||X|
GRANT and REVOKE authorizations with Task Work, Task Assign, and Update Variable permissions precede over Update and Update Task.
Default Task Permissions
When a user is related to a task by being an assignee, a candidate user, a part of a candidate group or an owner, then these users get the default permission as either “Task Work” or “Update”, based on the configuration setting “defaultUserPermissionNameForTask”.
If the “defaultUserPermissionNameForTask” is not set, then by default UPDATE permission is granted.
Additional Process Definition Permissions
In Addition to Update, Read and Delete, the following permissions are available on the Process Definition Resource:
- Read Task
- Update Task
- Task Work
- Task Assign
- Create Instance
- Read Instance
- Update Instance
- Retry Job
- Suspend Instance
- Update Instance Variable
- Update Task Variable
- Migrate Instance
- Delete Instance
- Read History
- Delete History
The “Create Instance” permission is required to start new process instances.
Start new process instance
To perform that action, the user also needs to have “Create” permission on the Process Instance resource.
GRANT and REVOKE authorizations with Retry Job, Suspend, Suspend Instance, Update Instance Variable, and Update Task Variable permissions precede over Update. Keep in mind that user who is allowed to perform variable updates could trigger other changes in the process by updating a variable. For example, successful evaluation of conditional event related to this variable.
Additional Process Instance Permissions
In Addition to Create, Read, Update, and Delete, the following permissions are available on the Process Instance Resource:
- Retry Job
- Update Variable
GRANT and REVOKE authorizations with Retry Job, Suspend, and Update Variable permissions precede over Update. Keep in mind that user who is allowed to perform variable updates could trigger other changes in the process by updating a variable. For example, successful evaluation of conditional event related to this variable.
Additional Decision Definition Permissions
In Addition to Update, Read and Delete, the following permissions are available on the Decision Definition Resource:
- Create Instance
- Read History
- Delete History
The “Create Instance” permission is required to evaluate decisions with the decision service.
Additional Batch Permissions
In Addition to Create, Update, Read and Delete, the following permissions are available on the Batch Resource:
- Read History
- Delete History
- Create Batch Migrate Process Instances
- Create Batch Modify Process Instances
- Create Batch Restart Process Instances
- Create Batch Delete Running Process Instances
- Create Batch Delete Finished Process Instances
- Create Batch Delete Decision Instances
- Create Batch Set Job Retries
- Create Batch Set External Task Retries
- Create Batch Update Process Instances Suspend
The specific “Create …” permission has higher priority than the general “Create” permission.
Default Read Variable Permissions
enforceSpecificVariablePermission process engine configuration is enabled, in order to read variables, the user needs to be granted with the following permissions:
In case of Tasks
- Read Variable (for standalone tasks)
In case of Process Definitions
- Read Instance Variable (for runtime process instance variables)
- Read History Variable (for historic variables)
- Read Task Variable (for runtime task variables)
The resource “Application” uniquely supports the “Access” permission. The Access permission controls whether a user has access to a Camunda webapplication or not. Out of the box, it can be granted for the following applications (resource ids):
*(Any / All)
Camunda BPM has no explicit concept of “administrator” beyond it being a user who has been granted all authorizations on all resources.
The “camunda-admin” Group
When downloading the Camunda BPM distribution, the invoice example application creates a group with id
camunda-admin and grants all authorizations on all resources to this group.
In absense of the demo application, this task is performed by the Camunda Admin Web Application. If the Camunda webapplication is started for the first time and no user exists in the database, it asks you to perform the “initial setup”. In this process, the
camunda-admin group is created and granted all permissions on all resources.
The group “camunda-admin” is not created when using LDAP (since LDAP is only accessed in a read-only way). Also see the below section on the administrator authorization plugin.
The Administrator Authorization Plugin
The administrator authorization plugin is a process engine plugin with the following functionality: when the process engine is started, it grants administrative access to a configured group or user. Effectively this means that it grants all permissions on all resources to the configured group or user.
Usually this is used to bootstrap an LDAP installation: granting administrative access to an initial user who can then log in to Admin and configure additional authorizations using the UI.
The following is an example of how to configure the administrator authorization plugin in bpm-platform.xml / processes.xml:
<process-engine name="default"> ... <plugins> <plugin> <class>org.camunda.bpm.engine.impl.plugin.AdministratorAuthorizationPlugin</class> <properties> <property name="administratorUserName">admin</property> </properties> </plugin> </plugins> </process-engine>
The plugin will make sure that administrator authorizations (ALL permissions) are granted on all resources whenever the process engine is started.
It is not necessary to configure all LDAP users and groups which should have administrator authorization. It is usually enough to configure a single user and use that user to log into the webapplication and create additional authorizations using the User Interface.
Complete list of configuration properties:
||The name of the administrator user. If this name is set to a non-null and non-empty value, the plugin will create user-level Administrator authorizations on all built-in resources.|
||The name of the administrator group. If this name is set to a non-null and non-empty value, the plugin will create group-level Administrator authorizations on all built-in resources.|
This section explains available process engine configuration options related to authorization.
Enable Authorization Checks
Authorization checks can be globally enabled or disabled using the configuration option
authorizationEnabled. The default setting for this configuration option is
Enable Authorization Checks for User Code
The configuration option
authorizationEnabledForCustomCode controls whether authorization checks are performed for commands executed by delegation code (i.e., a Java Delegate). The default setting for this configuration option is
Check Revoke Authorizations
The configuration option
authorizationCheckRevokes controls whether authorization checks take into account authorizations of type
Available values are:
always: Always enables check for revoke authorizations. This mode is equal to the < 7.5 behavior. NOTE: Checking revoke authorizations is very expensive for resources with a high potential cardinality like tasks or process instances and can render authorized access to the process engine effectively unusable on most databases. You are therefore strongly discouraged from using this mode.
never: Never checks for revoke authorizations. This mode has best performance and effectively disables the use of revoke authorizations. Note: It is strongly recommended to use this mode.
auto(default value): This mode only checks for revoke authorizations if at least one revoke authorization currently exits for the current user or one of the groups the user is a member of. To achieve this it is checked once per command whether potentially applicable revoke authorizations exist. Based on the outcome, the authorization check then uses revoke or not. NOTE: Checking revoke authorizations is very expensive for resources with a high potential cardinality like tasks or process instances and can render authorized access to the process engine effectively unusable on most databases.
Also see the Performance Considerations section on this page.
Java API Example
An authorization is created between a user/group and a resource. It describes the user/group’s permissions to access that resource. An authorization may express different permissions, such as the permission to READ, UPDATE, DELETE the resource. (See Authorization for details).
To grant the permission to access a certain resource, an authorization object is created. For example, to give access to a certain filter:
Authorization auth = authorizationService.createNewAuthorization(AUTH_TYPE_GRANT); // The authorization object can be configured either for a user or a group: auth.setUserId("john"); // -OR- auth.setGroupId("management"); //and a resource: auth.setResource("filter"); auth.setResourceId("2313"); // a resource can also be a process definition auth.setResource(Resources.PROCESS_INSTANCE); // the process defintion key is the resource id auth.setResourceId("invoice"); // finally the permissions to access that resource can be assigned: auth.addPermission(Permissions.READ); // more than one permission can be granted auth.addPermission(Permissions.CREATE); // and the authorization object is saved: authorizationService.saveAuthorization(auth);
As a result, the given user or group will have permission to READ the referenced filter.
Another possible example would be to restrict the group of persons who are allowed to start a specific process:
//we need to authorizations, one to access the process definition and another one to create process instances Authorization authProcessDefinition = authorizationService.createNewAuthorization(AUTH_TYPE_GRANT); Authorization authProcessInstance = authorizationService.createNewAuthorization(AUTH_TYPE_GRANT); authProcessDefinition.setUserId("johnny"); authProcessInstance.setUserId("johnny"); authProcessDefinition.setResource(Resources.PROCESS_DEFINITION); authProcessInstance.setResource(Resources.PROCESS_INSTANCE); //the resource id for a process definition is the process definition key authProcessDefinition.setResourceId("invoice"); //asterisk to allow the start of a process instance authProcessInstance.setResourceId("*") // allow the user to create instances of this process definition authProcessDefinition.addPermission(Permissions.CREATE_INSTANCE); // and to create processes authProcessInstance.addPermission(Permissions.CREATE); authorizationService.saveAuthorization(authProcessDefinition); authorizationService.saveAuthorization(authProcessInstance);
Camunda Admin Webapp
The Camunda Admin Webapplication provides an out of the box UI for configuring Authorizations.
Authorizations are calculated by the database which is most efficient. Example: when performing a task query, the database query only returns the tasks for which the user has a READ authorization.
Performance of Checking Grant Authorizations
When only Grant authorizations are used, the check is very efficient since the authorization table can be joined with the resource table (task table, process instance table, etc…).
Performance of Checking Revoke Authorizations
Revoke authorizations are expensive to check. The check needs to consider the precedence of authorizations. Example: a user level Grant is stronger than a group level Revoke. A sequence of nested SQL
CASE statements and a subselect is used to account for the precedence. This has two downsides:
- The check scales linearly with the cardinality of the resource table (doubling the number of tasks makes the query twice as slow)
- The particular construct based on
CASEstatements performs extremely poorly on the following databases: PostgreSQL, DB2
On these databases, revoke authorizations are effectively unusable.
Also see the Configuration Options section on this page.