Event Hook Filtering and Okta Workflows

Event Hooks are outbound calls from Okta, sent when specified events occur in your tenant. They take the form of HTTPS REST calls to a URL you specify, encapsulating information about the events in JSON objects in the request body. These calls from Okta are meant to be used as triggers for process flows within your own software systems. Okta defines the REST API contract for the requests that it will send. Event Hooks are Okta’s implementation of the industry concept of webhooks. Okta’s Event Hooks are related to, but different from, Okta Inline Hooks, Event Hooks are meant to deliver information about events that occurred, not offer a way to affect execution of the underlying Okta process flow. Also, Event Hooks are asynchronous calls, meaning that the process flow that triggered the Event Hook continues without stopping or waiting for any response from your external service.

To handle Event Hook calls from Okta, you have two main options:

1. Implement a web service with an Internet-accessible endpoint. It’s your responsibility to develop the code and to arrange its hosting on a system external to Okta. See this blog post for a Java example of how to code a web service endpoint: Password Import Hook with Java Endpoint.
2. Use Okta Workflows. Using workflows to handle these events is super easy as Okta provides an Out of the Box connector that will automatically receive each type of event. Your workflow can then be used to process the event as desired. Now that Event Hook Filters are available (currently in beta at the time of writing this post), we now have an alternative way to handle Okta Events in Workflows in a more performant way.

Option 1 – Apply Filter in Workflow

This is the traditional approach. Okta Workflows comes with an Out of the Box connector for your Okta tenant. See the documentation here: Okta connector | Okta . As an example, we will be using the event that is triggered when a user is added to a group. User Added to Group | Okta

This is an example of how you would implement a workflow to process events for a specific group.

In the above screen shot, we can see that a Continue If card is required so only events pertaining to group Registration Approved are processed. In other words, this flow is executed for every user added to every group in your Okta tenant. This is obviously a highly inefficient way to process data, but up until now has been the only option.

Option 2 – Apply Filter in Okta Tenant

With the addition of Event Hook Filtering, we now have a better option to process Okta Events.

Step 1

Within Okta Workflows, create a new flow and expose the flow as an API Endpoint and choose the security option of Expose as Webhook. Once the flow has been created, click on the gear icon at the end of the flow and select API Access from the drop down menu.

Then on the API Endpoint Settings popup, copy the value for Invoke URL. We will be using this when we create an event hook within your tenant.

Step 2

Within your administration console, go to Workflow > Event Hooks and create a new event. As the event type, select User added to group. Paste the Invoke URL copied in the previous step as the events Endpoint URL.

Once the event has been created, go to the Filters tab.

Note: The Filters Tab will only be available once Event Hook Filtering has been enabled in your tenant. (Currently in beta at the time of writing this post)

Then add a filter that will screen out all events except for the ones you are after. In my example below, I’m only interested in events triggered when the user is added to group Registration Approved.

See the documentation here on how to construct your filter with Okta’s expression language: https://help.okta.com/en/betas/Content/Topics/betas/open/event-hooks/about-eventhooks-el.htm

Here is the expression I’m using:

event.target.?[type eq 'UserGroup' && displayName eq 'Registration Approved'].size()> 0

Ensure that your configured event has been set to Active.

Step 3

The final step is to complete your workflow that will receive the generated event. The way the payload is extracted is slightly different, but the good thing is that the flow will only be executed when the user is added to the group Registration Approved.

My basic flow is included below.