Build an Okta Workflow for group membership changes

TL;DR — Build an event-triggered Okta Workflow using the group membership event card, then branch on the event type and optionally filter by the target group ID. The most common reason it "doesn't fire" is that the flow is left in test mode or the event card is listening to the wrong membership event. Reading time: ~5 min

Goal

When you're done, Okta Workflows will automatically run a flow every time a user is added to or removed from an Okta group, and you'll be able to prove it by changing a user's group membership and seeing a successful execution in the flow's run history.

Prerequisites

• An Okta tenant with Okta Workflows enabled and permission to create/edit flows
• Permission to manage groups and group memberships in Okta
• At least one test user and one test group in Okta
• The exact group you want to watch, or its group ID if you want to filter to one group
• A browser session that can access the Okta Admin Console and Okta Workflows console
• Optional: curl for calling Okta APIs if you want to fetch a group ID from the terminal; check with:

curl --version

• Optional: an Okta API token with rights to read groups if you want to fetch IDs from the API
• Your Okta domain, for example:

export OKTA_DOMAIN="https://your-org.okta.com"

Steps

Step 1: Get the group ID you want to watch

If you already have the group ID, skip this step. Otherwise, fetch it with the Okta API:

export OKTA_TOKEN="your_api_token"
export GROUP_NAME="Engineering"
curl -sS -H "Authorization: SSWS $OKTA_TOKEN" -H "Accept: application/json" "$OKTA_DOMAIN/api/v1/groups?q=$GROUP_NAME" | jq -r '.[] | "\(.profile.name) \(.id)"'

You should see one or more lines shaped like Engineering 00g1abcdEFGHijkLM5d7.

Step 2: Create a new flow

In Okta Workflows, go to:

Workflows Console → Flows → New Flow

Set the flow name to:

Group Membership Change Handler

You should see a blank flow canvas with the new flow name at the top.

Step 3: Add the group membership event trigger

On the canvas, add the event card from the Okta connector. In the card picker, search for the group membership event and select the card that triggers on group membership changes. The menu path is:

Flow canvas → Add card (+) → Okta connector → search "group membership" → select the event card for user added/removed from group

If the card prompts for an Okta connection, select your existing Okta connection or create one with your tenant credentials. You should see the event card on the canvas with output fields for the user, group, and event metadata.

Step 4: Restrict the flow to one group (optional but recommended)

If you only care about one group, add an If card immediately after the event card and compare the incoming group ID to your target group ID. Use the literal value from Step 1.

Flow canvas → Add card (+) after trigger → Flow Control → If/Else

Set the condition to:

Left value: trigger output → group → id
Operator: equals
Right value: 00g1abcdEFGHijkLM5d7

If you want all groups, skip this step. You should see the If/Else card with a true branch for the matching group.

Step 5: Branch on add vs remove events

Add another If/Else card to inspect the event type. The exact field name varies by event card version, but it will be the event/action type from the trigger output. Set one branch to the add event and the other to the remove event.

Flow canvas → Add card (+) → Flow Control → If/Else

Set the condition to:

Left value: trigger output → event type
Operator: equals
Right value: group.user_membership.add

On the Else branch, treat it as the remove path. If your trigger card exposes a different event type string, use the exact value shown in the card's test payload. You should see one branch for add and one branch for remove.

Step 6: Add the action you actually want

For a minimal, testable implementation, add a log card on each branch so you can prove the flow ran before wiring downstream systems.

True branch (add) → Add card (+) → Compose → Text
Text value: User ${user.profile.login} added to ${group.profile.name}

Then → Add card (+) → Console/Log card if available in your Workflows tenant, or leave the composed text as the branch output

Else branch (remove) → Add card (+) → Compose → Text
Text value: User ${user.profile.login} removed from ${group.profile.name}

If your tenant doesn't expose a log card, keep the composed text cards and inspect them in execution history. You should see both branches ending in a simple, readable output message.

Step 7: Turn the flow on

Flows do not react to live events until they are enabled. In the flow editor, switch the flow from draft/test mode to on.

Flow editor → Save → Turn On

You should see the flow status change to On or Running.

Step 8: Trigger a real membership change

In the Okta Admin Console, add your test user to the target group, then remove them again.

Admin Console → Directory → Groups → select your test group → Manage People → Add user

Then remove the same user:

Admin Console → Directory → Groups → select your test group → Manage People → remove user

You should see two separate executions appear in the flow's history: one for add and one for remove.

Verify it works

Open the flow execution history and confirm both event types were processed.

Workflows Console → Flows → Group Membership Change Handler → History/Execution History

Expected result:

Run 1: Success
Trigger group id: 00g1abcdEFGHijkLM5d7
Event type: group.user_membership.add
Output: User test.user@example.com added to Engineering

Run 2: Success
Trigger group id: 00g1abcdEFGHijkLM5d7
Event type: group.user_membership.remove
Output: User test.user@example.com removed from Engineering

If you used a group filter, verify the flow does not run when you change membership in a different group.

Common pitfalls

The flow is saved but not turned on

Mistake: You created the flow and tested the cards, but left the flow in draft/test mode.

Symptom: Manual card tests work, but changing a user's group membership produces no live executions in history.

Fix: In the flow editor, click:

Save → Turn On

You filtered on the group name instead of the group ID

Mistake: The If card compares group.profile.name to a display name that later changes or doesn't match exactly.

Symptom: The flow runs inconsistently or stops matching after a group rename.

Fix: Change the condition to compare:

group.id == 00g1abcdEFGHijkLM5d7

You're listening for the wrong event shape

Mistake: The event card or branch condition uses the wrong membership event type string.

Symptom: The trigger fires, but your add/remove branch always goes to Else, or one path never executes.

Fix: Open one real execution, copy the exact event type value from the trigger payload, and paste that literal string into the If condition.

You tested with an app-assigned group, but your logic expects an Okta group event

Mistake: The membership change happened in a different place than the trigger card is watching.

Symptom: You changed access somewhere in Okta, but no group membership event reached the flow.

Fix: Re-test by editing membership directly in:

Admin Console → Directory → Groups → Manage People

and confirm the target is the same group object your flow filters on.

The Okta connection on the event card is stale

Mistake: The connector authorization expired or points at the wrong tenant.

Symptom: The card shows connection errors, or the flow never receives events from the tenant you're changing.

Fix: Re-authenticate the Okta connection on the event card and verify the org URL matches your tenant.

You changed the wrong group in testing

Mistake: The flow is correctly filtered to one group ID, but your test changed a different group with the same or similar name.

Symptom: No execution appears, even though the user was definitely added to "a" group.

Fix: In the group details page, copy the exact group identifier you intended to watch and compare it to the ID in your If card.

This article was written by an AI system and published pending human review. Verify anything you intend to act on.