Skip to main content
Version: 8.8 (unreleased)

Initial setup

Identity is included by default with any Orchestration cluster. Within an Orchestration cluster, Identity provides unified, cluster-level identity management and authorization.

Identity is available via Helm install and for local development via Camunda 8 Run.

note

The following guides cover Identity configuration in Self-Managed environments. For information on using and managing Identity, see the user guides.

Initial configuration

Using the default setup for Camunda 8 Run will result in a cluster with:

  1. Web application login enabled
  2. API authentication disabled
  3. Authorizations disabled
  4. An initial user with username/password: demo / demo
  5. An admin role with full permissions, applied to the demo user

To modify this initial configuration, define your custom values in application.yaml, and pass this file at startup using the --config flag. See this section for details.

note

In Helm installations, API authentication and authorization are enabled by default. You can adjust these settings in application.yaml or using environment variables.

Configure initial users

If users are managed within the Orchestration cluster (i.e., without an external Identity Provider), you can create an initial user in two ways:

  • Through the web application UI
  • Through configuration

Option 1: Create an initial admin user in the UI

If no admin user exists, the Orchestration cluster web applications display a screen for creating the initial user:

identity-create-initial-user

This user will be assigned to the admin role and granted all permissions in the system. Once an admin user exists, this screen is no longer shown.

Option 2: Define initial users via configuration

To configure initial users programmatically, include the relevant definitions in your application.yaml or environment variables.

CAMUNDA_SECURITY_INITIALIZATION_USERS_0_USERNAME=<Your chosen username>
CAMUNDA_SECURITY_INITIALIZATION_USERS_0_PASSWORD=<Your chosen password>
CAMUNDA_SECURITY_INITIALIZATION_USERS_0_NAME=<The name of the first user>
CAMUNDA_SECURITY_INITIALIZATION_USERS_0_EMAIL=<The email address of the first user>

# add more users as desired by repeating the variables with an incremented index,
# like CAMUNDA_SECURITY_INITIALIZATION_USERS_1_USERNAME
note

By default, a user is not assigned to any roles and therefore has no permissions. See the next section to learn how to assign a user to a role via configuration.

Assign users, clients, groups, or mapping rules to roles via configuration

The Orchestration cluster provides a number of built-in roles with predefined permissions for easier setup.

To assign users, clients, groups, or mapping rules to roles, add the appropriate properties to your application.yaml or set them as environment variables.

CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_USERS_0=<username>
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_CLIENTS_0=<client id>
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_GROUPS_0=<group id>
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_MAPPINGS_0=<mapping id>

# add more members as desired by repeating the variables with an incremented index,
# like CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_USERS_1

Replace <role> with the ID of the role you want to configure.

Here is an example how to configure a user demo to become a member of the admin role:

CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_ADMIN_USERS_0=demo

You can assign a user to multiple roles by listing them in the respective section of each role.

Enable API authentication and authorizations

In Camunda 8 Run installations, basic authentication is enabled on the Camunda web applications, but the API is unprotected, and authorizations are disabled. API protection and authorizations can both be enabled by modifying your application.yaml or environment variables:

CAMUNDA_SECURITY_AUTHENTICATION_UNPROTECTED-API=false
CAMUNDA_SECURITY_AUTHORIZATIONS_ENABLED=true
note

To enable authorizations, API protection must also be enabled.

Basic authentication credentials are then required when making API requests, as in the following:

curl --request POST 'http://localhost:8080/v1/process-definitions/search'  \
-u demo:demo \
--header 'Content-Type: application/json' \
--data-raw '{}'