New

If you signed up before June 3, 2021, see the migration guide to learn about the recent API changes.

Automate account recovery

Using Castle to automate the account recovery process by leveraging the /track endpoint.

Summary

If you detect malicious activity on a user account, you should protect the account by locking permissions on the account, notifying the user, and forcing the user to reset their password. If you prefer not to force a password reset, you run the risk of teaching the attacker that evolving their credential stuffing tactics will eventually allow them access into user accounts, regardless of login protections in place. Forcing password resets at first sign of account breach prevents up to 25x more account breaches during a single credential stuffing attack.


Steps

  1. Send Password Reset Events to Castle
  2. Lock Accounts and Notify Affected Users
  3. Force Password Resets


Tutorial

  1. Send Password Reset Events to Castle
  2. Lock Accounts and Notify Affected Users
  3. Force Password Resets

Step 1. Send password reset events to Castle

To Complete this Step:

  1. Send Password Reset Events
  2. Verify Password Reset Events in the Dashboard

Send password reset events

Send event: "$password_reset", status: "$succeeded" to Castle’s /track endpoint when a user successfully completes a password reset of their account.

Before we begin automating user account recovery, we first need a mechanism by which we can automatically determine that an account has been recovered. This event will tell Castle that any active threats to a user account have been mitigated. This important piece of the puzzle allows your Castle reporting to stay current and accurate.

Note: it is often a wise decision to use multiple authentication factors when allowing a user to perform a password reset. Use authentication mechanisms that are appropriate for your risk tolerance. Castle trusts that you have adequately authenticated a user that is able to reset their account password.

Verify password reset events in the dashboard

Verify that the password reset events are visible under user account views in the Castle Dashboard.

a screenshot of the Castle Dashboard User view, showing a password reset event in the user history
The user event history shows a password reset event

Step 2. Lock accounts and notify affected users

This step assumes that you are subscribed to the $incident.confirmed webhook. Visit our documentation about Webhooks for details on webhooks.

To Complete this Step:

  1. Lock User Accounts for Confirmed Incidents
  2. Notify Affected Users

Lock user accounts for confirmed incidents

When you receive the $incident.confirmed webhook from Castle, this means that a deny verdict was issued in accordance with your Castle Policy. The policy details are included in the webhook. You should consider this webhook to be a notice of a security breach.

Castle recommends that you lock user accounts at this point. While Castle will continue to issue the deny verdict inline, preventing the bad actor’s device from logging into the user account, the underlying problem needs to be addressed: the account credentials can no longer verify that the bearer is the account owner. The credentials have been leaked and abused.

Notify affected users

You may be familiar with email notifications of account breaches. These emails can be used as a courtesy notification to users, and as a means to establish trust with your users.

A screenshot of a mock email with details such as timestamp, IP, and device that was used to access a user account
An example of an email that can be sent to a user to notify them of an account breach

Castle’s Webhooks provide many details that will allow you to craft detailed messages about the user’s account breach. Details can include location, time, and device information. It’s up to you to brand your communications and convey information to your users in order to maintain their trust. Castle does not offer templates or direct integrations with notifications providers.

Step 3. Force password resets

This is a straightforward step to complete - make sure that users are forced to change their passwords in order to unlock their accounts.

Good password policies include (among other things) a requirement that no prior passwords are used. You should enforce this unique password policy in order to minimize the success rates of bad actors in future credential stuffing attacks.

Another topic that you should consider is enforcing multiple means of authentication for the password reset event. Since it is known at this point that the user’s password is exposed, you might want to consider that the user’s email address may be compromised (if they share the password across services). Castle can be integrated with the $password_reset_request event in order to evaluate the risk of the device performing the password reset. Alternatively, we recommend that you implement a second form of authentication, such as a knowledge-based challenge or a one-time-passcode via SMS, as part of the password reset process.

Once a user changes their password, Castle will receive an API call to /track with event: "$password_reset", status: "$succeeded" (from step 1) and the Threat on that user’s account will be marked “Mitigated”.