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

  1. Set up an administrator account.

  2. Create a new realm.

  3. Configure realm settings.

  4. Create a client: inubit-client

  5. Enable the following capability config on the client:

    • Client authentication

    • Authorization

    • Standard flow

    • Direct access grant

  6. 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

Proceed as follows

Create administrative 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 user group: admin

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

Create role

  1. Go to clients and select the INUBIT specific client (inubit-client)

  2. Navigate to the Roles tab

  3. Click Create Role

  4. Name the role and click Save

Create 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 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

INUBIT - Download Keycloak Client Configuration

  1. Log in into Keycloak

  2. Go to Clients and select the created client (inubit-client)

  3. Click Action and select Download adaptor configs

  4. Select Keycloak OIDC JSON to download the JSON file

  5. 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

  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:

    <!--
        If the json file is located under
        <inubit-installdir>/inubit/server/ibis_root/conf/keycloak.json
    -->
    <Property name="IdentityProviderConfiguration">keycloak.json</Property>
  4. Save all changes in ibis.xml

  5. Open the Keycloak JSON file <inubit-installdir>/inubit/server/ibis_root/conf/keycloak.json

  6. 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
    }
  7. Save all changes in keycloak.json

  8. Start INUBIT process engine

  9. Start INUBIT Workbench

  10. 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

  1. Log in to Keycloak as an administrator

  2. Switch to the roles via Realm settings > User registration > Assign roles (realm default roles)

  3. Set the role impersonation as the default role for every new user that is created

  4. 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

  1. Log in to Keycloak as an administrator

  2. Go to users

  3. Select the impersonation role for each user you want to take over

  4. Save your changes