We will walk you through configuring a minimal Keycloak setup to efficiently manage users, roles, and applications. Keycloak is an open-source Identity and Access Management (IAM) solution that makes it easy to secure applications and services with little to no coding.

​
Prerequisites

Before you begin, ensure you have the following:
  • Keycloak installed
  • Administrative access to the Keycloak server
  • Basic understanding of IAM concepts
Recommended keycloak version: 22.x
To configure a minimal required Keycloak setup, in this guide we will covere the following steps:
1

Create a new realm

Define available roles and realm-level roles assigned to new users.
2

Create/import user roles and groups

3

Create new users

4

Add clients

Configure the client authentication, valid redirect URIs, and enable the necessary flows.
5

Add mappers

6

Add service accounts

Set up admin, task management, process engine and scheduler service accounts.
Before starting, if you need further information or a broader understanding of Keycloak, refer to the official Keycloak documentation:

Keycloak documentation

​
Creating a new realm

A realm is a space where you manage objects, including users, applications, roles, and groups. Creating a new realm is the first step in setting up Keycloak. Follow the steps below to create a new realm in Keycloak:
1

Log in to the Keycloak Admin Console

Log in to the Keycloak Admin Console using the appropriate URL for your environment (e.g., QA, development, production).
2

Create Realm

In the top left corner dropdown menu, click Create Realm. If you are logged in to the master realm, this dropdown menu lists all the realms created.
If you are logged in to the master realm, this dropdown menu lists all the realms created.
3

Enter Realm Details

Enter a realm name and click Create.
4

Configure Realm Settings

Configure the Realm Settings, such as SSO Session Idle and Access Token Lifespan, according to your organization’s needs:Sessions -> SSO Session idle: Set to 30 Minutes (recommended).
Tokens -> Access Token Lifespan: Set to 30 Minutes (recommended).
Common Pitfalls:
  • Ensure that the realm name is unique within your Keycloak instance.
  • Double-check session idle and token lifespan settings to align with your security requirements.

​
Creating/importing user groups and roles

User groups and roles are essential for managing user permissions and access levels within a realm. You can either create or import user groups into a realm.
1

Download and Run the Import Script

To import a super admin group with the necessary default user roles, download and run the provided script.

Download script

Instructions:
  • Unzip the downloaded file.
  • Open a terminal and navigate to the unzipped folder.
  • Run the script using the appropriate command for your operating system.
2

Add Admin User to Group

After importing, add an admin user to the group and assign the necessary roles.
3

Validate imported roles

Check the default roles to ensure correct import:

Default Roles

Common Pitfalls:
  • Ensure the script has the necessary permissions to run on your system.
  • Verify that the roles and groups align with your organizational structure.

​
Creating new users

Creating new users is a fundamental part of managing access within Keycloak. Follow these steps to create a new user in a realm and generate a temporary password:
1

Navigate to Users

In the left menu bar, click Users to open the user list page.
2

Add a New User

On the right side of the empty user list, click Add User.Fill in the user details and set Email Verified to Yes.
3

Assign User to Group

In the Groups section, search for a group, in our case: FLOWX_SUPER_USERS and click Join.
4

Set Temporary Password

Save the user, go to the Credentials tab, and set a temporary password. Ensure the Temporary checkbox is checked.
Common Pitfalls:
  • Ensure that the email address is valid and correctly formatted.
  • Set the temporary password policy according to your organization’s security requirements.

​
Adding clients

A client represents an instance of an application and is associated with a specific realm.

​
Adding an OAuth 2.0 client

We’ll add a client named flowx-platform-authenticate, which will be used for login, logout, and refresh token operations by web and mobile apps.
1

Navigate to Clients

Click Clients in the top left menu, then click Create client.
2

Configure General Settings

In the General Settings tab configure the following properties:
  • Set a client ID to {your-client-name}-authenticate.
  • Set the Client type to OpenID Connect.
3

Configure Capability Config

Now click Next and configure the Capability config details:
  • Enable Direct Access Grants.
  • Enable Implicit Flow Enabled.
4

Set Valid Redirect URIs

Click Next and configure Login settings:
  • Set Valid redirect URIs, specifying a valid URI pattern that a browser can redirect to after a successful login or logout, simple wildcards are allowed.
5

Configure Additional Settings

After creating the client, scroll down in the Settings tab and configure additional settings - Logout Settings:
  • Backchannel Logout Session Required: Toggle OFF.
  • Front Channel Logout: Toggle OFF.
6

Add Mappers

Add mappers to {your-client-name}-authenticate client.
For instructions on adding mappers and understanding which mappers to add to your clients, refer to the section on Adding Protocol Mappers.

​
Adding an Authorizing client

To authorize REST requests to microservices and Kafka, create and configure the {your-client-name}-platform-authorize client.
1

Create the Client

Enter the client ID ({your-client-name}-platform-authorize).Set Client type to OpenID Connect.
2

Configure Capability Config

