Setting rules with DFP

Stytch's Device Fingerprinting (DFP) offers a fully featured automatic risk assessment and recommendation action (ALLOW, CHALLENGE, or BLOCK) that tells your application how to handle each request.

However, in some cases you may need to create authorization rules which enable increased or reduced friction for previously fingerprinted instances - for example manually ALLOW a user due to a false positive, or BLOCK an authentic user who violated the ToS of your application.

To do this, you’ll use the Set Rules endpoint. In this guide you'll learn how to set up rules with DFP. By the end, you'll have:

• Called the Set Rule endpoint to apply an authoritzaion action on a specific fingerprint.

• Removed the rule.

In order to complete this guide, you'll need the following:

• A Stytch project (either Consumer or B2B). If you don't have one already, sign up for a Stytch Workspace.
• The project Test environment's project_id and secret from the API keys section. You'll need to pass these values into the Authorization request header for most Stytch API calls.
• Device Fingerprinting enabled. If you don't have the product enabled, reach out to Stytch here.

When setting any rule there one thing to keep in mind is social engineering.

For example, is the user that is asking for the ALLOW a bad actor that is trying to get more access.

When setting an ALLOW rule for a customer who reaches out, you should confirm that the user is a good actor and should be allowed access to your application.

First, you'll need a fingerprint you want to set a rule for. These fingerprint identifiers are generated by the Fingerprint Lookup endpoint from the telemetry_id.

When making rules, consider the granularity and other characteristics of the fingerprint to avoid making a rule that unintentionally affects good users. Ensure that the fingerprint you adjust is as tightly scoped to your desired outcome and make sure that interactions with other rules already set will have the appropriate effect.

For instance:

• visitor_id with an ALLOW rule takes precedence over a network_fingerprint with a BLOCK rule.

• A rule against a visitor ID only affects a single visitor while a network or hardware fingerprint could block all iPhones of a specific model.

See the table below for uniqueness, stability, and precedence characteristics of each fingerprint type:

Before setting a rule, you should compare the fingerprint against your historical traffic if available.

You can go to the DFP dashboard or any internal dashboards you may have and look up the various fingerprint types to identify the uniqueness.

• When you search a fingerprint in the Stytch Dashboard, it will show how frequently other fingerprint types have had that fingerprint. You should make sure the percentage of ALLOWs isn’t too high.

• In addition to the Stytch Dashboard, you should cross reference your fingerprint with your own internal monitoring to verify that the rule won't affect other valid users. You should look to see how much overlap the new rule would have on other users.

Next, you’ll set a custom rule via either the Stytch Dashboard or a direct API call.

Dashboard [BETA]API

1. Navigate to Device Fingerprinting -> Authorization Rules in the Stytch Dashboard.
2. Select “+ New Rule”
3. Enter the fingerprint, for example a visitor_id or browser_id.
4. Set action to ALLOW, BLOCK, or CHALLENGE.
5. Optionally set an expiration time and a description for the rule.
6. Click “Save”

You'll call the Set Rule endpoint with the following body parameters in the request:

• The fingerprint, for example a visitor_id or browser_id.
• An action set to ALLOW, BLOCK, or CHALLENGE.
• An optional expires_in_minutes set to a specified int.

curl --request POST \
  --url https://telemetry.stytch.com/v1/rules/set \
  -u 'project-test-16a5c23c-fc81-42af-ac51-3cf03efe93f7:secret-test-8ezLWb0H2mB8hAtxSzMonWBKvBmjehFDQFE=' \
  --data '{
	"visitor_id": "visitor-6139cbcc-4dda-4b1f-b1c0-13c08ec64d72",
	"action": "BLOCK"
}'

Upon a successful API call or Dashboard action, in the example request above, the rule directs Stytch to BLOCK any fingerprint with a matching visitor_id from now on. Any future calls to Fingerprint Lookup endpoint involving this fingerprint will automatically return a BLOCK verdict with a reason of RULE_MATCH.

To learn more about the actions like BLOCK, ALLOW, or CHALLENGE, check out our DFP overview.

You also have the option of providing an expires_in_minutes parameter if you need a rule to expire after a specified lifetime. Since expires_in_minutes was omitted in our example request, the rule will be kept permanently.

To remove a rule you've set, call the same Set Rule endpoint with the following body parameters in the request:

• The same visitor_id or browser_id from step 2.
• An action set to NONE.

curl --request POST \
  --url https://telemetry.stytch.com/v1/rules/set \
  -u 'PROJECT_ID:SECRET' \
  --data '{
	"visitor_id": "visitor-6139cbcc-4dda-4b1f-b1c0-13c08ec64d72",
	"action": "NONE"
}'

To enable Device Fingerprinting for your project, please reach out to Stytch.