Skip to main content
This guide walks through configuring a minimal Keycloak setup to efficiently manage users, roles, and apps. Keycloak is an open-source Identity and Access Management (IAM) solution that secures apps 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.xNote for Keycloak 26+: If using Keycloak version 26 or above, additional email configuration is required in the realm settings to prevent bad request errors when creating users. See the realm configuration section for details.
To configure a minimal required Keycloak setup, this guide covers the following steps:
1

Create a new realm

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

Create new users

3

Add clients

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

Add mappers

5

Add service accounts

Set up admin, task management, process engine, scheduler, integration designer, runtime manager, organization manager, email gateway, and license 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

Fresh 5.7.0+ installations: If you are deploying FlowX for the first time, the guided setup flow (via the Organization Manager) creates both the user realm and the service accounts realm automatically. You only need to follow this section if you are configuring Keycloak manually, or if you need to customize realm settings beyond the defaults.Upgrading from 5.1.x: Your existing “flowx” realm is renamed automatically by Liquibase migrations. You do not need to create a new realm, but you should review the Realm architecture section to understand the changes.
A realm is a space where you manage objects, including users, apps, roles, and groups. Creating a new realm is the first step in setting up Keycloak manually. 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).
Keycloak Admin Console login page
2

Create realm

In the top left corner dropdown menu, click Manage realms then click Create realm.
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.
Create realm dialog in Keycloak
4

Configure realm settings

Tokens → Access Token Lifespan: Set to 30 Minutes (recommended).
Access token lifespan setting in realm configuration
Login → Email settings: Configure email authentication settings.
Email settings in Keycloak Login tab
For Keycloak versions 26 and above: You must configure the email settings in the Login tab to avoid bad request errors when creating users in FlowX Designer. Make sure to enable Email as username and Login with email toggles as shown in the realm settings.
Verify your realm is created correctly: navigate to the realm selector dropdown in Keycloak and confirm your new realm appears in the list.

​
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

Click Create new user.Fill in the user details and set Email Verified to Yes.
Create new user form in Keycloak
3

Set temporary password

Save the user, go to the Credentials tab, and set a temporary password. Ensure the Temporary checkbox is checked.
Setting temporary password in Keycloak Credentials tab
Verify the user is created: navigate to Users and confirm the new user appears in the list with Email Verified set to Yes.

​
Password policy

Available starting with FlowX.AI 5.5.0
FlowX.AI enforces the following password policy for all user accounts:
RuleRequirement
Minimum length8 characters
Maximum length64 characters
UppercaseAt least one uppercase letter
LowercaseAt least one lowercase letter
NumberAt least one digit
Special characterAt least one of !@#$%^&*()_+-
AdditionalCannot match the user’s email address
Configure your Keycloak realm password policy to match these requirements. In Keycloak, go to Authentication → Policies → Password Policy and add the corresponding policy rules.

​
Adding clients

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

​
Adding an OAuth 2.0 client

Add a client named flowx-platform-authenticate, 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.
Keycloak Clients page with Create client button
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.
Client general settings with Client ID and Client type
3

Configure capability config

Now click Next and configure the Capability config details:
  • Enable Direct Access Grants.
  • Enable Implicit Flow Enabled.
Capability config with Direct Access Grants and 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.
Login settings with Valid redirect URIs
5

Configure additional settings

After creating the client, scroll down in the Settings tab and configure additional settings - Logout Settings:
  • Front Channel Logout: Toggle OFF.
  • Backchannel Logout Session Required: Toggle OFF.
Logout settings with Front Channel Logout and Backchannel toggled 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

The flowx-platform-authorize client is used for opaque token introspection. In 5.1.x, all services validate tokens by calling the Keycloak introspection endpoint using this client’s credentials.
5.5.0 and later: The flowx-platform-authorize client is no longer required. Token validation switches from opaque-token introspection to JWT public key validation (security.type: jwt-public-key). You can skip this section if you are running FlowX.AI 5.5.0 or later.
Create and configure the {your-client-name}-platform-authorize client to authorize REST requests to microservices and Kafka.
1

Create the Client

Enter the client ID ({your-client-name}-platform-authorize).Set Client type to OpenID Connect.
Authorize client general settings
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”.
Authorize client with Client Authentication toggled ON
3

Set valid redirect URIs

Valid Redirect URIs: Populate this field with the appropriate URIs. Save the configuration.
Authorize client Valid Redirect URIs
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.
Logout settings with Front Channel Logout and Backchannel toggled 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 app.

​
Example configuration for microservices

Starting with FlowX.AI 5.5.0, services validate incoming tokens using JWT public key validation. Opaque-token introspection and the flowx-platform-authorize client are no longer used. The shared security library (application-security-client.yaml) handles most configuration automatically.
security:
  type: jwt-public-key                                # JWT public key validation (replaces oauth2)
  oauth2:
    base-server-url: https://keycloak.example.com      # Base URL of the Keycloak server
    sa-realm: 00000002-0002-4002-8002-000000000002      # Service accounts realm ID (fixed UUID)

# Organization manager is a required dependency for all services
flowx:
  lib:
    security:
      services:
        organization-manager:
          base-url: http://organization-manager:80
Configuration KeyValue/ExampleDescription
security.typejwt-public-keyValidates tokens using JWT public key (no introspection endpoint needed).
security.oauth2.base-server-urlhttps://keycloak.example.comBase URL of the Keycloak server.
security.oauth2.sa-realm00000002-0002-4002-8002-000000000002Fixed UUID of the service accounts realm.
flowx.lib.security.services.organization-manager.base-urlhttp://organization-manager:80Organization manager URL (required dependency for all services).
The following properties from 5.1.x are removed in 5.5.0 and later:
  • security.oauth2.realm — replaced by per-organization realm resolution
  • security.oauth2.client.client-id / client-secret — introspection client no longer needed
  • spring.security.oauth2.resource-server.opaque-token.* — entire opaque-token block removed

​
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.
Protocol mappers overview in Keycloak
To enhance your clients’ functionality, add the following common mappers:
The mappers should be configured to be included in the token introspection response. Previously, mappers were primarily added to the /userinfo endpoint, but modern Keycloak versions support adding them to token introspection, which is the recommended approach for better security and performance.
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.
Clients list in Keycloak
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.
Dedicated client scope selection
3

Select client scope

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

Add a New Mapper

Click Add Mapper. From the list of available mappers, choose Group Membership.
Add Group Membership mapper from predefined list
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.Add to token introspection: Toggle ON.
Group Membership mapper configuration
This group membership mapper includes 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.
Client scopes Mappers tab for attribute mapper
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 businessFilter.
  • Token Claim Name: Enter attributes.businessFilters.
  • Add to access token: Toggle ON.
  • Add to token introspection: Toggle ON (recommended).
  • Multivalued: Toggle ON.
  • Aggregate attribute values: Toggle ON.
User Attribute mapper configuration for business filters
This user attribute mapper includes the custom attribute “businessFilters” in the token claim under the name “attributes.businessFilters”, making business filter information available within your app. 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.
User Realm Role mapper in predefined list
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.
  • Add to token introspection: Toggle ON.
User Realm Role mapper configuration
This roles mapper includes the user’s assigned realm roles in the OAuth user info response under the claim name “roles”.
You can repeat these steps to add multiple roles mappers if you need to include multiple realm roles in the token claim.

​
Creating a basic client scope

To ensure consistent token configuration across all clients, you should create a default client scope named “basic” with predefined mappers.
1

Navigate to Client Scopes

From the Keycloak admin console, go to Client Scopes in the left menu.Click Create client scope.
2

Configure client scope settings

  • Name: Enter basic.
  • Type: Select Default.
  • Protocol: Select OpenID Connect.
  • Display on consent screen: Toggle OFF.
  • Include in token scope: Toggle ON.
Click Save.
3

Add predefined mappers

In the newly created basic client scope, navigate to the Mappers tab.Add the following predefined mappers:
  1. sub mapper:
    • Click Add mapper → From predefined mappers
    • Select sub
    • Click Add
  2. auth_time mapper:
    • Click Add mapper → From predefined mappers
    • Select auth_time
    • Click Add
4

Assign to All Clients

After creating the basic client scope, assign it to all your clients:
  1. Navigate to Clients in the left menu
  2. For each client (e.g., flowx-platform-authenticate, flowx-platform-authorize, and all service accounts):
    • Open the client settings
    • Go to the Client Scopes tab
    • Click Add client scope
    • Select basic from the list
    • Choose Default as the assignment type
    • Click Add
The basic client scope ensures that all clients have consistent token claims for subject identification (sub) and authentication time (auth_time), which are essential for proper token validation and session management.

​
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 turn on Client authentication (access type) for your client. When you do this, the Service Accounts Enabled switch will appear.

​
Realm architecture

Starting with FlowX.AI 5.5.0, Keycloak uses a two-realm architecture that separates user authentication from service-to-service communication:
RealmIDPurpose
User realmOrganization UUID (e.g., 11111111-0001-4001-8001-111111111111)Human users, roles, groups, and the flowx-platform-authenticate client. Each organization gets its own realm.
Service accounts realm00000002-0002-4002-8002-000000000002 (fixed)All backend service account clients (e.g., flowx-admin-sa, flowx-process-engine-sa). Shared across the installation.
This separation improves security isolation — service accounts cannot access user tokens, and user realm changes do not affect service-to-service authentication.Where to create each client:
  • User-facing clients (flowx-platform-authenticate) go in the user realm
  • All service account clients go in the service accounts realm
  • The flowx-platform-authorize client is no longer needed (JWT public key validation replaces opaque-token introspection)
On fresh installations (5.7.0+), both realms are created automatically during the setup flow. On upgrades from 5.1.x, Liquibase migrations handle the realm split — the existing “flowx” realm is renamed to the organization UUID, and service accounts are moved to the new SA realm.If your deployment does not grant Keycloak admin credentials to FlowX services, you must create the service accounts realm and move the service account clients manually. See Manual Keycloak configuration below.
Upgrading from 5.2, 5.3, or 5.4? These versions may already have partial realm or organization changes from intermediate releases. Do not follow the 5.1.x upgrade path — it may conflict with your existing realm configuration. Contact your FlowX representative for a migration plan specific to your deployment.
Authorization system master realm configurationThe authorization-system service requires access to the Keycloak master realm for managing realms and running migrations. Configure the following properties on the authorization-system service only:
Environment VariableDescriptionDefault Value
SECURITY_MASTERREALM_CLIENTIDMaster realm admin client IDadmin-cli
SECURITY_MASTERREALM_NAMEMaster realm namemaster
SECURITY_MASTERREALM_ADMIN_USERNAMEKeycloak admin username-
SECURITY_MASTERREALM_ADMIN_PASSWORDKeycloak admin password-
These credentials grant full Keycloak administrative access. Store them securely using your secrets management solution (e.g., Vault, Kubernetes secrets). Never commit them to version control.

​
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.
Admin service account client ID setup
2

Configure capability config

  • Enable Client authentication (access type).
  • Disable Standard flow.
  • Disable Direct access grants.
  • Enable Service accounts roles.
Service account capability config with Client authentication and Service accounts roles enabled
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.
Logout settings toggled OFF for service account
4

Configure service account roles

In the newly created client, navigate to the Service accounts roles tab.
Service accounts roles tab
Important: The admin service account no longer requires client roles from realm-management. If you have existing roles assigned, remove them to follow the updated security model.
The admin service account is now configured to work without specific client roles. Authentication and authorization will be managed through the service account token itself.
The admin service account does not require mappers or specific client roles. Authentication is handled through the service account token itself.

​
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

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 following service account client roles from realm-management:
  • view-users
  • query-users
  • query-groups
Remove any other roles if they are assigned (such as view-realm). The task management service account should only have these three client roles.
Assigning realm-management client roles to task management SA
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 similar to this:
Task management SA with assigned client roles
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.
Adding User Realm Role mapper to task management SA
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.
Realm roles mapper configuration for task management SA
Click Save.
Saved realm roles mapper
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

​
Process engine service account

The process engine requires a service account for service-to-service authentication and authorization.
This service account is also needed to be able to use Start Catch Event node.
1

Create the Client

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

Configure service account roles

