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

INUBIT can integrate Keycloak as a user data system.

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

Set up an administrator account.
Create a new realm.
Configure realm settings.
Create a client: inubit-client
Enable the following capability config on the client:
- Client authentication
- Authorization
- Standard flow
- Direct access grant
Adjust the access settings for the client.

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

Realm and client have been created in Keycloak

Proceed as follows

Create administrative user account:

Provide any username and a strong password.

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.

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

Create role

Go to clients and select the INUBIT specific client (inubit-client)
Navigate to the Roles tab
Click Create Role
Name the role and click Save

Create user group

Navigate to Manage > Groups
Click Create Group
Provide a group name
Save the group.

Create user

Create user:
1. Go to Users and click Add users
2. Create a new user with the desired name
Assign user group
1. Click Join Groups and select the group
2. Click Create
Set a strong user password
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 inubit-client client and assign the desired role.
5. Add all required Keycloak roles 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

Keycloak server is installed and started
A realm and a client have been set up in Keycloak
An administrative account has been created in Keycloak
An root user account has been created in Keycloak
INUBIT can access Keycloak (via network)

INUBIT - Download Keycloak Client Configuration

Log in into Keycloak
Go to Clients and select the created client (inubit-client)
Click Action and select Download adaptor configs
Select Keycloak OIDC JSON to download the JSON file
Save the downloaded file under <inubit-installdir>/inubit/server/ibis_root/conf/keycloak.json

INUBIT - Set Keycloak as external identity provider

Requirements

INUBIT Process Engine is stopped
Keycloak server is running

Proceed as follows

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

Set the Identity Provider setting to keycloak:

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

Set the Keycloak JSON file location:

<!--
    If the json file is located under
    <inubit-installdir>/inubit/server/ibis_root/conf/keycloak.json
-->
<Property name="IdentityProviderConfiguration">keycloak.json</Property>

Save all changes in ibis.xml
Open the Keycloak JSON file <inubit-installdir>/inubit/server/ibis_root/conf/keycloak.json

Add username and password of the administrative account

Sample of a Keycloak configuration JSON file

{
    "realm": "<realm_name_created_for_inubit>",
    "auth-server-url": "<keycloak_server_url>",
    "ssl-required": "none",
    "resource": "<client_name_created_for_inubit>",
    "verify-token-audience": true,
    "credentials": {
      "secret": "<inubit_client_secret>"
    },
    "username": "<administrative_account_username>",
    "password": "<administrative_account_password>",
    "use-resource-role-mappings": true,
    "confidential-port": 0
}

Save all changes in keycloak.json
Start INUBIT process engine
Start INUBIT Workbench
Login with the root user

Impersonation - Log in with another user

INUBIT supports the feature of logging in with another user without knowing their password.

When using Keycloak, the functionality Impersonation must be activated in Keycloak.

There are no users in Keycloak yet

Log in to Keycloak as an administrator
Switch to the roles via Realm settings > User registration > Assign roles (realm default roles)
Set the role impersonation as the default role for every new user that is created
Save your changes

The role impersonation is now automatically added to every newly created user.

Existing users are not changed.

All users already exist in Keycloak

Log in to Keycloak as an administrator
Go to users
Select the impersonation role for each user you want to take over
Save your changes