Failed authentication events: use cases and how-to

They say that ignorance is bliss but we believe that it can also be very dangerous. Ignoring problems does not make them go away and when it comes to failed authentication events, time only makes it worse as your app’s availability is compromised. It’s best that you know there is a problem as soon as possible.

In this article, we will see the failed authentication events that WorkOS logs, how you can get them, and what use cases they unlock for your app and your customers.

Use cases for failed authentication events

Failed authentication events can be very useful both from a security and a UX perspective. You can use them to identify problems or potential attacks. In this section we will see some of these use cases and how you can use failed authentication events to implement them.

Block login after X failed attempts

When you can identity how many times a user tried to authenticate and failed, you can enforce certain rules in your app. For example you could:

• Lock a user account after X failed login attempts.
• Send the user an email to reset their password and unlock their account.
• Unlock the account after X hours and let the user try again.

To implement something like this you would need a timestamp for the last password attempt and a counter for failed password attempts. Every time a user fails to login you can increase the counter if their last attempt was within X minutes.

This way you can protect your app and also be compliant with any standards you follow. For example, deactivating users after X failed login attempts is a requirement for the PCI DSS (Payment Card Industry Data Security Standard) 4.0, a standard designed to help organizations that handle credit card information keep that information safe and secure.

Another way to protect your application from abuse, fraud, and attacks, is by using Radar, a feature that builds on top of AuthKit’s user management and hosted forms to collect signals on the behavior of users as they sign in to your SaaS app. These signals feed into an engine that is looking for abusive or anomalous behavior. When Radar detects a suspicious authentication attempt, it can block or challenge that attempt based on the settings you configure.

Monitor for errors in connections

You can set up alerts so that when SSO sessions fail your admins are informed that there might be an issue. For example, if one of your SSO connections has a certificate issue you will start seeing failed SSO login events. In this example, if your app is monitoring for an uptick in authentication.sso_failed it can sound an alarm so you proactively check for and fix any issues.

Failed authentication events

WorkOS currently emits the following failed authentication events:

• authentication.sso_failed
• authentication.oauth_failed
• authentication.password_failed
• authentication.magic_auth_failed

The following are coming soon:

• authentication.mfa_failed
• authentication.email_verification_failed

You can view all emitted events at the WorkOS dashboard> Events.

Event: authentication.sso_failed

Triggered when a user fails to authenticate with Single Sign-On.

	
{
  "event": "authentication.sso_failed",
  "id": "event_01JD5N7CKVE9K641963QV2P6GW",
  "data": {
    "type": "sso",
    "email": null,
    "error": {
      "code": "redirect_uri_invalid",
      "message": "The redirect_uri 'http://localhost:5173' is not on your allow list."
    },
    "status": "failed",
    "user_id": null,
    "ip_address": "24.0.103.216",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
  },
  "created_at": "2024-11-20T20:46:36.667Z"
}
	

Event: authentication.oauth_failed

Triggered when a user fails to authenticate via OAuth.

	
{
  "event": "authentication.oauth_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "oauth",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "invalid_credentials",
      "message": "Invalid credentials."
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z"
}
	

Event: authentication.password_failed

Triggered when a user fails to authenticate with password credentials.

	
{
  "event": "authentication.password_failed",
  "id": "event_01JC6365JA4ADRK8NNN50KS2ZA",
  "data": {
    "type": "password",
    "email": "kate@example.com",
    "error": {
      "code": "invalid_credentials",
      "message": "Invalid credentials for 'kate@example.com'."
    },
    "status": "failed",
    "user_id": null,
    "ip_address": "24.0.103.216",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
  },
  "created_at": "2024-11-08T14:34:54.922Z"
}
	

Event: authentication.magic_auth_failed

Triggered when a user fails to authenticate via Magic Auth.

	
{
  "event": "authentication.magic_auth_failed",
  "id": "event_04FKJ843CVE8F7BXQSPFH0M53V",
  "data": {
    "type": "magic_auth",
    "status": "failed",
    "user_id": "user_01E4ZCR3C5A4QZ2Z2JQXGKZJ9E",
    "email": "todd@example.com",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36",
    "error": {
      "code": "authentication_method_not_allowed",
      "message": "Google OAuth is disabled."
    }
  },
  "created_at": "2023-11-18T04:18:13.126Z"
}
	

How to get failed authentication events

You can get failed login events from WorkOS in the following ways:

• Listen for failed auth events using the Events API.
• Register webhook endpoints to get notified.
• Stream events to Datadog and use their dashboard and alerting.

Sync with the Events API

One way to get failed authentication events from WorkOS, is by listening for them using the Events API.

The Events API is a strictly ordered list of immutable events exposed through a paginated API. Each event includes a sortable ID, type, and data payload. The API ensures events are returned in a consistent order using cursor pagination. This solves two big problems that webhooks have: out-of-order updates and spiky throughput.  It’s an ideal webhook alternative for applications where data consistency and integrity are non-negotiable.

The steps to integrate with the Events API are:

1. Integrate the Events API SDK: Choose an available language or contact us to request an SDK.
2. Create a cursor: A cursor is a bookmark to track your app’s position in the events list. The very first call to the events API won’t have a cursor. Subsequent requests to WorkOS should include the updated cursor using the after parameter.
3. Update your cursor: You will need to update and store your cursor after processing an event in order to maintain your position in the event stream.
4. Select event types: Select the events you want to consume. Retrieve events from the API using cursor pagination. To fetch the next set of events, provide the ID of the latest processed event in the after parameter. For example, the following code snippet retrieves all the failed authentication event types using Node.

	
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const listOfEvents = await workos.events.listEvents({
  events: [
    'authentication.magic_auth_failed',
    'authentication.oauth_failed',
    'authentication.password_failed',
    'authentication.sso_failed',
  ],
});
	

For details on how to handle event replay, choose a cursor if you lose yours, and more, see Sync data using the events API.

Sync with webhooks

One way to get failed authentication events from WorkOS, is by using webhooks and have the events pushed to your app.The steps to set up webhooks are:

1. Create your endpoint to receive webhook events: Create a public endpoint that WorkOS can send events to. This endpoint should use HTTPS and should accept POST requests with the workos-signature header.
2. Register your endpoint with WorkOS: Set and save the webhook URL in the WorkOS dashboard, so WorkOS knows where to deliver the events. Your webhook endpoints should only be configured to receive the ones required by your integration. Receiving all event types can put undue strain on your servers and is not recommended.
3. Process the events received from WorkOS: In order to avoid unnecessary retry requests hitting your webhook handler, we recommend using two concurrent processes for handling events: one for receiving the event, and the other for processing it. For more details on how you should properly process events see the docs.
4. Test your endpoint: After configuring the endpoint, send test webhook events from the WorkOS dashboard. If you would like to test against your local development environment, we recommend using a tool like ngrok to create a secure tunnel to your local machine, and sending test webhooks to the public endpoint generated with ngrok. For more details on how to do this see How to Test WorkOS webhooks locally with ngrok.

For more details on the above and best practices see the docs.

For info on how to manage multiple events, implement clear error handling, debug webhook responses, and validate event types properly, see this video.

‍For more on webhooks vs the Events API, see Why you should rethink your webhook strategy.

Stream to Datadog

WorkOS supports real-time streaming of events to Datadog. You can push all failed authentication events there and use their dashboard and alerting.

The steps to stream events to Datadog are:

1. Create a Datadog API key: Create a new Datadog API key to give WorkOS permission to send event activity as logs to your Datadog account. While you can use an existing API key, WorkOS recommends creating a new key that will only be used for WorkOS event streaming.
2. Configure event streaming in WorkOS: Go to the WorkOS dashboard > Events and choose the Stream to Datadog button. Enter the Datadog API key and region. WorkOS will send new events to Datadog with the source workos.

For more details on how to configure this see the docs.

Data reconciliation

There may be cases where your app gets out of sync. For example, your app may have a bug in its event processing logic or in rarer cases, may experience some data loss. Depending on the scope of the issue, you can reconcile your app state by either replaying events from the Events API or by using the WorkOS API.

Reconciling via the Events API

In general, reconciling state changes between WorkOS and your app using the events API is simplest. Pick your cursor, which is usually the last known cursor you have processed, and paginate through events using the after parameter.

For special cases such as webhook migration or event replay, you can specify a starting time for event consumption using the range_start parameter.

Reconciling via the API

Your app may perform data reconciliation by syncing state via the WorkOS API e.g., in disaster recovery scenarios.This requires performing diffs to identify deletions to ensure the correct state is maintained.

The general approach for reconciling data is as follows:

1. Pull state from WorkOS API for the objects your app is interested in. For example, to reconcile organizations data you would pull state from WorkOS using the List organizations, while for users the List users.
2. Update based on updated_at. If the timestamp is out of date, update the object.
3. Identify deactivated objects or deletions and sync that state.

If you need to force all objects to update state, perform a complete resynchronization of the affected data instead of relying solely on the updated_at timestamp. Update all objects regardless of the individual updated_at timestamp.

For more on data reconciliation see the docs.

Conclusion

Identifying failed authentication events unlocks use cases that keep your app more secure. By proactively identifying and solving issues with connections you minimize the impact on users and ensure that your app’s availability is high.

WorkOS can help you with that by providing these failed authentication events to your app.

‍Sign up for WorkOS and start building today.