Policies

Policies let you trigger custom risk logic when you call the Authenticate API endpoint.

Policies

Castle comes with a set of default Policies for each of the supported events. You’re able to modify the default Policies, and if you wish to restore the initial state there is a Changelog from which you can select the version you wish to restore.

Policies are grouped by event to give you a better understanding of the actions taken throughout the different points in your application; from registration to login to transaction. In each event group, Policies are evaluated in order, from top to bottom, and you can easily re-order them as you see fit.

Stage

Pre-authentication

Pre-authentication Policies are used to filter out bots and spam before the login, registration, or password reset request. Since the user won’t be authenticated in your application at this stage, any Risk Signals related to changes in user behavior, such as “New device”, won’t be available. Nor will Account Takeover Risk. This stage is similar to what you would get from a typical anti-bot or CAPTCHA tool.

A new environment will come with one default Policy per supported pre-authentication event. These Policies are configured to Deny by default, as it’s the recommended action to take for anonymous users. If you still want Challenge a user with something like a CAPTCHA pre-authentication, simply change the Action to Challenge, or create a new Policy.

Event Type Action Risk threshold
$registration.attempted Bot Deny 90
$password_reset_request.attempted Bot Deny 90
$login.attempted Bot Deny 90

Post-authentication

Post-authentication Policies lets you leverage a user’s historical behavior when configuring the risk logic. You’ll have access to more Risk Signals as well as the Account Takeover Risk. Once inside the application, the most common measure is to use the Account Takeover Risk to detect account takeovers, however, the Bot Risk is also available for when you’re primarily interested in addressing bot activity, for instance to prevent abusive transactions.

A new environment will come with one default Policy per supported post-authentication event, except for $login.succeeded that will have two complementary Policies in order to support both the Account recovery and Engaging your users use-cases.

Event Type Action Risk threshold
$login.succeeded Authentication Deny 90
$login.succeeded Authentication Challenge 60
$profile_update.attempted Authentication Challenge 60
$transaction.attempted Authentication Challenge 60

Segments

A Segment is a custom-defined filter that allows you to group users and events together based on criteria that are important to your business; for example “Sellers from outside the United States”, “Free users on mobile” or “Transactions over $100”. One Segment can be linked to one or many Policies.

Segments

Risk Score

Castle provides two types of Risk Scores. Both go from 0 to 100, where anything at 90 or above is considered abusive enough to outright deny, and normally anything over 60 is considered to be out of the ordinary and should be challenged with additional verification.

  • Bot Risk: Predicts the likelihood of the device being controlled by a bot, where 90 and above is very unlikely to ever be a human
  • Account Takeover Risk: Predicts the likelihood of a user being compromised, where 90 and above is very likely a credential stuffing attack

There is also an option to Ignore Risk Score, which is useful when you want to make a Policy rely on Segments and Risk Signals exclusively.

Risk Signals

Castle’s risk scores are calculated from thousands of data points, and a subset of these data points can be used as conditions in Policies as Risk Signals. A description of each Risk Signal can be found by hovering the question marks in the Policy Settings.

Verdict

Inline action

Defines what will be returned by the authenticate response as action, and is used to inform your application how to respond to the user.

The Action can be any of these three options:

  • Deny – the most severe Action where the recommendation is to deny the request
  • Challenge – ask the user for additional verification, for example two-factor authentication or identify verification
  • Allow – the request is safe and that the user can proceed with whatever they intended to do. This is the default value when no Policy triggered.

If the policy is configured to Log only, the selected action will not affect the action field in the inline API response, but a Threat will still be created. It will not break the policy execution chain, which allows you to review the impact of a Policy before setting it live.

Webhooks
In addition to the inline response, if the Action is set to Deny or Challenge, a Webhook may trigger depending on the state of the device.

Approval options

  • Until device is approved: The policy will only trigger until a Device is Approved through a feedback event such as a Inline challenge, Account recovery, or a User review.
  • Every time: The policy will trigger regardless of whether the Device is marked as Approved or not.