Processing Okta Event Hooks with Workflows

Okta Event hooks and Workflows can be combined to provide powerful detection, alerting and remediation actions. These can be leveraged for a wide range of actions such as those detailed in the Security Blog Post: Cross-Tenant Impersonation: Prevention and Detection including;

1. Alerting on phishing attempts detected and stopped by FastPass and triggering changes to authentication policies or user access. See here for an example.
2. Alerting on Factor Resets, particularly those performed against privileged users
3. Triggering on changes to settings such IdPs which can be used to impersonate users into downstream applications.

The steps required to setup this detection are as follows.

1. Create an API Endpoint on Demand Workflow in Workflows Console
2. Create an Event Hook in Okta Admin Console
3. Test Event Hook preview
4. Update Workflow to capture details
5. Test the Workflow

Creating Workflow to Receive Events

To create the initial workflow to receive event complete the following.

1. In the Okta Admin Console navigate to Workflow -> Workflows Console. This will open up a new Window.
2. In the Workflows Console Navigate to the Flows tab and select New Flow. I recommend organising your flows into an obvious folder structure so please create your flow in the appropriate spot.
3. When the flow opens click Add Event on the When this happens card and Select API Endpoint under Okta Apps as shown below.

4. Once you have added the Card save the workflow by clicking Save in the top right corner.
5. Once saved click on the </> at the bottom of the API Endpoint card and copy the Invoke URL we will need this to setup the Event Hook.

6. Before moving on to create the event hook ensure the flow is turned on and saving data by clicking on the power icon in the top right as shown below

Create Event Hook

To create the Event Hook complete the following steps.

1. Navigate to Workflows -> Event Hooks and select Create Event Hook
2. On the Add Hook details screen paste in the Invoke URL that was copied in the workflow setup & give the hook a name.
3. Next select the events that apply for this web hook, in the screen shot below we’ve selected Authentication of a user via MFA which is what would be used if we wanted to implement example 1, detect a phishing attempt, above.
4. Click Create hook and Continue

5. Next an optional filter can be added by clicking the Apply Filter checkbox and then either applying a simple filter or selecting Use Okta Expression Language (advanced). To continue the Phishing attempt example we would end up with something like the below

Test Event Hook Preview

The next step of creating the event hook is to test a preview flow.

1. On the preview event flow check select the Event Type and a suitable sample event.
2. If you wish to alter the sample event you can click the Edit button and change details.
3. Click Deliver Request to send the sample Event Hook to your connected workflow. You should see Request Delivery Successful as shown in the screen shot below.

4. Switch back to the Workflows Console and navigate to Execution History. You should see a Success under Status on the right hand side and when you click on the successful execution you should see event details like those shown below.

Processing the Event in Workflows

Example workflows for processing an event hook can be found in the Workflows Github repository and include processing Phishing attempts. In most cases the first steps will be to parse the JSON object and extract the events. The below screen shot for example composes a message with the IP address and Display name of a user which can be sent in an email or Slack message.