Mapping rules
Mapping rules are used to dynamically manage access control by connecting your Identity Provider and mapping claims from a JWT access token to Identity entities in Camunda 8.
Support for mapping rules in SaaS and Self-Managed
In Camunda 8 SaaS, mapping rules are not configurable. They are automatically applied based on your organization's setup.
In Camunda 8 Self-Managed, you may need to configure mapping rules in two components:
-
Orchestration Cluster Identity: Manage permissions within an orchestration cluster. Use mapping rules to assign users to user groups and roles, grant authorizations, and associate them with specific tenants.
- Mapping rules are available for Orchestration Cluster Identity only when using OIDC-based authentication. They do not apply to other authentication methods, such as basic authentication.
-
Management Identity: Manage access to components like Web Modeler, Console, and Optimize. Mapping rules in Management Identity assign users to roles and tenants, granting access to those components. To learn more, see the guide on managing mapping rules in Management Identity.
How to use mapping rules
To use mapping rules, you must be familiar with the structure of the JWT access tokens that your OIDC provider issues to clients.
A mapping rule has the following properties:
- Claim name: The name of a (nested) claim or a JSONPath expression.
- Claim value: The expected value of the claim. The mapping rule takes effect only if this value is present in a JWT access token.
Using a mapping rule is a two-step process:
- Create the mapping rule – Define how Camunda identifies a match between a JWT claim and the rule.
- Assign the mapping rule – Apply it to a group, role, authorization, or tenant.
Assume the following payload of an access token issued by your Identity Provider (IdP):
{
"sub": "1234567890",
"name": "John Doe",
"isAdmin": true,
"orggroups": ["acct", "finance"],
"iat": 1516239022
}
To make any user a member of the admin role when their isAdmin claim is set to true, first define a mapping rule as follows:
- Claim name:
isAdmin - Claim value:
true
Then, assign the mapping rule to the admin role.
To make any member of the organizational group acct a member of the Orchestration Cluster group accounting, define a mapping rule as follows:
- Claim name:
orggroups - Claim value:
acct
Then, assign the mapping rule to the accounting group.
In this case, the mapping rule matches against an array of objects. Depending on the JWT structure, a claim value is matched using equals or in semantics.
References
For more details on configuring mapping rules in a Self-Managed environment, see: