Managing Workflows

Keycloak Workflows is a powerful engine to automate and orchestrate realm administrative tasks, bringing key capabilities of Identity Governance and Administration (IGA) to your identity and access management infrastructure. By using workflows, you can implement policies and processes that govern the lifecycle of realm resources, such as users and clients, helping you to improve security, meet compliance requirements, and reduce administrative costs.

As a core component of IGA, identity lifecycle management is fully supported by workflows so that you can easily automate onboarding and offboarding processes, and other recurring administrative tasks. For example, you can define workflows to:

• Provision and de-provision realm resources, such as users, automatically based on specific events or conditions.

• Automate Joiner-Mover-Leaver (JML) processes to ensure that users are granted the appropriate access rights based on their roles and responsibilities.

• Enforce access reviews and certifications to ensure that users have the appropriate access rights.

• Enforce Just-In-Time and Least Privilege access by automating role assignments and revocations.

• Enforce strong authentication policies for realm users.

• Prevent insider data breaches by automating the removal of inactive or obsolete users.

By leveraging workflows, realm administrators can ensure that security policies are consistently enforced and based on the least privilege principle, reduce the risk of human error, and free up valuable time to focus on other important administrative tasks. This guide will walk you through the process of creating and managing workflows to automate your administrative tasks and implement IGA best practices when managing realms.

Understanding workflows

A workflow is an activity or process within Keycloak that executes a series of predefined steps on a specific realm resource in response to specific events and based on the defined conditions.

In Keycloak, there are two main types of events:

• User Events: These events are initiated by users, such as login in or registering a new account.

• Admin Events: These events are initiated by administrators through the Admin Console and API, such as creating or updating a user or any other realm resource.

Workflows are designed to respond to these events by automating tasks and processes that need to be performed and executed on the realm resources associated with these events.

Once an event is fired, the workflow engine evaluates all defined workflows in the realm to determine if any should be triggered based on the event type and the specified conditions. If the event matches the conditions defined in a workflow, a workflow execution is created and assigned with an identifier. The workflow execution is bound to the realm resource associated with the event, and only a single instance of a workflow can be active for that realm resource at any given time.

A realm resource can be any entity within the realm, such as a user, client, group, or a role. At the moment, workflows can be defined for the following realm resources:

• Users

Once a workflow is active for a realm resource, its step chain is processed. The steps run sequentially, and they will run immediately or be scheduled to execute later in time, depending on each step configuration. Once all the steps are executed, the workflow execution is completed and the realm resource is no longer bound to that workflow.

That is the main gist of Keycloak Workflows. There are more details and settings that can be configured to customize the behavior and the lifecycle of a workflow, how their instances are created, managed, and bound to realm resources, as well as how their steps are executed.

Understanding the workflow definition

Workflows are defined in YAML format. This format allows for a clear and human-readable way to specify the automation process represented by a workflow.

In its simplest form, a workflow definition can be defined as follows:

name: Onboarding new users
on: user-created
steps:
  - uses: notify-user
    with:
      message: |
        <p>Dear ${user.firstName} ${user.lastName}, </p>
        <p>Welcome to ${realm.displayName}!</p>
        <p>
           Best regards,<br/>
           ${realm.displayName} Team
        </p>
  - uses: set-user-required-action
    after: 30d
    with:
      action: UPDATE_PASSWORD
  - uses: restart
    with:
      position: 1

The example above is very simple but illustrates the core structure and the flexibility of a workflow to automate administrative tasks. It is composed of three main sections:

• name: A unique and user-friendly name to identify the workflow within the realm.

• on: The event that will trigger the workflow. In this case, the workflow is triggered when a new user is added to the realm.

• steps: A set of one or more steps to be executed when executing a workflow execution. In this example, three steps are defined:
  1. The first step uses the built-in notify-user action to send a welcome message to the new user.
  2. The second step uses the built-in set-user-required-action action to require the user to update their password after 30 days.
  3. The third step uses the built-in restart action to restart the workflow from the second step so that the user is forced to update their password every 30 days.

Here is a more detailed look at all settings available from the workflow definition:

name

A unique and user-friendly name to identify the workflow within the realm. This name is crucial for management and logging purposes. This setting is mandatory.

on

Define a condition that determines the event that will trigger the workflow. The condition is written using an expression language that supports a variety of checks on the event. See Triggering workflows on events for more details. This setting is optional.

schedule

Define a schedule that will trigger the workflow at defined intervals. See Scheduling workflows for more details. This setting is optional.

if

Define a condition that must be met for the workflow to be triggered. The condition is written using an expression language that supports a variety of checks on the realm resource associated with the event. A workflow execution is only created if the expression evaluates to true. If this setting is omitted, the event defined in the on setting will always create the workflow execution. See Defining conditions for more details. This setting is optional.