In the newly created client, navigate to the Service accounts roles tab.The process engine service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the SA_FLOWX realm role.
3

Add a realm roles mapper

In the newly created process engine 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.Configure the mapper:
  • Name: Enter realm-roles
  • Token Claim Name: Set it to roles
  • Add to ID token: Toggle OFF
  • Add to token introspection: Toggle ON
Adding realm roles mapper to process engine SA

​
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 similar to the process engine service account:
1

Create the Client

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

Configure service account roles

In the newly created client, navigate to the Service accounts roles tab.The scheduler service account does not require client roles from realm-management. Authentication and authorization are managed through the service account token and the SA_FLOWX realm role.
3

Add a realm roles mapper

Add a realm-roles mapper (as shown in the example for process-engine service account):In the scheduler 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.Configure the mapper:
  • Name: Enter realm-roles
  • Token Claim Name: Set it to roles
  • Add to ID token: Toggle OFF
  • Add to token introspection: Toggle ON
Realm roles mapper for scheduler SA

​
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:
1

Create the Client

  • In Keycloak, navigate to Clients and select Create client.
  • Enter a Client ID for your new client (e.g., flowx-integration-designer-sa).
Integration Designer SA client ID setup
2

Configure client capabilities

  • Enable Client authentication under access type.
  • Enable Service accounts roles to allow the account to manage integrations.
Integration Designer SA capability config
3

Save the Client Configuration

  • Skip the Login settings page.
  • Click Save to apply the configuration.
4

Assign service account client roles

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 only the view-users role from realm-management:
Remove any other roles if they are assigned. The integration designer service account should only have the view-users client role.

​
Authorization System service account

The Authorization System service account is used for managing user authentication and authorization operations, including user management, realm configuration, and access control within the FlowX.AI platform. Steps to set up an Authorization System service account:
1

Create the Client

Navigate to Clients and select Create client.Enter a Client ID for your new client (e.g., flowx-authorization-system-sa).
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 service account client roles

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 following service account client roles from realm-management:
  • view-users
  • query-users
  • manage-users
  • manage-realm
These roles are essential for the Authorization System service account to perform user and realm management operations within Keycloak.

​
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:
1

Create the Client

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

Configure capability config

  • Enable Client authentication (access type).
  • Disable Standard flow.
  • Disable Direct access grants.
  • Enable Service accounts roles.
Runtime manager SA capability config
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.
Logout settings toggled OFF for service account
4

Configure service account roles

In the newly created client, navigate to the Service accounts roles tab.
Service accounts roles tab
Important: The runtime manager service account no longer requires specific realm roles. If you have existing roles assigned (such as ROLE_TASK_MANAGER_HOOKS_ADMIN, ROLE_ADMIN_MANAGE_PROCESS_ADMIN, etc.), remove them to follow the updated security model.
The runtime manager service account is now configured to work without specific realm roles. Authentication and authorization for export/import operations will be managed through the service account token itself.

​
Organization manager service account

Available starting with FlowX.AI 5.5.0
The organization manager service account is used by the organization manager microservice to handle organization and workspace management within the FlowX.AI platform.
1

Create the Client

Follow steps 1-3 as in the Admin Service Account Configuration: Admin service account.Enter a Client ID of flowx-organization-manager-sa.
2

Configure service account roles

In the newly created client, navigate to the Service accounts roles tab.The organization manager service account does not require specific client roles from realm-management. Authentication and authorization are managed through the service account token and the SA_FLOWX realm role.

​
Email gateway service account

Available starting with FlowX.AI 5.4.0
The email gateway service account is used by the email gateway microservice to manage email sending and receiving operations within the FlowX.AI platform.
1

Create the Client

Follow steps 1-3 as in the Admin Service Account Configuration: Admin service account.Enter a Client ID of flowx-email-gateway-sa.
2

Assign service account client roles

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 following service account client role from realm-management:
  • view-users
Remove any other roles if they are assigned. The email gateway service account should only have the view-users client role.

​
License service account

Available starting with FlowX.AI 5.5.0
The license service account is used by the license microservice to manage license validation and enforcement within the FlowX.AI platform.
1

Create the Client

