Overview

Policies let you trigger custom risk logic when you call Castle's /risk or /filter API endpoints. Each API response will contain a policy object with the matching policies, and a policy.action field set to allow, challenge, or deny.

---

How policies work

Customization

Policies apply to Segments, which are sets of filters that allow you to select things like device traits, user traits, or event properties to group events. The default Segment is "All Events".

Configuring Segments is an advanced topic, but it allows Policies to become infinitely customizable. To configure a target segment, visit the Policy segments page in the Castle Dashboard.

Event evaluation

When a Policy returns a verdict (such as action: challenge in the Castle /risk response), these things have occurred in order:

1. Event (i.e. $login) sent to Castle /risk endpoint
2. Event has a Policy configured (i.e. "Deny" for $login)
3. Event context matches the Segment filters specified in the Policy
4. Event evaluated for risk scores and risk signals defined by Policy
5. Event Risk Score/Signals meet the Policy definition (i.e. risk 90+), so deny is returned

Versioning

Castle comes pre-configured with several Policies. You’re allowed to modify these default Policies. If you wish to restore previous states of Policies, there is a Changelog from which you can select the version you wish to restore.

Organization

Policies are grouped by event to give you a better understanding of the actions taken throughout the different points in your application. These events include registrations, logins, profile updates, transactions, and password resets.

Policies are evaluated in order, from top to bottom, for each event grouping. You can easily re-order them as you see fit. The most narrow-scope and restrictive policies (i.e. deny) should usually be at the top of the list because they should be evaluated for matches first.

Creating a policy

Step 1. Create a new policy

To complete this step:

1. Click "Create a New Policy"
2. Enter a Policy Name
3. Select a Triggering Event (i.e. $login, $registration, etc.)

Step 2. Configure the policy

This step has multiple parts, which are all part of the "Configure a Policy" widget. Each part is covered below

Step 2a. (optional) Choose the triggering segment

To complete this step, select the Triggering Segment that will trigger evaluation for matches to this policy.

Configuring a Segment is an advanced use-case that becomes easier after you have started sending traffic that matches your Policy. A Segment is a set of event-property-based filters. Segments are matched prior to Policy evaluation.

You can view and filter the last 100 events sent to Castle's /risk endpoint via the Castle Dashboard Segments Tool. This is the easiest way to verify filter performance when creating Segments.

The default segment for a policy is "All Events".

If you are configuring your new policy prior to defining the target segment, no worries! You can click the "Create New" button next to the Segment selector, and the configurator will allow you to define a new segment. Return to the "Policies" page when you are finished to continue where you left off.

Step 2b. Choose the verdict

The verdict is the inline action that Castle's API response returns to your application: allow, challenge, or deny.

To complete this step:

1. Select the action that you want delivered when this policy evaluates to true
2. (Optional) Make this a Log Only policy for evaluation purposes

Choose whether you want the Castle API response to include action: deny or action: challenge when this policy evaluates to true. Also select whether the device that receives this verdict should receive the verdict every time this policy triggers, or only if the device is unapproved.

Step 2c. Adjust risk score

You can modify the risk score range for which the policy evaluates true. Castle recommends these default settings:

• 60-100: challenge
• 90-100: deny

The reason there is overlap in the scores is that deny policies should be ordered above challenge policies, so they will always be evaluated first. That way, if you have a need to disable a deny policy, the events that used to receive deny verdicts will receive challenge verdicts.

Step 2d. Risk signals

Castle calculates many risk signals based on event properties, and we expose a handful of often-requested signals here for you to use in order to force specific verdicts when you see these signals. The configuration UI contains informative explanations for the signals, so please refer to your Dashboard Policy Configuration page for details.

Step 2e. Device risk memory

Castle can "remember" the risk of a device. This becomes useful when, for example, a device triggers a challenge verdict because it matches one custom Policy, but the next time that device is used it does not match the same custom policy. You can choose whether Castle should "remember" the device risk in order to deliver a challenge or deny verdict in the future, when the future contextual risk would otherwise have Castle return an allow verdict.

Step 2f. Summary

Click the "Summary" button to read a summary of your policy. This summary should make sense based on the settings you configured. It might be good to have a team member double-check the policy summary.

Step 3. Enable and reorder

To complete this step:

1. (Optional) Reorder the policy to an appropriate position
2. Enable the policy

When you have multiple Policies for the same event, there is no harm in having policies overlap in their triggers or definitions, but Policy ordering becomes very important. You will notice that Castle's default policies enable deny verdicts for risk score ranges 90-100, and challenge verdicts for risk score ranges 60-100. This is fine, as long as the deny policy is evaluated before the challenge policy. Otherwise, if the deny policy were below the challenge policy, the deny policy would never have a chance to evaluate to true because the challenge policy would always be the first-matched policy for that event.

The most important thing to consider here is that policies are evaluated in top-down order. For most cases, this means that deny policies should be ordered above challenge policies. If you are unsure about the effects of reordering your policies, you can create Log Only policies to evaluate these effects before modifying the "real" enabled policies.

Use-cases

Setting up an IP blocklist

You will need to set up a Policy, as well as a Policy Segment to accomplish this. Once you've set that up, it will be straightforward to add IPs to it in the future.

First, you'll create the Policy Segment, add an IP filter, and add an IP address to it. Save the Segment as "Blocklisted IPs".

Then, you'll create a Policy to always Deny for All Events, and you reference the "Blocklisted IPs" Segment.

If you make sure this Policy is ordered to trigger first, it will return a "deny" response every time an IP matches what you've put into the Policy Segment.