steps

Define the step chain consisting of one or more steps to be sequentially executed during the lifetime of a workflow. See Defining steps for more details. This setting is mandatory.

concurrency

This setting controls the behavior when multiple events that would trigger the same workflow occur for the same realm resource while a workflow execution is already active for that resource. This setting is optional. + The available options are:

• restart-in-progress: A new event causes the current workflow execution to restart from the beginning.

• cancel-in-progress: A new event causes the current workflow execution to be canceled and disassociated from the realm resource.

enabled

This setting enables or disables the workflow. If set to false, new workflow executions will not be created for the workflow and any active workflow execution will be paused. This setting is optional and defaults to true.

Understanding the workflow expression language

Some settings from the workflow definition can be defined using a boolean expression language, the Workflow Expression Language. Expressions are defined using functions, operands, and logical operators. The functions available in an expression will depend on the setting where it is being defined.

The functions can have zero or more arguments, and they can be combined with the following logical operators and symbols to define complex expressions:

Operator	Description
and	Logical AND
or	Logical OR
not	Logical NOT
( )	Grouping and delimiting conditional logic

These examples are all valid expressions:

f1
f1 and f2
not (f1 and f2)
(f1 and f2) or f3

The settings that supports expressions provide its own set of functions as you will see in the following sections.

Managing workflows

Workflows can be managed through the Admin Console or the Admin REST API.

Managing workflows through the Admin Console

To manage workflows through the Admin Console, you can follow these steps:

Procedure

1. Click Workflows in the menu.

If your realm does not have any workflows defined yet, you will see an empty list. To create a new workflow, click Create.

This will open the workflow creation screen where you can define the workflow using YAML format. To save the workflow, click Save.

Once you have created one or more workflows, they will be listed in the workflows list.

From the workflows list, you can perform the following actions:

• Create: Click Create workflow to create a new workflow.

• Update: Click on the name of an existing workflow to update it.

• Enable/Disable: Use the toggle button on the Status column to enable or disable a workflow.

• Copy: Click on the Copy button next to a workflow to create a copy of it. This is useful if you want to create a new workflow based on an existing one.

• Delete: Click on the Delete button next to a workflow to delete it.

Updating a workflow

To update a workflow, click on its name in the workflows list. This will open the workflow in edit mode, where you can modify its YAML definition. After making your changes, click Save to apply the updates.

There are limitations when updating workflows if they have scheduled steps. In such cases, you are not able to change the step chain of a workflow if there are active instances of the workflow being updated. This limitation is in place to ensure the integrity of ongoing workflow instances where updates to the step chain could lead to an expensive operation of migrating existing instances to the new step chain, which could impact system performance as well as lead to inconsistencies and an unexpected behavior.

In future releases, we plan to introduce a more flexible approach to updating workflows with scheduled steps, so that administrators are going to be allowed to migrate realm resources scheduled for a specific step to a different step in the updated workflow.

For now, the only option is to either wait for all active instances to complete or to delete the workflow and create a new one. Note that deleting a workflow will also delete all its active instances, therefore, realm resources associated with those instances will not be processed further, and they would need to be re-associated with a new workflow instance if needed.

Triggering workflows on events

The on setting defines the event that will trigger the workflow. You should choose the event accordingly to the realm resource and the intent of the workflow.