Follow steps 1-3 as in the Admin Service Account Configuration: Admin service account.Enter a Client ID of flowx-license-sa.
2

Assign service account client roles

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 following service account client role from realm-management:
  • view-users
Remove any other roles if they are assigned. The license service account should only have the view-users client role.

​
Configuring SA_FLOWX realm role

The SA_FLOWX role is a realm-level role that should be assigned to all service accounts to ensure proper authentication and authorization across the FlowX.AI platform.
5.5.0 and later: Create the SA_FLOWX role in the service accounts realm (00000002-0002-4002-8002-000000000002), since that is where all service account clients reside. In 5.1.x, create it in the user realm.
1

Create the SA_FLOWX Realm Role

  1. In the Keycloak admin console, navigate to the appropriate realm:
    • 5.1.x: Your user realm
    • 5.5.0+: The service accounts realm (00000002-0002-4002-8002-000000000002)
  2. Go to Realm roles in the left menu.
  3. Click Create role.
  4. Enter SA_FLOWX as the Role name.
  5. Add a description: “Service account role for FlowX.AI platform services”.
  6. Click Save.
2

Assign SA_FLOWX to service accounts

For each service account listed below, assign the SA_FLOWX realm role:
  • flowx-process-engine-sa
  • flowx-admin-sa
  • flowx-runtime-manager-sa
  • flowx-integration-designer-sa
  • flowx-scheduler-core-sa
  • flowx-authorization-system-sa
  • flowx-task-management-plugin-sa
  • flowx-organization-manager-sa (5.5.0+)
  • flowx-email-gateway-sa (5.4.0+)
  • flowx-license-sa (5.5.0+)
To assign the role to each service account:
  1. Navigate to Clients and select the service account client.
  2. Go to the Service accounts roles tab.
  3. Click Assign role.
  4. In the Filter field, select Filter by realm roles.
  5. Find and select SA_FLOWX from the list.
  6. Click Assign.
Assigning SA_FLOWX realm role to a service account
3

Verify role assignment

After assigning the role to all service accounts, verify that each service account has the SA_FLOWX role listed in its Service accounts roles tab.
The SA_FLOWX role ensures consistent authentication and authorization behavior across all FlowX.AI platform services. Make sure all service accounts have this role assigned for proper system operation.

​
Email (SMTP) configuration

Required for self-hosted deploymentsOn self-hosted (on-premises) deployments, SMTP must be configured by the client directly in Keycloak. This is required for password reset flows and user invitation emails sent from FlowX Designer.
To configure email delivery:
1

Navigate to email settings

In Keycloak, go to your organization realm, then Realm settings → Email.
2

Configure SMTP connection details

Fill in your SMTP server details:
FieldDescription
HostSMTP server hostname (e.g., smtp.example.com)
PortSMTP port (typically 587 for TLS or 465 for SSL)
FromSender email address (e.g., noreply@example.com)
Enable SSL / Enable StartTLSToggle ON based on your mail server requirements
AuthenticationToggle ON if your SMTP server requires credentials
Username / PasswordSMTP authentication credentials
3

Test the connection

Use the Test connection button in Keycloak to verify emails can be sent.
Without SMTP configured, the following features will not work:
  • Password reset — users cannot reset their passwords via email
  • User invitations — inviting new users from FlowX Designer will fail

​
Manual Keycloak configuration

Available starting with FlowX.AI 5.5.0This section is only needed if your deployment does not provide Keycloak admin credentials to the authorization-system service (i.e., you cannot set the SECURITY_MASTERREALM_* environment variables). In that case, Liquibase migrations cannot run automatically and you must configure Keycloak manually.
If FlowX services do not have Keycloak admin access, perform the following steps manually in the Keycloak Admin Console:
1

Create the service accounts realm

  1. Log in to the Keycloak Admin Console.
  2. Click Create realm.
  3. Set the Realm name to 00000002-0002-4002-8002-000000000002.
  4. Set the Display name to Flowx Administration Realm.
  5. Click Create.
Configure the realm settings:
  • Login tab: Enable Email as username and Login with email
  • Authentication → Policies → Password Policy: Add uppercase, digit, special character, and minimum length (8) rules
2

Move service account clients to the SA realm

