Keycloak User Management

Keycloak is an external system for user management. All user information including passwords is stored in this system. Keycloak also offers the option of integrating other user data systems, such as Microsoft Active Directory, Google or Facebook. Modern security mechanisms such as 2-factor authentication or Passkey can be added via configuration.

This means that Keycloak can be used as a secure central user management system in the IT infrastructure. All Virtimo products offer Keycloak integration.

For productive use, Virtimo AG recommends using Keycloak as a central identity provider.

Installation

The Keycloak server can be easily installed using the INUBIT installer. To do this, select the Keycloak installation set in the installer.

It is recommended to install Keycloak on a separate system. This system can then be secured according to the systems and applications accessing Keycloak.

Configuration - Keycloak

In order for INUBIT to integrate Keycloak as a user data system, the Keycloak server must be prepared for the INUBIT users to be managed.

Requirements

  • Keycloak server is installed and started

Goals

  • Create an administrative Keycloak account through which INUBIT can manage its users in Keycloak

  • Create at least the INUBIT user root in Keycloak so that you can log in to the INUBIT Process Engine using the Workbench

Keycloak – Realm and Client

In Keycloak, users are grouped into so-called realms. One application can usually access one realm. Different applications can also access the same or separate realms together.

Proceed as follows

  1. Set up an administrator account

  2. Create a new realm

  3. Configure realm settings

  4. Create three clients for the INUBIT components and assign the desired client IDs:

    • Process Engine (e.g. inubit_process_engine)

    • Workbench (e.g. inubit_workbench)

    • CLI (e.g. inubit_cli)

      The configured IDs must match the values under client-ids in keycloak.json.

  5. Enable the required flows/capabilities for each client:

    • Process Engine: Enable Direct Access Grants

    • Workbench: Enable Standard Flow (Authorization Code Flow)

    • CLI: Enable Standard Flow; optionally also Direct Access Grants for browser less login (headless systems)

  6. Set Client Authentication to Off (public client, no client secret) and leave Authorization disabled.

Keycloak – Account and Roles

INUBIT requires an administrative Keycloak account to be able to create, change and delete users. In addition, INUBIT also uses this account to manage the necessary user groups.

Create 2 separate accounts for administrative access and the INUBIT user root.

Requirements

Proceed as follows

Create technical user account:

Provide any username and a strong password.

  1. Create user and assign the following roles:

    • manage-users

    • manage-clients

    • manage-realm

Create INUBIT user account root:

Provide the username root and a strong password.

  1. Create role: System Administrator

  2. Create a user group: admin

  3. Create user: root with role System Administrator in group admin

Create role

  1. Go to Clients and select the corresponding INUBIT client according to your configuration (client-ids in keycloak.json, e.g. inubit_process_engine)

  2. Navigate to the Roles tab

  3. Click Create Role

  4. Name the role and click Save

Create a user group

  1. Navigate to Manage > Groups

  2. Click Create Group

  3. Provide a group name

  4. Save the group

Create user

  1. Create user:

    1. Go to Users and click Add users

    2. Create a new user with the desired name

  2. Assign user group

    1. Click Join Groups and select the group

    2. Click Create

  3. Set a strong user password

  4. Assign roles to the user:

    1. Select the user

    2. Go to the Role Mappings tab

    3. Click Assign roles

      The dialog Assign roles to <username> will be opened

    4. Filter by Clients and select the client where the role exists (e.g. the Process Engine client)

    5. Assign the desired role and click Assign.

Configuration - INUBIT

The appropriate Keycloak configuration must be stored on the INUBIT side so that INUBIT can communicate with the Keycloak.

Requirements

As of version 9.0.0, keycloak is the default value for the IdentityProvider property in the ibis.xml file.

Alternatively, inubit can be used as the identity provider. This option exists only for backward compatibility and is deprecated. It is strongly recommended to use Keycloak instead.

INUBIT - Set Keycloak as external identity provider

Requirements

  • INUBIT Process Engine is stopped

  • Keycloak server is running

Proceed as follows

  1. Open the file <inubit-installdir>/inubit/server/ibis_root/conf/ibis.xml

  2. Set the Identity Provider setting to Keycloak:

    <Property name="IdentityProvider">keycloak</Property>

  3. Set the Keycloak JSON file location:

    <Property name="IdentityProviderConfiguration">keycloak.json</Property>

  4. Save all changes in ibis.xml

  5. Open the file <inubit-installdir>/inubit/server/ibis_root/conf/keycloak_template.json and configure it as per details given in documentation section

  6. Save all changes in keycloak.json

  7. Start INUBIT process engine

  8. Start INUBIT Workbench

  9. Login with the root user

  • admin-group-priority: If true, the admin group will always be set as the primary group if the user is a member of it.

  • username/password: Can be left empty if the environment variables INUBIT_PE_KEYCLOAK_USERNAME and INUBIT_PE_KEYCLOAK_PASSWORD are set instead. Storing them in plain text is still supported for backwards compatibility but will be removed in the future.

  • client-ids: Allows separate client IDs for Process Engine, Workbench and CLI. Default values are shown in the example. This makes it possible to run multiple separate INUBIT environments in the same Keycloak realm by using different client IDs.

Canonical Keycloak URL and reachability

The value of auth-server-url in keycloak.json must be a single, canonical Keycloak URL that is reachable by both the Process Engine and the client applications (Workbench, CLI). All components must use the same hostname and scheme for keycloak; mixing different hostnames or raw IP addresses can lead to issuer mismatches and token validation failures.

If direct reachability requires different network paths (for example, the Process Engine talks to Keycloak via a private IP while external clients access it over the public internet), use DNS to keep a single canonical hostname. In such scenarios, configure split-horizon (split-view) DNS so that the canonical keycloak hostname resolves to an internal IP inside the private network and to a public IP for external clients. This keeps internal traffic local while preserving a consistent issuer and discovery endpoint for all parties.

Prefer DNS names over raw IPs whenever possible.

Token lifetime considerations

Token lifetimes determine how often users need to log in again. Short lifetimes can cause frequent logins, especially after standby phases, when access or refresh tokens have expired. The lifetimes can be configured at realm or client level in the Session settings: Important parameters are Client Session Idle, Client Session Max and SSO Session Max. Choosing appropriate values can improve user convenience without significantly reducing security.

Session lifetime considerations

Starting with INUBIT version 9.0, user interaction between the Workbench and the Process Engine is session-based when Keycloak is used as the identity provider. Each session has a limited lifespan and may expire. If a user remains inactive for an extended period, a pop-up appears in the Workbench prompting them to log in again.

This behavior depends on the validity period of the token issued by Keycloak. As a Keycloak administrator, you can modify the token validity period in the Keycloak realm settings.

Automatic session refresh

The token issued by Keycloak is, by default, sent along with a refresh token. This refresh token is used by the Workbench to automatically renew an expired token without requiring user interaction. A user needs to log in only in the rare case that the refresh token has also expired.

We recommend enabling the issuance of refresh tokens.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen