Why Use Okta Event Hooks?

For over ten years now, Okta has provided reliable authentication infrastructure for organizations to manage users and authentication into business applications. Okta has also provided a means for developers to interact with its infrastructure by providing APIs and event notification systems. One of these notification systems is Event Hooks.

In this article, we look at Okta Event Hooks from a usage perspective and highlight some of the usage scenarios. This way, you can understand why and when you should use them.

What are Okta Event Hooks?

The concept of Okta Event Hooks is simple. If you have an external system/application and you need it to respond to an event in your Okta organization, use Event Hooks.

Event Hooks are a one-way messaging system for notifying your external applications about an event in Okta, and passing along information about that event.

Event Hooks are Okta's implementation of the webhooks concept. If you're familiar with how webhooks work, you already know a good deal about what Event Hooks intend to achieve.

How Event Hooks work in Okta

Event Hooks provide an Okta-initiated push notification used to communicate with external systems. Event Hook communication is achieved by sending an HTTP request from Okta to your external system or API. When an event takes place in Okta, an HTTP request which contains data relating to the event is automatically fired.

This HTTP request is sent to an endpoint on your API. This endpoint is submitted to Okta for the event(s) registered. In webhook terms, this endpoint is your webhook URL.

After registering for an Event Hook, Okta sends a one-time GET request to the endpoint to authenticate it. This request contains the x-okta-verification-challenge header containing a random string that you need to return in your response to Okta inside the response body. This value is returned in a verification property of the JSON response body.

Subsequent HTTP requests from Okta for the actual events are POST requests.

Now that we have a good understanding of how Okta Event Hooks work, let's look at the type of events Okta supports for Event Hooks.

What are Okta event types

Note that not all events in Okta can be subscribed to using Event Hooks. Okta maintains a list of eligible events that can be queried on Okta's events page on the docs with the event-hook-eligible: parameter.

These are the events that appear on the Subscribe to events dropdown when creating a new event hook.

Here is a list of the eligible event groups:

• Device trust events
• Device identity events
• Security events
• User auth events
• Security authenticator lifecycle
• Admin privilege events
• User app events
• Rate limit events
• Group events
• User lifecycle events
• Certification events
• User import events
• Group lifecycle events
• Policy events
• Application lifecycle events

These groups are categories of events supported by Okta for Event Hooks. A group contains one or more events in it, and defines the general purpose of the events it contains.

As seen in the image above, the event categories appear above the list of events they contain. This grouping can serve as a useful guide in knowing the events you subscribe to.

Most popular use cases for Okta webhooks

There are numerous scenarios in which you can use Event Hooks, and as always it depends on your needs. Let's look at some of the most common use cases for setting up Okta Event Hooks.

Manage user information in external applications

Let's assume you have an external payroll system for your employees. This system is used to pay wages at monthly intervals. You want to ensure that once a new employee is added to your Okta organization, a payroll account is automatically set up for that employee. Also, when an employee leaves and their account is deactivated or deleted on Okta, you want to make sure they do not get paid anymore.

You can register for the User created and User deleted events under the User lifecycle events group. When a new user is added to your Okta organization, an event hook is fired to your external payroll system to create a new payment account for the user. When the user is removed from your organization, an event hook is also fired to your payroll system to remove/deactivate the user's payment account.

Authenticate users in external systems

Okta allows you to add applications to your organization so that with a single authenticated session, a user can have access to these applications. You may have some external and custom applications which cannot be added to Okta, but you want these applications to be accessed using the same authentication state the user has on Okta.

By subscribing to the authentication events under the User Auth events group (for example, the User logged out from Okta event), you can update the authentication state of users on your external application. This will enable you to grant users access to your external application based on their authentication state on your Okta organization.

Logging and analytics

Okta provides different types of reporting information under the Reports section of the admin page. However, you may need to build some custom reporting and data visualizations based on activities taking place in your Okta organization.

Event Hooks allow you to subscribe to information you're interested in and receive real-time updates. With this, you can build custom dashboards, charts, and log histories that get updated in real-time using data coming from Okta Event Hooks.

Let's say you want to track your users' authentication activities and access to your Okta apps in your organization — you can subscribe to events under the User Auth events, User App events , and User Lifecycle events groups to achieve that.

You can even go as far as monitoring the devices your users are signing in from using the Device trust events and Device identity events groups.

Detect suspicious activities in your organization

Okta allows users to report suspicious activities within an organization they belong to. This is a feature an administrator can enable within their organization.

Let's assume someone (most likely a malicious user) tries to use someone else's credentials to log into an Okta organization but then gets bounced by Okta's Multi-factor Authentication (MFA) system. The original owner of the account would receive an email reporting the activity as suspicious, and could choose to report this if they are unaware of the activity or ignore it if they are.

You can subscribe for the User reported suspicious activity event under the Security events group to get notified about the user's report immediately. This can help you take action promptly or log the information and mine it later for reports on the rate of suspicious activities taking place in your Okta organization over some time.

Okta usage notifications

This is most useful for system administrators and DevOps teams. The events under the Rate limit events group are fired when requests from a single client id is beginning to consume a worrisome amount out of an organization's rate limit.

This can help administrators increase their rate limit (if needed) or detect anomalies in their system setup that are causing the usage rate to go above estimated amounts.

A hacker may also be initiating an attack causing these notifications to be triggered, which administrators can immediately get notified about and take necessary actions.

Conclusion

Okta Event Hooks give developers an entry into the data Okta collects about its user's activities and application usage. This real-time notification and information sharing system allow developers to build custom integrations with Okta based on their organization's needs.

In this article we have taken a look at the common use cases for setting up Okta Event Hooks, and how we can make the best use of them. We will keep looking into more scenarios where Okta Event Hooks can be used and continue to share them here. Start working with Okta Event Hooks using Hookdeck today!