For each service account client listed in Adding service accounts, create the client in the service accounts realm (not the user realm):
  1. In the SA realm, go to Clients → Create client.
  2. Enter the Client ID (e.g., flowx-admin-sa).
  3. Enable Client authentication and Service accounts roles. Disable Standard flow and Direct access grants.
  4. Configure Logout Settings: Toggle OFF both Backchannel Logout and Front Channel Logout.
  5. Assign the SA_FLOWX realm role (create it first in the SA realm if it does not exist).
3

Configure the org_id protocol mapper

In the user realm, ensure the flowx-platform-authenticate client has a protocol mapper that adds the org_id claim to access tokens:
  1. Go to Clients → flowx-platform-authenticate → Client scopes → dedicated scope.
  2. Add mapper → By configuration → Hardcoded claim.
  3. Set Name to org_id, Token Claim Name to org_id, Claim value to your organization UUID, and Claim JSON Type to String.
  4. Enable Add to access token and Add to token introspection.
4

Remove service accounts from user realm

After creating the service account clients in the SA realm, delete the old service account clients from the user realm. Keep only user-facing clients (flowx-platform-authenticate) in the user realm.
If you skip manual configuration, service-to-service authentication will fail. All FlowX backend services expect service accounts to exist in the realm identified by security.oauth2.sa-realm (00000002-0002-4002-8002-000000000002).

​
Troubleshooting

Keycloak 26+ only: You must configure email settings in the Login tab of realm settings. Toggle ON both Email as username and Login with email. Without this configuration, user creation requests from FlowX Designer fail with a bad request error.
Ensure the realm name is unique within your Keycloak instance. Duplicate realm names cause creation failures.
Verify the following:
  • The service account client has Client authentication enabled and Service accounts roles toggled ON.
  • The SA_FLOWX realm role is assigned to the service account.
  • The client secret in your deployment matches the secret in Keycloak (Clients → select client → Credentials tab).
  • 5.1.x: The security.oauth2.realm configuration points to the correct realm.
  • 5.5.0+: The security.oauth2.sa-realm is set to 00000002-0002-4002-8002-000000000002 and the service account client exists in the SA realm (not the user realm).
Check that the required protocol mappers are configured on the correct client scope:
  • Group Membership mapper with Add to token introspection toggled ON.
  • User Realm Role mapper with Add to token introspection toggled ON.
  • User Attribute mapper for business filters with Multivalued and Aggregate attribute values toggled ON.
5.5.0+: Also verify the org_id protocol mapper is configured on the flowx-platform-authenticate client in the user realm.
The task management service account requires view-users, query-users, and query-groups client roles from realm-management. Verify these are assigned in the Service accounts roles tab. In 5.5.0+, the task management SA is in the service accounts realm but still needs access to user realm data via the master realm configuration.
After upgrading from 5.1.x:
  • Verify security.type is set to jwt-public-key (not oauth2).
  • Remove any spring.security.oauth2.resource-server.opaque-token.* configuration.
  • Remove the security.oauth2.realm, security.oauth2.client.client-id, and security.oauth2.client.client-secret properties.
  • Ensure security.oauth2.sa-realm is set to 00000002-0002-4002-8002-000000000002.
  • Verify that flowx.lib.security.services.organization-manager.base-url is set and the organization-manager service is reachable.

​
Summary

By following these steps, you have a minimal Keycloak setup to manage users, roles, and apps efficiently.
Your Keycloak setup should include:
  • A user realm (named with your organization UUID) containing the flowx-platform-authenticate client, protocol mappers, users, roles, and groups
  • A service accounts realm (00000002-0002-4002-8002-000000000002) containing all flowx-*-sa service account clients with the SA_FLOWX realm role
  • SMTP configured in the user realm for password reset and user invitations (required for self-hosted deployments)
  • JWT public key validation (security.type: jwt-public-key) on all services
  • Master realm credentials configured on the authorization-system service
For more detailed configurations and advanced features, refer to the official Keycloak documentation.

Access Management overview

User roles, groups, and access control

Business filters

Data-level access control using business filters

Keycloak documentation

Official Keycloak documentation
Last modified on April 9, 2026