The value of the `on’ setting is an expression that must evaluate to true. In its basic form, the expression is simply the name of the event.

on: user_created

As you can see, events are functions in an expression and, as such, they also support parameters to provide more specific conditions. For example, to trigger a workflow when a user is added to a specific group, you can use the following expression:

on: user_group_membership_added('/mygroup')

You can also combine multiple conditions using logical operators. For example, to trigger a workflow when a user is created or when they authenticate, you can use:

on: user_created or user_authenticated

*Even though the on setting can be defined using expressions, keep in mind that a single event triggers a workflow.

If this setting is not specified, the workflow will not be triggered by any event, but workflow executions can still be created manually for a specific realm resource.

At the moment, workflows support event functions for the following realm resources:

Event functions

Event	Description	Parameters
user_created	User is added to the realm.	None
user_removed	User is removed from the realm.	None
user_authenticated	User authenticates to the realm.	The client id of the client acting on behalf of the user when authenticating.
user_federated_identity_added	User is federated or when the account is linked to an identity provider.	The identity provider alias.
user_federated_identity_removed	User’s federated identity is removed or unlinked from an identity provider.	The identity provider alias.
user_role_granted	A role is granted to the user.	The role name.
user_role_revoked	A role is revoked from the user.	The role name.
user_group_membership_added	User joined a group.	The group name or path
user_group_membership_removed	User is removed from a group.	The group name or path

Scheduling workflows

Workflows can be scheduled to run periodically according to a defined interval. This is done using the schedule setting in the workflow definition.

A key difference between event-based triggering and scheduled workflows is that scheduled workflows follows a passive execution model where the workflow engine periodically checks for realm resources that meet the defined condition.

name: Track inactive users
schedule:
  after: 5s
  batch-size: 100

This method of scheduling is useful for automating tasks that need to be performed regularly, such as cleaning up inactive users or enforcing specific policies on realm resources. It is an alternative to event-based triggering, but it can also be used in combination with it. When used together, the workflow will be triggered either by the defined event or by the schedule.

When a workflow is scheduled, it will be triggered automatically at the defined interval. At each run, the workflow engine will query for the realm resources that matches the workflow’s condition and will create a workflow execution for each of them, up to the defined batch size. If no condition is defined, the workflow will be executed for all realm resources of the type associated with the workflow. In the example above, the workflow is scheduled to run every 5 seconds and will process up to 100 realm resources at each run.

The schedule setting supports the following parameters:

• after: Defines the interval between each run of the workflow.

• batch-size: Defines the maximum number of realm resources to process at each run.

Defining conditions

The optional if setting allows you to define the conditions, as expressions, that the target resource must meet in order for the workflow to be triggered. See Understanding the workflow expression language for more details.

Conditions provide fine-grained control over whether a workflow execution should be created. They allow you to inspect the context of the event and the state of the resource. For example, you can create conditions to check: * If a user has a specific attribute. * If a specific role is granted to a user or if the user is joining a specific group.

If the condition evaluates to true, the workflow execution is created. If it evaluates to false, no workflow execution is created, even though the expression from the on setting evaluates to true.

Just like the on setting, the condition is written using an expression that supports a variety of checks on the realm resource associated with the event. For instance, considering a user_created event, you can define a condition to trigger the workflow only if the user has a specific attribute:

on: user_created
if: has-user-attribute('plan', 'gold')

In this example, the workflow will only be triggered when a new user is created and that user has an attribute plan with the value gold.

Keycloak provides a set of built-in conditions that you can use in your workflows. The conditions are also based on the realm resource associated with the event.

User Functions

Condition	Description	Parameters
has-user-attribute	If the user has an attribute set.	The attribute name and optionally the attribute value using a properties format. If multiple values, they should be separated by comma. If the value is omitted, only the presence of the attribute is checked.
has-role	If the user is granted with a specific role	The name of the role.
has-identity-provider-link	If the user is linked to an identity provider.	The alias of the identity provider.
is-member-of	If the user is member of a specific group.	The name or path of the group.

Defining steps

The steps setting allows you to define the step chain, which is a sequence of actions to be executed during the lifetime of a workflow execution. Each step represents a specific action that can be performed, such as sending a notification, updating user attributes, or interacting with external systems.

Each step in the step chain is defined using the following structure:

steps:
  - uses: <step>
    with:
      <param>: <value>
      ...
    after: <duration>
  ...

In its simplest form, a step is defined using only the uses field:

steps:
  - uses: disable-user

However, some steps also support additional settings to customize their behavior:

steps:
  - uses: notify-user
    with:
      message: "Welcome to the platform!"

Here is a more detailed look at all fields available from defining a step:

uses

The name of the step to be executed. This field is mandatory.

with

Key/value pairs to be passed to the step. The available parameters depend on the step being used. This field is optional.

after

An optional duration to wait before executing the step. The duration is defined using a number followed by a time unit:

• ms: milliseconds

• s: seconds (default if no unit is specified)

• m: minutes

• h: hours

• d: days

Keycloak provides a set of built-in steps that you can use in your workflows. The steps are targeted at performing actions on the realm resource associated with the event, so that each realm resource type has its own set of steps.

User steps

Step	Description	Configuration
set-user-required-action	Set a required action to the user	action: The name of the required action
delete-user	Delete the user	None
disable-user	Disable the user	None
notify-user	Notify the user by email	subject: The email subject message: The email message in plain text or HTML format
set-user-attribute	Set an attribute to the user. Allows providing multiple <name> / <value> pairs	<name>: The attribute name <value>: The value of the attribute

Understanding immediate steps

A step can run immediately whenever it is reached in the step chain. A immediate step is executed as soon as the previous step is completed, without any delay. This is the default behavior for steps in a workflow.

For example, in the following workflow definition, both steps are immediate steps:

steps:
  - uses: notify-user
  - uses: disable-user

Understanding scheduled steps

A step can be scheduled to run after a specific duration using the after field. A scheduled step is executed after waiting for the defined duration once the previous step is completed.

For example, in the following workflow definition, the disable-user step is a scheduled step that will run 7 days after notifying the user:

steps:
  - uses: notify-user
  - uses: disable-user
    after: 7d

Understanding the workflows engine

The lifecycle and execution of workflows in Keycloak is managed by the Workflows Engine. The engine is responsible for processing events, creating workflow executions, and processing their steps. Once a workflow execution is created, the engine takes over and manages the execution of its steps chain.

The execution of the steps chain is done asynchronously and detached from the request that originated the event that triggered the workflow. This means that workflows are not scheduled nor executed immediately within the context of the request, but rather sent to a task thread pool and scheduled to be executed later by the engine. This allows for better performance and scalability, as the steps can be executed in the background without blocking the main request thread.

For immediate steps, the engine processes them as soon as the workflow execution is submitted to the task thread pool. This means that immediate steps are executed right away, as soon as the workflow execution is picked up by a worker thread from the pool.

For scheduled steps, the engine continuously monitors the state of all active workflow executions in the realm. This is done by a background task that runs periodically to check for any workflow executions that have steps ready to be executed. The schedule steps of a workflow are also executed asynchronously by the background task, using the same task thread pool as immediate steps.

Configuring the scheduled steps execution interval

By default, the background task tracking due steps runs every 12 hours, but this interval can be configured by setting the following server configuration option:

• spi-events-listener—​workflow-event-listener—​step-runner-task-interval: Defines the interval, in milliseconds, at which the background task runs to check for workflow steps that are due for execution.

You can adjust this interval based on your realm’s needs and the expected frequency of workflow executions.

Configuring the task execution timeout

Most of the time, steps are executed in a short amount of time. However, there might be cases where a step takes longer to execute due to various reasons, such as network latency depending on an external service delays, or complex processing logic.

By default, the timeout for executing a step is set to 1 second. If a step takes longer than this timeout to execute, it will be marked as failed, and the workflow execution will be halted. If the step is scheduled, it will run again in the next execution window of the background task. If the step is not scheduled, the workflow execution will be marked as failed and that step won’t be retried.

You can configure the timeout for step execution by setting the following server configuration option:

• spi-workflow—​default—​executor-task-timeout: Defines the timeout, in milliseconds, for executing a workflow step.

Performance considerations

Workflows can introduce additional processing overhead. This is mainly true when workflows are triggered frequently such as when users are authenticating. Even though workflows are scheduled and executed asynchronously, they still consume system resources. Therefore, it’s important to monitor the performance of your realm and adjust your workflow definitions accordingly to ensure optimal performance.

Consider the following best practices when defining workflows:

• Keep workflows simple and focused on specific tasks and avoid long-running transactions when executing steps in a workflow. This is specially true for steps that are executed immediately upon workflow execution creation.

• Consider using short timeouts for the step execution to avoid blocking the workflow execution for too long and potentially exhaust the workflow task thread pool and impacting the execution of other workflows.

• Adjust the background task interval based on the expected frequency of workflow executions in your realm. If your realm has a high volume of workflow executions, consider reducing the interval to avoid processing multiple workflows at once.

Understanding common use cases

Workflows can be used to automate a wide range of administrative tasks within a realm. Here are some common use cases where workflows can be particularly beneficial:

User Onboarding

When a new user is created, a workflow can automatically send a welcome email, and assign initial roles or groups to the user. This ensures that new users have the necessary access and information from the moment they join.

name: Onboarding gold members
on: user-created
if: has-user-attribute('membership','gold')
steps:
  - uses: notify-user
    with:
      message: "Welcome to the Gold Membership program!"
  - uses: grant-role
    with:
      role: gold-member

User Offboarding

When a user is removed from a specific group, a workflow can automatically revoke certain roles or permissions associated with that group.

name: Offboarding sales members
on: user_group_membership_removed('/Sales')
steps:
  - uses: revoke-role
    with:
      role: "manager,sales-rep,sales-intern"

Tracking user activity and taking actions on inactivity

When a user has been inactive for a certain period, a workflow can send reminder emails and deactivate the account.

name: Track inactive users
on: user-authenticated
schedule:
  after: 5s
  batch-size: 2
concurrency:
  restart-in-progress: true
steps:
  - uses: notify-user
    after: 180d
    with:
      message: It has been a while since your last login. We miss you!
  - uses: notify-user
    after: 60d
    with:
      message: Your account will be disabled in ${workflow.daysUntilNextStep} days!
  - uses: disable-user
    after: 7d
  - uses: notify-user
    with:
      message: Your account was disabled. Sorry to see you go.

© 2026 Interfacing Technologies Corporation