Keycloak 26.6+ Workflows: Automating Identity

Introduction

With the release of Keycloak 26.6+, workflows have evolved into a powerful and officially supported feature, bringing core Identity Governance and Administration (IGA) capabilities into the platform.

Workflows allow administrators to automate and orchestrate lifecycle operations on realm resources such as users, clients, groups, and roles—reducing manual effort and improving consistency.

What are Keycloak Workflows?

Workflows in Keycloak are defined in YAML format and enable automation based on:

• Events (user or admin actions)
• Schedules (time-based execution)
• A combination of both

These workflows allow you to define step-by-step automation logic that runs when specific conditions are met.

How Workflows Are Triggered

A workflow can be triggered in three main ways:

1. Event-Based Trigger

• User events (e.g., login, registration)
• Admin events (e.g., create/update user)

2. Schedule-Based Trigger

• Time-based execution (e.g., every 30 days)

3. Combined Trigger

• Event + scheduled follow-up actions

How Workflow Execution Works

Once an event occurs:

1. The workflow engine evaluates all workflows in the realm
2. Matching workflows are selected based on:
   • Event type
   • Conditions defined in the workflow
3. The workflow is bound to the specific realm resource (e.g., a user)

What is a Realm Resource?

A realm resource is any manageable entity inside a realm, such as:

• User
• Client
• Group
• Role

👉 When a workflow is triggered, it is associated with that specific resource instance (for example, a particular user)

⚠️ Although, a realm resource can be any entity within the realm, such as a user, client, group, or a role, as per this link, at the moment, workflows can be defined for the Users realm resource.

Workflow Execution Lifecycle

Once triggered:

• Steps execute sequentially
• Each step can:
  • Run immediately
  • Be scheduled for later execution
• The workflow continues until all steps are completed

After completion:

• The workflow is detached from the resource

Example Workflow (User Onboarding)

name: Onboarding new users
on: user-created
steps:
  - uses: notify-user
    with:
      message: |
        <p>Welcome ${user.firstName} ${user.lastName}</p>
  - uses: add-required-action
    after: 30d
    with:
      action: UPDATE_PASSWORD
  - uses: restart
    with:
      position: "1"

What this Workflow Does

1. On user creation
   • Sends a welcome message to the user
     ⚠️ Requires SMTP configuration in the realm
2. After 30 days
   • Forces the user to update their password
3. Restart step
   • Repeats the workflow from step 1
   • Effectively enforces password update every 30 days

Important Notes

• Email notifications work only if SMTP is configured
• Steps like notify-user depend on available step providers
• Workflows are processed per resource instance

Creating and Managing Workflows

You can create workflows from:

👉 Admin Console → Workflows

Additional features:

• Enable/disable workflows
• Monitor execution
• View active workflows per resource

👉 If a workflow is active for a user:

• It will be visible in the Workflow tab in user details

Key Use Cases

Some practical use cases include:

• ✅ User onboarding automation
• ✅ Enforcing periodic password updates
• ✅ Automated user lifecycle management
• ✅ Compliance-driven policies
• ✅ Scheduled maintenance tasks

Configuring Workflow Execution Interval

Workflow steps that are scheduled (e.g., after: 30d) are executed by a background task.

By default:

• Runs every 12 hours

You can customize it using:

--spi-events-listener-workflow-event-listener-step-runner-task-interval

👉 Example:

• Set to 1h for hourly checks

--spi-events-listener-workflow-event-listener-step-runner-task-interval=1h

Performance Considerations

To ensure optimal performance:

• Keep workflows simple and focused
• Avoid long-running or blocking operations
• Prefer smaller, modular workflows over complex chains

Debugging Workflows

To enable debug logging for workflows:

--log-level=org.keycloak.models.workflow:debug

This helps you:

• Trace execution
• Debug step failures
• Understand workflow behavior

Keycloak Workflows vs Traditional Extensions

Before workflows:

• You needed Event Listener SPI
• Or custom Java extensions

Now:

• Many use cases can be handled declaratively using YAML
• Reduces need for custom development

Summary

Workflows in Keycloak 26.6+ mark a major step forward in making the platform more automation-friendly and closer to modern IGA solutions.

While still evolving, they provide a strong foundation for:

• Event-driven automation
• Lifecycle management
• Policy enforcement

For teams already using Keycloak, workflows open the door to powerful automation without deep customization.

About Skycloak

Skycloak is a fully managed Keycloak platform hosted in the cloud. It enables organizations to leverage the power of open-source Keycloak IAM without the operational overhead of installing, maintaining, and scaling production-grade Keycloak environments — delivered securely and cost-effectively.

If you’re new to Skycloak, visit the Skycloak Getting Started Guide to learn more