Configuring an IAM solution (Keycloak)

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 setup

To configure a minimal required Keycloak setup, in this guide we will covere the following steps:

Before starting, if you need further information or a broader understanding of Keycloak, refer to the official 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:

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.

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:

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.

​

Adding an Authorizing client

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

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

​

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:

• Group Membership mapper (realm-groups)
  • Maps user groups to the authorization token.
• User Attribute mapper (business filter mapper)
  • Maps custom attributes, for example, mapping the businessFilters list, to the token claim.
• User Realm role (realm-roles)
  • Maps a user’s realm role to a token claim.

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:

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:

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:

​

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:

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.

​

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

​

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:

For more detailed information on admin access rights, refer to the following section:

​

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:

For more information about task management plugin access rights, check the following section:

​

Process engine service account

The process engine requires a process engine service account to make direct calls to the Keycloak API.

To create the process engine service account:

• 1-3: Follow the same steps as in the Admin Service Account Configuration: Admin service account:

To assign the necessary service account roles:

3. 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:

4. Add a realm-roles mapper:

​

Scheduler service account

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

​

Integration Designer service account

The Integration Designer service account is used by the integration designer microservice to interact securely with Keycloak, enabling it to manage various integrations within the FlowX.AI platform.

Steps to set up an Integration Designer service account:

For further details on configuring access rights and roles for the Integration Designer service account, refer to the following section:

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.