Keycloak Workflow Admin Audit (event listener)

Maven module that ships a global EventListenerProviderFactory (workflow-admin-audit). It observes workflow step outcomes and emits realm admin events when steps succeed or fail on supported resources (WorkflowStepExecutedEvent, WorkflowStepFailedEvent).

Compatibility

Built against	Keycloak 26.7.3 (see JAR manifest Keycloak-Version)
Supported range	Keycloak 26.6.0 and later
Requirement	Workflows feature enabled (Profile.Feature.WORKFLOWS)

One JAR covers the whole 26.6.x–26.7.x line. Rebuild and cut a new provider release when Keycloak SPI changes require it; no per-minor artifact matrix.

Prerequisites

• Keycloak with the workflows feature enabled.
• Target realm: enable Save admin events to persist rows in the admin event store. When persistence is off, configured realm event listeners (for example jboss-logging) still receive emitted admin events.

Build

Default build (Keycloak 26.7.3 from Maven Central):

mvn clean install

Against Keycloak nightly snapshots:

mvn clean install -Dkeycloak.version=999.0.0-SNAPSHOT

Against another supported release:

mvn clean install -Dkeycloak.version=26.6.0

Install and enable

1. Copy the built JAR into your server providers/ directory.
2. Run kc.sh build.
3. In the realm: enable Save admin events (for persistence) and/or configure event listeners as needed.

If nothing is recorded, confirm the JAR is on the classpath, the image was rebuilt, and startup logs show no provider load errors.

Server configuration (optional)

Key	Meaning
spi-events-listener--workflow-admin-audit--enabled	true (default) or false to disable emission.
spi-events-listener--workflow-admin-audit--step-allowlist	Optional comma-separated step provider ids (lowercase). When empty, all steps are audited.
spi-events-listener--workflow-admin-audit--include-definition-snapshot	true (default) or false to omit workflow/step definition JSON from the event representation.

For environment variables, follow the Keycloak provider configuration rules (KC_SPI_… mapping from the same logical key).

Audited resources

• Users: grant-role, revoke-role, join-group, leave-group, set-user-attribute, remove-user-attribute, add-required-action, remove-required-action, notify-user, unlink-user, disable-user, delete-user, and any custom user step providers.
• Clients (Keycloak 26.7+): disable-client, delete-client, and custom client step providers.

Admin event details include the step action parameters when present in the step config: role, group, attribute, action, subject, message, reason. Scheduling keys such as after stay out of details.

AuthDetails (synthetic actor)

Admin events use stable synthetic userId and clientId constants defined in WorkflowAdminAuditEventListenerFactory so the UI shows a consistent non-interactive actor. They do not need to exist as real realm users or clients.

Troubleshooting

• No persisted admin rows: confirm Save admin events on the realm, the provider JAR is installed, the server was rebuilt, and spi-events-listener--workflow-admin-audit--enabled is not false.
• Steps missing from audit: check step-allowlist is not restricting them.
• High DB volume: set include-definition-snapshot to false, or disable admin event details on the realm.

Screenshots

Spoiler