Authorization Service
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.
Example
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.
By contrast, if the Camunda Rest API is directly exposed over the network to a Javascript application, then a malicious user, once authenticated, can send a request to the server querying all tasks, even the ones that are not assigned to this user. In this case, authorization needs to be turned on to ensure the user only sees the tasks which he is authorized to see, regardless of the query parameters.
Basic Principles
Authorizations
An Authorization assigns a set of Permissions to an identity to interact with a given Resource.
Examples
- 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.
Identities
Camunda Platform 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.
Permissions
A Permission defines the way an identity is allowed to interact with a certain resource.
The basic permissions available in the engine are:
- None
- All
- Read
- Update
- Create
- Delete
- Access
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
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/* |
Authorization | 4 | Authorization Id |
Batch | 13 | Batch Id |
Decision Definition | 10 | Decision Definition Key |
Decision Requirements Definition | 14 | Decision Requirements Definition Key |
Deployment | 9 | Deployment Id |
Filter | 5 | Filter Id |
Group | 2 | Group Id |
Group Membership | 3 | Group Id |
Process Definition | 6 | Process Definition Key |
Process Instance | 8 | Process Instance Id |
Task | 7 | Task Id |
Historic Task | 19 | Historic Task Id |
Historic Process Instance | 20 | Historic Process Instance Id |
Tenant | 11 | Tenant Id |
Tenant Membership | 12 | Tenant Id |
User | 1 | User Id |
Report | 15 | Report Id |
Dashboard | 16 | Dashboard Id |
User Operation Log Category | 17 | User Operation Log Entry Category |
Note: The Resource Id should be ‘*’ when you create new authorization with CREATE permissions only.
Authorization Type
There are three types of authorizations:
Authorization type | Description | Integer representation |
---|---|---|
Global Authorization (AUTH_TYPE_GLOBAL ) |
Ranges over all users and groups (userId = ANY ) and are usually used for fixing the "base" permission for a resource. |
0 |
Grant Authorization (AUTH_TYPE_GRANT ) |
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 (AUTH_TYPE_REVOKE ) |
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.
Authorization Precedence
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
authorizationEnabled
is set totrue
(default value isfalse
). - 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:
Read | Update | Create | Delete | |
---|---|---|---|---|
Authorization | X | X | X | X |
Batch | X | X | X | X |
Decision Definition | X | X | ||
Decision Requirements Definition | X | |||
Deployment | X | X | X | |
Filter | X | X | X | X |
Group | X | X | X | X |
Group Membership | X | X | ||
Process Definition | X | X | X | |
Process Instance | X | X | X | X |
Task | X | X | X | X |
Historic Task | X | |||
Historic Process Instance | X | |||
Tenant | X | X | X | X |
Tenant Membership | X | X | ||
User | X | X | X | X |
User Operation Log Category | X | X | 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:
- 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 | |
---|---|---|---|---|
Claim | X | X | ||
Complete | X | X | ||
Add Candidate User | X | X | ||
Delete Candidate User | X | X | ||
Set Assignee | X | X | ||
Set Owner | X | X | ||
Add Candidate Group | X | X | ||
Delete Candidate Group | X | X | ||
Save Task | 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
- Suspend Instance
- Update Instance Variable
- Update Task Variable
- Migrate Instance
- Delete Instance
- Read History
- Delete History
- Update 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
- Suspend
- 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
- Create Batch Set Removal Time
The specific “Create …” permission has higher priority than the general “Create” permission.
Default Read Variable Permissions
When the 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 process and standalone tasks)
In case of Historic Tasks
- Read Variable (only enforced when Historic Instance Permissions are enabled)
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)
Application Permissions
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):
admin
cockpit
tasklist
optimize
*
(Any / All)
User Operation Log Permissions
The resource “User Operation Log Category” controls whether a user can access user operation log entries from the specified categories. Out of the box, it can be granted for the following categories (resource ids):
TaskWorker
Admin
Operator
*
(Any / All)
Historic Instance Permissions
The resources control whether a user can read the history related to a specific instance.
Compared to runtime permissions, historic permissions are not immediately removed when the related instance has been finished. The Removal-Time-based History Cleanup Strategy removes historic permissions at a later point.
You can enable the permissions with the help of a process engine configuration flag:
<property name="enableHistoricInstancePermissions">true</property>
The feature is disabled by default because of two reasons:
- When enabled, the SQL queries are more complex because additional authorization checks are performed. More complex queries may degrade the performance.
- When enabled and an Identity Link is added to a Task, the respective User or Group is authorized to read the associated history (e. g. for the Task, Variable, or Identity Link History). For Camunda Platform versions <= 7.12, the history is not readable in this case.
Historic Task Permissions
When permission is granted to a Historic Task, you can use the following queries to retrieve the entities related to the Historic Task:
- Historic Task Instance Query
- Historic Variable Instance Query
- Historic Detail Query
- Identity Link Log Query
- User Operation Log Query
Historic Process Instance Permissions
When permission is granted to a Historic Process Instance, you can use the following queries to retrieve the entities related to the Historic Process Instance:
- Historic Process Instance Query
- Historic Activity Instance Query
- Historic Task Instance Query
- Historic Variable Instance Query
- Historic Detail Query
- Identity Link Log Query
- Historic Incident Query
- Job Log Query
- External Task Log Query
- User Operation Log Query
Administrators
Camunda Platform 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 Platform 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.
LDAP
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:
Property | Description |
---|---|
administratorUserName |
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. |
administratorGroupName |
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. |
Configuration Options
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 false
.
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 false
.
Check Revoke Authorizations
The configuration option authorizationCheckRevokes
controls whether authorization checks take into account authorizations of type Revoke
.
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.
Performance Considerations
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
CASE
statements 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.