Skip to main content
Version: 8.8 (unreleased)

Configuration

As a Spring Boot application, the Orchestration Cluster supports standard Spring configuration methods.

The following configurations apply to all components within the Orchestration Cluster.

Environment variableDescriptionDefault value
CAMUNDA_SECURITY_AUTHENTICATION_METHODThe authentication method to use. Options: basic, oidc.basic
CAMUNDA_SECURITY_AUTHENTICATION_AUTHENTICATIONREFRESHINTERVALThe interval at which the memberships (groups, roles, tenants, component authorizations) are refreshed for logged in users.PT30S
CAMUNDA_SECURITY_AUTHENTICATION_UNPROTECTEDAPIIf the API can be used without authentication.false
CAMUNDA_SECURITY_AUTHORIZATIONS_ENABLEDIf authorizations are enabled.true
CAMUNDA_SECURITY_MULTITENANCY_CHECKSENABLEDEnables multi-tenancy checks. This requires the API to be protected.false
CAMUNDA_SECURITY_MULTITENANCY_APIENABLEDEnables the multi-tenancy API and UI independently from multi-tenancy checks.true
CAMUNDA_PERSISTENT_SESSIONS_ENABLEDStores session data in secondary storage so users stay logged in across cluster nodes.true
SPRING_PROFILES_ACTIVENote: This property will be deprecated as additional authentication methods become available.consolidated-auth

Explaining the authentication-refresh-interval property​

When a user logs in, we determine their associations at once (membership in roles, groups, tenants; application authorizations) and put them into the web session. When these associations change (e.g. user is removed from a group; authorizations change), then this is not reflected in this cached state until the next refresh interval comes. The default interval is 30 seconds but can be configured via camunda.security.authentication.authentication-refresh-interval property to a higher/lower value if needed considering a trade-off between the extra load for session refresh and the criticality of having sync authentications. The property format is ISO8601 duration, example: PT10M for 10 minutes. For more information on ISO8601 duration format, refer to ISO8601.

Initialization​

The following variables are used to set the identifier pattern of Identity-related entities and initialize users and mapping rules.

Environment variableDescriptionDefault value
CAMUNDA_SECURITY_INITIALIZATION_IDENTIFIERREGEXDefines the allowed identifier characters for Identity-related entities.^[a-zA-Z0-9_@.+-]+$
CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_USERNAMEThe username of the first user.
CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_PASSWORDThe password of the first user.
CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_NAMEThe name of the first user.
CAMUNDA_SECURITY_INITIALIZATION_USERS[0]_EMAILThe email address of the first user.
CAMUNDA_SECURITY_INITIALIZATION_MAPPINGRULES[0]_MAPPINGRULEIDThe id of the first mapping rule.
CAMUNDA_SECURITY_INITIALIZATION_MAPPINGRULES[0]_CLAIMNAMEThe claim of the first mapping rule.
CAMUNDA_SECURITY_INITIALIZATION_MAPPINGRULES[0]_CLAIMVALUEThe claim's value of the first mapping rule.
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_USERS[0]Users assigned to the <role> role.
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_GROUPS[0]Groups assigned to the <role> role.
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_CLIENTS[0]Clients assigned to the <role> role.
CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_<role>_MAPPINGRULES[0]Mapping rules assigned to the <role> role.

OIDC Configuration​

The following variables are used when oidc is selected as the authentication method.

Environment variableDescriptionDefault value
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_CLIENTIDThe client ID for OIDC authentication.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_CLIENTSECRETThe client secret for OIDC authentication.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_ISSUERURIThe issuer URI for OIDC authentication.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_REDIRECTURIThe redirect URI for OIDC authentication.http://localhost:8080/sso-callback
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_USERNAMECLAIMThe claim to use for the username in OIDC authentication.sub
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_GROUPSCLAIMThe claim to use for groups in OIDC authentication.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_CLIENTIDCLAIMThe claim to use for clients in OIDC authentication.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_AUDIENCESComma-separated list of audiences to validate in the OIDC token.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_SCOPEComma-separated list of scopes to request in the OIDC token.openid, profile
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_JWKSETURIThe authorization server’s JWK Set Uri can be configured.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_AUTHORIZATIONURIThe authorization server’s Authorization Uri can be configured.
CAMUNDA_SECURITY_AUTHENTICATION_OIDC_TOKENURIThe authorization server’s Token Uri can be configured.

HTTP Security Headers​

The HTTP security headers mechanism allows you to add response headers that enable browser-side protections against common web vulnerabilities. Each header addresses a specific security concern and can be configured independently.

