Run with Bonita Runtime

Deploy Bonita Process Designer alongside an existing Bonita Runtime so users sign in once through the Bonita portal session.

In Bonita Runtime mode, Bonita Process Designer reuses the session of a co-located Bonita Runtime instead of presenting its own login form. Users who are already authenticated in the Bonita portal reach the editor without signing in again, and their Bonita identity is mapped onto a Bonita Process Designer role.

This is one of three deployment modes. The application logic, data model, and editor behaviour are identical across all modes — only the way a request is authenticated changes.

When to use this mode

Choose Bonita Runtime mode when Bonita Process Designer is deployed next to an existing Bonita Runtime and you want a single sign-on experience driven by the Bonita portal session. Keep the default standalone mode (its own username/password login) when there is no Bonita Runtime to delegate to — see Install with Docker and Standalone installation.

Deploy Bonita Runtime mode same-site behind the Bonita reverse proxy — Bonita Process Designer and the Bonita portal served under one origin — and keep the CORS allow-list tight. The authorising credential is the Bonita portal’s session cookie, whose security attributes are set by Bonita and not by Bonita Process Designer, so a cross-site deployment needs additional CSRF protection.

How authentication is delegated

When this mode is active, Bonita Process Designer authenticates every request against the co-located Bonita Runtime instead of its own login form:

It reads the Bonita portal session cookie (JSESSIONID).
It validates that session against the Bonita Runtime and resolves the user’s name, display name, and membership role.
It maps that Bonita identity onto a Bonita Process Designer user, created automatically the first time the user is seen and re-synced (display name and role) on later visits.
Role-based access control then works exactly as in standalone mode, so roles and permissions apply unchanged.

The resolved identity is cached per session for a short window (60 seconds by default) to avoid calling the Bonita Runtime on every request. As a result, when a user logs out of the Bonita portal, their access to Bonita Process Designer ends within that cache window rather than instantly.

Checking the active mode

Bonita Process Designer exposes the active authentication mode at the public endpoint GET /auth/mode:

{ "mode": "bonita" }

The value is either standalone or bonita. The front-end uses this to decide whether to render the credential form — in Bonita mode the login form is hidden because the portal session already authenticates the user.

Role mapping

Bonita membership roles are mapped onto Bonita Process Designer roles:

A user whose Bonita role name matches BONITA_ADMIN_ROLE_NAME (case-insensitive, default administrator) is granted the Admin role.
Every other user is granted the role configured in BONITA_DEFAULT_ROLE (default Creator).

Groups remain Bonita Process Designer’s own model: the Bonita organisation tree is not synchronised. Create and manage groups in Bonita Process Designer as described in Manage groups.

Configuration

Set AUTH_MODE=bonita and point Bonita Process Designer at the Bonita Runtime REST API:

AUTH_MODE=bonita
BONITA_API_URL=http://localhost:8080/bonita

The full set of variables for this mode:

Variable Default Purpose

Variable	Default	Purpose
`AUTH_MODE`	`standalone`	Authentication strategy: `standalone` or `bonita`.
`BONITA_API_URL`	(required)	Base URL of the Bonita Runtime REST API, for example `http://localhost:8080/bonita`.
`BONITA_SESSION_CACHE_TTL_SECONDS`	`60`	How long a validated session is cached. A Bonita logout drops Bonita Process Designer access within this window.
`BONITA_ADMIN_ROLE_NAME`	`administrator`	Bonita role name (case-insensitive) that maps to the Bonita Process Designer Admin role.
`BONITA_DEFAULT_ROLE`	`Creator`	Bonita Process Designer role granted to users whose Bonita role is not the admin role. Set it to `Reader`, `Creator`, or `Admin`.
`BONITA_DEV_USER_HEADERS`	`false`	Development only. Trusts user identity request headers instead of calling Bonita. Never enable in production.

AUTH_MODE

standalone

Authentication strategy: standalone or bonita.

BONITA_API_URL

(required)

Base URL of the Bonita Runtime REST API, for example http://localhost:8080/bonita.

BONITA_SESSION_CACHE_TTL_SECONDS

60

How long a validated session is cached. A Bonita logout drops Bonita Process Designer access within this window.

BONITA_ADMIN_ROLE_NAME

administrator

Bonita role name (case-insensitive) that maps to the Bonita Process Designer Admin role.

BONITA_DEFAULT_ROLE

Creator

Bonita Process Designer role granted to users whose Bonita role is not the admin role. Set it to Reader, Creator, or Admin.

BONITA_DEV_USER_HEADERS

false

Development only. Trusts user identity request headers instead of calling Bonita. Never enable in production.

See Configuration reference for the variables shared across all deployment modes.

Testing without a Bonita Runtime

For local development without a real Bonita Runtime, set BONITA_DEV_USER_HEADERS=true and supply the identity through request headers:

curl -H "X-Bonita-User-Name: walter" \
     -H "X-Bonita-User-Display-Name: Walter Bates" \
     -H "X-Bonita-User-Role: administrator" \
     http://localhost:3000/auth/session

BONITA_DEV_USER_HEADERS bypasses session validation entirely. Use it only on a developer machine and never in any shared or production environment.

Verify the integration

With a real Bonita Runtime available:

Start Bonita Process Designer with AUTH_MODE=bonita and BONITA_API_URL pointing at the Runtime.
Log in to the Bonita portal in your browser to establish a session.
Open Bonita Process Designer and confirm you land authenticated, without a separate login.
Confirm a Bonita admin-role user receives the Admin role and a regular user receives the role set in BONITA_DEFAULT_ROLE.
Log out of the Bonita portal and confirm Bonita Process Designer access is denied within the cache window.