Castle policies

Using Castle policies to customize in-application risk management workflows

Prerequisites

Your application must already be sending relevant events to the Castle API /authenticate endpoint. This can be verified via the Castle Dashboard Debugger or the Castle Dashboard Policy Segments tools.


Steps

  1. Create a new policy
  2. Select the event and triggering segment
  3. Select the verdict
  4. Adjust risk signals
  5. Enable and reorder

Summary

Policies let you trigger custom risk logic when you call Castle’s /authenticate API endpoint. Castle’s Policies are arranged by event name, and the default Policies apply to “All Events” of an event name (i.e. all $login.succeeded events).

Policies only evaluate traffic sent to /authenticate.

Policy configuration is a Castle Dashboard experience. In order to configure Policies, your application must already be sending relevant events to the Castle API’s /authenticate endpoint. Please refer to our tutorials in the Relevant Links above for guidance in sending these events to the Castle API.


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 /authenticate response), these things have occurred in order:

  1. Event (i.e. $login.succeeded) sent to Castle /authenticate endpoint
  2. Event has a Policy configured (i.e. “Deny” for $login.succeeded)
  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
a screenshot of Castle Policies for $login.attempted and $login.succeeded events
Castle Policies

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.

a screenshot showing a Policy changelog
A Policy Changelog Allows Reversion to Prior Versions

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.


Tutorial

Step 1. Create a new 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.succeeded, $registration.attempted, etc)
screenshot of the first modal shown when clicking 'Create a New Policy'
Create a New Policy

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 /authenticate 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”.

screenshot of segment choices in policy configuration
Choose a Segment for this Policy to Target

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
screenshot of verdict options in a policy
Choose a Verdict, and optionally enable Log Only

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 because 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.

screenshot of risk score configurations in a policy
Choose a Risk Score Trigger, score range, and additional Risk Signals

Step 2d. Risk signals

Castle calculates many different 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.

screenshot of risk signal configurations in a policy
Choose risk signals that will trigger the policy

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.

screenshot of the remember device risk setting in a policy
Choose whether the device risk should be remembered

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 so 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.