Environment variableDescriptionRelated HeaderDefault value
CAMUNDA_SECURITY_HTTP_HEADERS_CACHE_CONTROL_ENABLEDEnables or disables cache prevention headers. Default values: Cache-Control: no-cache, no-store, max-age=0, must-revalidate, Pragma: no-cache, Expires: 0.Cache-Control, Pragma, Expirestrue
CAMUNDA_SECURITY_HTTP_HEADERS_CONTENT_SECURITY_POLICY_ENABLEDEnables or disables CSP headers.Content-Security-Policytrue
CAMUNDA_SECURITY_HTTP_HEADERS_CONTENT_SECURITY_POLICY_POLICY_DIRECTIVESCustom CSP directives. If not set, default values applied. If set, overrides default CSP policies.Content-Security-Policy
CAMUNDA_SECURITY_HTTP_HEADERS_CONTENT_SECURITY_POLICY_REPORT_ONLYEnables reporting mode without enforcing policies.Content-Security-Policy-Report-Onlyfalse
CAMUNDA_SECURITY_HTTP_HEADERS_CONTENT_TYPE_OPTIONS_ENABLEDEnables or disables X-Content-Type-Options header with nosniff value.X-Content-Type-Optionstrue
CAMUNDA_SECURITY_HTTP_HEADERS_CROSS_ORIGIN_EMBEDDER_POLICY_VALUERestricts embedded cross-origin resources. Options: REQUIRE_CORP, UNSAFE_NONE.Cross-Origin-Embedder-PolicyUNSAFE_NONE
CAMUNDA_SECURITY_HTTP_HEADERS_CROSS_ORIGIN_OPENER_POLICY_VALUEIsolates windows from cross-origin openers. Options: UNSAFE_NONE, SAME_ORIGIN_ALLOW_POPUPS, SAME_ORIGIN.Cross-Origin-Opener-PolicySAME_ORIGIN_ALLOW_POPUPS
CAMUNDA_SECURITY_HTTP_HEADERS_CROSS_ORIGIN_RESOURCE_POLICY_VALUEDeclares whether resources can be loaded cross-origin. Options: SAME_ORIGIN, SAME_SITE, CROSS_ORIGIN.Cross-Origin-Resource-PolicySAME_SITE
CAMUNDA_SECURITY_HTTP_HEADERS_FRAME_OPTIONS_ENABLEDEnables or disables X-Frame-Options header. Default value is SAMEORIGIN.X-Frame-Optionstrue
CAMUNDA_SECURITY_HTTP_HEADERS_FRAME_OPTIONS_MODEFrame options mode. Options: DENY, SAMEORIGIN.X-Frame-OptionsSAMEORIGIN
CAMUNDA_SECURITY_HTTP_HEADERS_HSTS_ENABLEDEnables or disables Strict-Transport-Security header.Strict-Transport-Securitytrue
CAMUNDA_SECURITY_HTTP_HEADERS_HSTS_INCLUDE_SUBDOMAINSApplies HSTS to all subdomains.Strict-Transport-Securityfalse
CAMUNDA_SECURITY_HTTP_HEADERS_HSTS_MAX_AGE_IN_SECONDSHSTS max age in seconds.Strict-Transport-Security31536000
CAMUNDA_SECURITY_HTTP_HEADERS_HSTS_PRELOADEnables HSTS preloading.Strict-Transport-Securityfalse
CAMUNDA_SECURITY_HTTP_HEADERS_PERMISSIONS_POLICY_VALUERestricts access to browser capabilities.Permissions-PolicyDisables all features by default
CAMUNDA_SECURITY_HTTP_HEADERS_REFERRER_POLICY_VALUEControls referrer information sharing. See available values below.Referrer-PolicySTRICT_ORIGIN_WHEN_CROSS_ORIGIN

Default Content Security Policy​

This is default value of the Content Security Policy when enabled:

default-src 'self';
base-uri 'self';
script-src 'self' https: *.chargebee.com *.mixpanel.com ajax.cloudflare.com static.cloudflareinsights.com;
script-src-elem 'self' cdn.jsdelivr.net ;
connect-src 'self' https: *.mixpanel.com cloudflareinsights.com *.appcues.net wss://api.appcues.net cdn.jsdelivr.net;
style-src 'self' https: 'unsafe-inline' cdn.jsdelivr.net *.googleapis.com *.chargebee.com;
img-src data: 'self';
form-action 'self';
frame-ancestors 'self';
frame-src 'self' https: *.chargebee.com blob: ;
object-src 'self' blob:;
font-src 'self' data: fonts.camunda.io cdn.jsdelivr.net;
worker-src 'self' blob:;
child-src;
script-src-attr 'none'.

CSRF Protection​

Cross-Site Request Forgery (CSRF) is a type of malicious exploit where unauthorized commands are transmitted from a user that the web application trusts. In a CSRF attack, an attacker tricks a victim's browser into making unwanted requests to a web application where the victim is authenticated.

For a comprehensive understanding of CSRF attacks and prevention methods, refer to the MDN Web Docs on CSRF.

How CSRF protection works in Camunda​

  • Token generation: A unique CSRF token is generated and stored in a secure, HTTP-only cookie named X-CSRF-TOKEN.
  • Token validation: For state-changing requests (POST, PUT, DELETE, etc.), the server validates that the CSRF token in the request header X-CSRF-TOKEN matches the one in the cookie.
  • Safe methods: GET, HEAD, TRACE, and OPTIONS requests are considered safe and don't require CSRF validation.

Configuration​

The following variables are used to configure CSRF protection. The CSRF protection only applies in the context of a session-based authentication. You don't need to provide CSRF tokens when using OIDC or Basic authentication methods.

Environment variableDescriptionDefault value
CAMUNDA_SECURITY_CSRF_ENABLEDEnables or disables CSRF protection.true
caution

Disabling CSRF protection is not recommended for production environments as it leaves your application vulnerable to cross-site request forgery attacks.

Protected vs unprotected paths​

Protected paths (require CSRF token)​

  • /api/** – API endpoints (except specifically excluded paths)
  • /v1/**, /v2/** – Versioned API endpoints
  • All state-changing operations (POST, PUT, DELETE, PATCH)

Unprotected paths (no CSRF token required)​

  • /actuator/** – Health and monitoring endpoints
  • /v2/license – Public license endpoint
  • /error – Error handling
  • Authentication endpoints (/login, /logout)
  • Safe HTTP methods (GET, HEAD, OPTIONS, TRACE)

Security considerations​

  • Always use HTTPS in production to prevent token interception.
  • Consider additional security headers configured in the security settings.
  • Regularly review and update the list of unprotected paths.