Client Authentication: Toggle ON
This setting defines the type of the OIDC client. When enabled, the client type is set to “confidential access.” When disabled, it is set to “public access”.
Disable Direct Access Grants.
3

Set Valid Redirect URIs

Valid Redirect URIs: Populate this field with the appropriate URIs. Save the configuration.
4

Configure Additional Settings

After creating the client, scroll down in the Settings tab and configure additional settings - Logout Settings:
  • Backchannel Logout Session Required: Toggle OFF.
  • Front Channel Logout: Toggle OFF.
Once you have configured these settings, the {your-client-name}-platform-authorize client will be created and can be used to authorize REST requests to microservices and Kafka within your application.

​
Example configuration for microservices

Below is an example of a minimal configuration for microservices using OAuth2 with the {your-client-name}-platform-authorize client: 
security:
  type: oauth2 #Specifies the security type as OAuth2.
  basic:
    enabled: false #Disables basic authentication.
  oauth2:
    base-server-url: http://localhost:8080 #Sets the base server URL for the Keycloak server
    realm: flowx #Specifies the Keycloak realm
    client:
      access-token-uri: ${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token
      client-id: your-client-name-platform-authorize
      client-secret: CLIENT_SECRET
    resource:
      user-info-uri: ${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/userinfo
Configuration KeyValue/ExampleDescription
security.typeoauth2Specifies the security type as OAuth2.
security.basic.enabledfalseDisables basic authentication.
security.oauth2.base-server-urlhttp://localhost:8080Sets the base server URL for the Keycloak server.
security.oauth2.realmflowxSpecifies the Keycloak realm.
security.oauth2.client.access-token-uri${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/tokenDefines the URL for obtaining access tokens.
security.oauth2.client.client-idyour-client-name-platform-authorizeSets the client ID for authorization.
security.oauth2.client.client-secretCLIENT_SECRETProvides the client secret for authentication.
security.oauth2.resource.user-info-uri${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/userinfoSpecifies the URL for retrieving user information.

​
Adding protocol mappers

Protocol mappers in Keycloak allow you to transform tokens and documents, enabling actions such as mapping user data into protocol claims and modifying requests between clients and the authentication server. This provides greater customization and control over the information contained in tokens and exchanged during authentication processes.
To enhance your clients’ functionality, add the following common mappers:
The mappers we use can also be configured to control the data returned by the /userinfo endpoint, in addition to being included in tokens. This capability is a feature that not all Identity Providers (IDPs) support.
By incorporating these mappers, you can further customize and enrich the information contained within your tokens, ensuring they carry the necessary data for your applications.

​
Group Membership mapper

Steps to add a Group Membership mapper:
1

Navigate to Clients

From the Keycloak admin console, go to Clients and select your desired client.
2

Select Client Scopes

In the client settings, click on Client Scopes.Select the dedicated client scope: {your-client-name}-authenticate-dedicated to open its settings.
3

Client Scope

Make sure the Mappers tab is selected within the dedicated client scope.
4

Add a New Mapper

Click Add Mapper. From the list of available mappers, choose Group Membership.
5

Provide Mapper Details

Name: Enter a descriptive name for the mapper to easily identify its purpose, for example realm-groups.Token Claim Name: Set the token claim name, typically as groups, for including group information in the token.Add to ID Token: Toggle OFF.
By configuring the group membership mapper, you will be able to include the user’s group information in the token for authorization purposes.

​
User Attribute mapper

To include custom attributes such as business filters in the token claim, follow these steps to add a user attribute mapper:
1

Navigate to Client Scopes

From the Keycloak admin console, go to Clients and select your desired client.Click on Client Scopes and choose {your-client-name}-authenticate-dedicated to open its settings.Ensure the Mappers tab is selected.
2

Add a New Mapper

Click Add mapper. From the list of available mappers, select User Attribute.
3

Provide Mapper Details

  • Mapper Type: Select User Attribute.
  • Name: Enter a descriptive name for the mapper, such as “Business Filters Mapper”.
  • User Attribute: Enter businessFilters.
  • Token Claim Name: Enter attributes.businessFilters.
  • Add to ID Token: Toggle OFF.
  • Multivalued: Toggle ON.
By adding this user attribute mapper, the custom attribute “businessFilters” will be included in the token claim under the name “attributes.businessFilters”. This enables you toto access and utilize business filters information within your application. For more information about business filters, refer to the following section:

Business filters

​
User realm role mapper

To add a roles mapper to the {your-client-name}-authenticate client, so roles will be available in the OAuth user info response, follow these steps:
1

Navigate to Client Scopes

From the Keycloak admin console, go to Clients and select your desired client.Click on Client Scopes and choose {your-client-name}-authenticate-dedicated to open its settings.Ensure the Mappers tab is selected.
2

Add a New Mapper

Click Add Mapper. From the list of available mappers, select User Realm Role.
3

Provide Mapper Details

  • Name: Enter a descriptive name for the mapper, such as “Roles Mapper”.
  • Mapper Type: Select User Realm Role.
  • Token Claim Name: Enter roles.
  • Add to ID Token: Toggle OFF.
  • Add to access token: Toggle OFF.
By adding this roles mapper, the assigned realm roles of the user will be available in the OAuth user info response under the claim name “roles”. This allows you to access and utilize the user’s realm roles within your application.
Please note that you can repeat these steps to add multiple roles mappers if you need to include multiple realm roles in the token claim.

​
Examples

​
Login

To request a login token: 
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=admin@flowx.ai' \
--data-urlencode 'password=password' \
--data-urlencode 'client_id= your-client-name-authenticate'

​
Refresh token

To refresh an existing token: 
curl --location --request POST 'http://localhost:8080/realms/flowx/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id= your-client-name-authenticate' \
--data-urlencode 'refresh_token=ACCESS_TOKEN'

​
User info

To retrieve user information: 
curl --location --request GET 'localhost:8080/realms/flowx/protocol/openid-connect/userinfo' \
--header 'Authorization: Bearer ACCESS_TOKEN' \

​
Adding service accounts

What is a service account?A service account grants direct access to the Keycloak API for a specific component. Each client can have a built-in service account that allows it to obtain an access token.
To use this feature you must enable the Client authentncation (access type) for your client. When you do this, the Service Accounts Enabled switch will appear.

​
Admin service account

The admin service account is used by the admin microservice to connect with Keycloak, enabling user and group management features within the FlowX.AI Designer. Steps to add an Admin service account:
1

Create the Client

Navigate to Clients and select Create client.Enter a Client ID for your new client.
2

Configure Capability Config

  • Enable Client authentication (access type).
  • Disable Standard flow.
  • Disable Direct access grants.
  • Enable Service accounts roles.
3

Configure Additional Settings

After creating the client, scroll down in the Settings tab and configure additional settings - Logout Settings:
  • Backchannel Logout Session Required: Toggle OFF.
  • Front Channel Logout: Toggle OFF.
4

Assign Roles to Service Account

In the newly created client, navigate to the Service accounts roles tab.
Click Assign role and in the Filter field, select Filter by clients.
Assign the necessary roles to the admin service account based on the required access scopes, such as:
  • manage-realm
  • manage-users
  • query-users
In the end, you should have something similiar to this:
Ensure you have created a realm-management client to include the necessary client roles.
The admin service account does not require mappers as it doesn’t utilize roles. Service account roles include client roles from realm-management.
For more detailed information on admin access rights, refer to the following section:

Configuring access rights for admin

​
Task Management service account

The task management service account facilitates process initiation and enables the use of the task management plugin (requiring the FLOWX_ROLE and role mapper), and access data from Keycloak. Steps to Add a Task Management service account:
1

Create the Service Account

Follow steps 1-3 as in the Admin Service account configuration: Admin service account.
2

Assign Necessary Roles

Assign the necessary service accounts client roles to the Task Management plugin service account based on the required access scopes, such as:
  • view-realm
  • view-users
The task management plugin service account requires a realm roles mapper to function correctly. Make sure to configure this to ensure proper operation.
In the end, you should have something similiar to this:
3

Add a Realm Roles Mapper

In the newly created task management plugin service account, select Client Scopes:Click on {your-client-name}-service-account to open its settings.
Ensure the Mappers tab is selected within the dedicated client scope.
Click Add mapper. From the list of available mappers, select User Realm Role.
4

Configure the Mapper

Name: Enter a descriptive name for the mapper to easily identify its purpose, for example realm-roles.Token Claim Name: Set it to roles.Disable Add to ID token.
Click Save.
5

Add the Service Account Realm Role

Assign the FLOWX_ROLE service account realm role (used to grant permissions for starting processes).
The FLOWX_ROLE is used to grant permissions for starting processes in the FlowX.AI Designer platform. By default, this role is named FLOWX_ROLE, but its name can be changed from the application configuration of the Engine by setting the following environment variable:FLOWX_PROCESS_DEFAULTROLES
For more information about task management plugin access rights, check the following section:

Configuring access rights for Task Management

​
Process engine service account

The process engine requires a process engine service account to make direct calls to the Keycloak API.
This service account is also needed to be able to use Start Catch Event node.
To create the process engine service account: To assign the necessary service account roles:
This service account does not require service account client roles. It needs a realm role (to be able to start process instances) and realm-roles mapper.
  1. Add the FLOWX_ROLE service account realm role (used to grant permissions for starting processes):
In the end, you should have something similiar to this:
  1. Add a realm-roles mapper:

​
Scheduler service account

This service account is used for Start Timer Event node. The registered timers in the scheduler require sending a process start message to Kafka. Authentication is also necessary for this operation.
The configuration is similiar to the process engine service account:
  • Assign the FLOWX_ROLE as service account role (this is needed to run process instances).
  • Add a realm-roles mapper (as shown in the example for process-engine service account).
By following these steps, you will have a minimal Keycloak setup to manage users, roles, and applications efficiently. For more detailed configurations and advanced features, refer to the official Keycloak documentation.