Skip to content

Protecting the password reset

Make sure you’ve first integrated the client-side integration in order to generate the “request tokens” required for each call to the Risk and Filter API.

Send $password_reset_request activity to track attempts to reset a user password, which can be an early signal of an account takeover. With an incorrectly implemented password reset flow, the attacker can run a user enumeration attack, which can be used to increase the success rate of an account takeover attack. By sending the below events to Castle, you can catch and mitigate fraud at an early stage. The Filter API returns a Castle risk assessment, which can be used to allow or deny the password reset request.

Once the user received the instructions on how to reset the password, typically an email or text message with a reset link, send the $profile_reset event to the Risk API to mark the completion of the reset flow. Note this event is named profile, not password, since it allows you to also track accounts that other types of resets such as their phone number or authentication method reset.

Step 1. Requesting the password reset#

The $password_reset_request activity can be sent at different stages of the reset request flow, which is denoted by setting the status field:

  • $attempted – The form was posted but hasn’t yet been validated by your backend. Useful when you want to use the Castle response to verify the request before the request email goes out to the account holder
  • $succeeded –  The password reset link was sent to the user
  • $failed – A user matching the request form field doesn’t exist
castle = ::Castle::Client.new

begin
  token = request.params['castle_request_token']
  context = Castle::Context::Prepare.call(request)

  res = castle.filter(
    type: '$password_reset_request',
    status: '$attempted',
    request_token: token,
    context: {
      ip: context[:ip],
      headers: context[:headers]
    },
    matching_user_id: 'ca1242f498', # Optional
    params: {
      email: request.params['email']
    }
  )

  if res[:policy][:action] == 'deny'
    # IMPLEMENT: Deny attempt
  end

rescue Castle::InvalidRequestTokenError
  # Deny attempt. Likely a bad actor bypassing fingerprinting
rescue Castle::Error => e
  # Allow attempt. Data missing or invalid, or a server or timeout error
end

Step 2. Completing the password reset#

The $profile_reset activity can be sent at different stages of the reset completion flow, which is denoted by setting the status field:

  • $attempted – The form was posted but hasn’t yet been validated by your backend. Useful when you want to use the Castle response to verify the user before the profile reset is completed
  • $succeeded – The user profile was reset
  • $failed – The user profile was not reset, likely because of validation errors
castle = ::Castle::Client.new

begin
  token = request.params['castle_request_token']
  context = Castle::Context::Prepare.call(request)

  res = castle.risk(
    type: '$profile_reset',
    status: '$succeeded',
    request_token: token,
    context: {
      ip: context[:ip],
      headers: context[:headers]
    },
    user: {
      id: 'ca1242f498', # Required. A unique, persistent user identifier
      email: 'mgray@example.com' # Recommended
    },
    changeset: {
      password: { changed: true }
    }
  )

  if res[:policy][:action] == 'deny'
    # IMPLEMENT: Deny attempt
  end

rescue Castle::InvalidRequestTokenError
  # Deny attempt. Likely a bad actor bypassing fingerprinting
rescue Castle::InvalidParametersError
  # Allow attempt. Data missing or invalid. Needs to be fixed
rescue Castle::Error => e
  # Allow attempt. Likely a server or timeout error
end

The changeset object#

The optional changeset object lets you specify which attributes were changed in the profile reset process.

JSON
changeset: {
  password: { changed: true },
  email: {
    from: 'original.email@example.com',
    to: 'new.email@example.com'
  },
  'authentication_method.type': {
    from: null,
    to: '$authenticator'
  },
  custom_property: {
    # ...
  }
}

For security reasons, the password field only accepts the changed: true value, whereas email, phone, name, and authentication_method.type accepts an object with from and to values.

Setting from to null means that the value was previously not set, and to to null means that the field was unset, for example in the case of authentication_method.type it could mean that a 2FA method was disabled.

In addition to the standard attributes, you can add any number of custom values, and they will all appear in the dashboard, however they will not be filterable like the standard attributes.

Taking action#

The response from the API call to Risk can then be used to take different actions. Typically, for profile updates, you’d want to ask the user to either re-authenticate using their password, or preferably by stepping up the authentication to a stronger factor.