Skip to main content
Version: 8.8 (unreleased)

Identity in Self-Managed

Identity is included by default with the Orchestration Cluster in all Self-Managed installation methods. Within a cluster, Identity provides unified, cluster-level identity management and authorization.

info

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

Initial setup​

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

  1. Web components 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 the 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

Configure initial users​

If users are managed within the Orchestration Cluster (that is, without an external Identity Provider), you can create an initial user in three ways:

warning

After completing the initial setup, ensure at least one user remains assigned to the admin role.
If no admin user exists, a third party could create a new admin account and gain full access.

Option 1: Create an initial admin user in Orchestration Cluster UI​

If no admin user exists, the orchestration cluster web applications show 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: Create an initial admin user via the Setup endpoint of Orchestration Cluster REST API​

You can create the first admin user by calling the Setup API endpoint:

POST /v2/setup/user (API documentation)

with the following JSON request body:

{
  "username": "<your chosen username>",
  "password": "<your chosen password>",
  "name": "<the user's full name>",
  "email": "<the user's email address>"
}

This endpoint is only available if no user is assigned to the admin role.

Option 3: Define initial users via the 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 following 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 for the Orchestration Cluster web components, 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 '{}'