> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuring an IAM solution (Keycloak)
> This guide provides step-by-step instructions for configuring a minimal Keycloak setup to manage users, roles, and applications efficiently.
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**
## Recommended Keycloak setup
To configure a minimal required Keycloak setup, in this guide we will cover the following steps:
Define available roles and realm-level roles assigned to new users.
Configure the client authentication, valid redirect URIs, and enable the necessary flows.
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:
## 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:
Log in to the Keycloak Admin Console using the appropriate URL for your environment (e.g., QA, development, production).
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.
Enter a realm name and click **Create**.
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.
To import a super admin group with the necessary default user roles, download and run the provided 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.
After importing, add an admin user to the group and assign the necessary roles.
Check the default roles to ensure correct import:
**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:
In the left menu bar, click **Users** to open the user list page.
On the right side of the empty user list, click **Add User**.
Fill in the user details and set **Email Verified** to **Yes**.
In the **Groups** section, search for a group, in our case: `FLOWX_SUPER_USERS` and click **Join**.
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.
Click **Clients** in the top left menu, then click **Create client**.
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`.
Now click **Next** and configure the **Capability config** details:
* Enable **Direct Access Grants**.
* Enable **Implicit Flow Enabled**.
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.
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.
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-protocol-mappers).
### Adding an Authorizing client
To authorize REST requests to microservices and Kafka, create and configure the `{your-client-name}-platform-authorize` client.
Enter the client ID (`{your-client-name}-platform-authorize`).
Set **Client type** to **OpenID Connect**.
**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**.
**Valid Redirect URIs**: Populate this field with the appropriate URIs.
Save the configuration.
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:
```yaml theme={"system"}
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 Key | Value/Example | Description |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `security.type` | `oauth2` | Specifies the security type as OAuth2. |
| `security.basic.enabled` | `false` | Disables basic authentication. |
| `security.oauth2.base-server-url` | `http://localhost:8080` | Sets the base server URL for the Keycloak server. |
| `security.oauth2.realm` | `flowx` | Specifies the Keycloak realm. |
| `security.oauth2.client.access-token-uri` | `${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/token` | Defines the URL for obtaining access tokens. |
| `security.oauth2.client.client-id` | `your-client-name-platform-authorize` | Sets the client ID for authorization. |
| `security.oauth2.client.client-secret` | `CLIENT_SECRET` | Provides the client secret for authentication. |
| `security.oauth2.resource.user-info-uri` | `${security.oauth2.base-server-url}/realms/${security.oauth2.realm}/protocol/openid-connect/userinfo` | Specifies 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:
* [Group Membership mapper ](#group-membership-mapper) (`realm-groups`)
* Maps user groups to the authorization token.
* [User Attribute mapper](#user-attribute-mapper) (`business filter mapper`)
* Maps custom attributes, for example, mapping the [businessFilters ](../../docs/platform-deep-dive/user-roles-management/business-filters) list, to the token claim.
* [User Realm role](#user-realm-role) (`realm-roles`)
* Maps a user's realm role to a token claim.
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:
From the Keycloak admin console, go to **Clients** and select your desired client.
In the client settings, click on **Client Scopes**.
Select the **dedicated client scope**: `{your-client-name}-authenticate-dedicated` to open its settings.
Make sure the **Mappers** tab is selected within the dedicated client scope.
Click **Add Mapper**. From the list of available mappers, choose **Group Membership**.
**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:
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.
Click **Add mapper**. From the list of available mappers, select **User Attribute**.
* **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:
### 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:
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.
Click **Add Mapper**. From the list of available mappers, select **User Realm Role**.
* **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 theme={"system"}
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 theme={"system"}
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:
Navigate to **Clients** and select **Create client**.
Enter a **Client ID** for your new client.
* Enable **Client authentication** (access type).
* Disable **Standard flow**.
* Disable **Direct access grants**.
* Enable **Service accounts roles**.
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.
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:
### 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:
Follow steps **1**-**3** as in the Admin Service account configuration: [Admin service account](#admin-service-account).
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:
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**.
**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**.
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:
### 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**](../../docs/building-blocks/node/message-events/message-catch-start-event) node.
**To create the process engine service account**:
* **1-3**: Follow the same steps as in the Admin Service Account Configuration: [Admin service account](#admin-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.
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
This service account is used for [**Start Timer Event**](../../docs/building-blocks/node/timer-events/timer-start-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).
### 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:
* In Keycloak, navigate to **Clients** and select **Create client**.
* Enter a **Client ID** for your new client (e.g., `integration-designer-sa`).
* Enable **Client authentication** under access type.
* Enable **Service accounts roles** to allow the account to manage integrations.
* Skip the **Login settings** page.
* Click **Save** to apply the configuration.
For further details on configuring access rights and roles for the Integration Designer service account, refer to the following section:
### Runtime manager service account
The runtime manager service account is used by both Application Manager and Runtime Manager services to connect with Keycloak and perform export/import operations for builds, application versions, or other resource-specific tasks.
Steps to add a Runtime manager service account:
Navigate to **Clients** and select **Create client**.
Enter a **Client ID** for your new client.
* Enable **Client authentication** (access type).
* Disable **Standard flow**.
* Disable **Direct access grants**.
* Enable **Service accounts roles**.
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.
In the newly created client, navigate to the **Service accounts roles** tab.
Click **Assign role** and in the Filter field, select **Filter by realm roles**.
Make sure the service account has the necessary roles assigned—this is crucial for features like export/import of builds, application versions, resource files, and for invoking scenarios such as moving scheduled events from one build to another.
Assign the necessary roles to the admin service account based on the required access scopes, the following roles are required:
* `ROLE_TASK_MANAGER_HOOKS_ADMIN`
* `ROLE_TASK_MANAGER_VIEWS_ADMIN`
* `ROLE_DOCUMENT_TEMPLATES_ADMIN`
* `ROLE_ADMIN_MANAGE_PROCESS_ADMIN`
* `ROLE_INTEGRATION_SYSTEM_ADMIN`
* `ROLE_TASK_MANAGER_PROCESS_ALLOCATION_SETTINGS_ADMIN`
* `ROLE_CMS_CONTENT_ADMIN`
* `ROLE_MEDIA_LIBRARY_ADMIN`
* `ROLE_NOTIFICATION_TEMPLATES_ADMIN`
* `ROLE_INTEGRATION_WORKFLOW_ADMIN`
For more detailed information on application manager/runtime manager access rights, 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.
## Related topics
- [Configuring an IAM solution (EntraID)](/4.6.0/setup-guides/access-management/configuring-an-iam-solution-entra.md)
- [IAM solution](/4.6.0/setup-guides/access-management/access-management-overview.md)
- [Authorization & access roles](/4.6.0/docs/platform-deep-dive/plugins/custom-plugins/reporting/access-and-authorization.md)
- [Deployment guidelines v5.7.0](/release-notes/v5.x/v5.7.0-april-2026/deployment-guidelines-v5.7.md)
- [FlowX.AI Designer](/4.6.0/docs/flowx-designer/overview.md)