Guides
Sign Up
Start typing to search…

Rules Engine and Flow deployments (Beta)

Protect your application with rules based on Fingerprint device intelligence. Deploy Fingerprint protection to the edge without touching your application's code.

🚧

Feature in Beta

This feature is currently in a Beta testing phase with select customers. We recommend testing it inside an isolated staging environment. All feedback is welcome! If you encounter any issues, please contact your Customer Success representative.

Pre-requisites

  • A Fingerprint account with an Admin or Owner role.
  • A website proxied (not DNS-only) through Cloudflare.

Rules engine

The Rules Engine allows you to define an event ruleset — a collection of rules evaluated against a Fingerprint identification event, including the Visitor ID and Smart signals.

For example, you might want to prevent browsers in incognito mode from creating accounts in your application:

  1. Open the Fingerprint Dashboard.
  2. Navigate to Rules Engine.
  3. Click + New ruleset. You will see a canvas with an initial "Identify visitors" node.
  4. Click + Add rule.
  5. Choose the Browser incognito detection Smart Signal as the rule condition.
  6. Click on the added rule to start editing it using the right-hand sidebar.
  7. Make sure the If Incognito condition is set to True.
  8. Optionally, in the Then section, adjust the Status or the Body of the response, for example {"message": "Incognito not allowed"}
  9. In the top right corner, click Save to save your changes.

The ruleset is saved right away, but it can take up to 60 seconds for the changes to propagate.

Rule condition

A rule condition is a logical expression like

  • IF VPN is True
  • IF Suspect Score is greater than 10 AND IPv4 Country Code is CN
  • IF Incognito Mode is True AND Returning visitor is True AND (Anti-Detect Browser is True OR Privacy-focused Settings is True)

The simplest condition is a single comparison (for example, VPN is True), consisting of the event property (VPN), operator (is) and value (True).

You can combine multiple comparisons using logical operators (AND and OR) and groups.

Note: To keep things simple, you must use the same logical operator between all comparisons within a group.

  • You cannot represent a condition like a AND b OR c.
  • But you can do a AND b AND c, a OR b OR c, a AND (b OR c).

Rule name

A rule name is generated based on the initial comparison property. You can rename rules by clicking the name at the top of the rule form sidebar.

Rule action

A rule action defines what happens to the client request if the condition is true. There are two options:

  • Block with response — the client (browser) request is not allowed to reach your application origin server, and a predefined response is returned to the client.
    • You can define the headers and body of the returned response.
  • Allow with headers — the client request is forwarded to your application origin server as normal.
    • Optionally, you can modify the request headers to pass additional, predefined information to your server.

The system assumes that rule evaluation and action processing occur between your application's client (e.g., your website) and its origin server (e.g., your backend). See Flow deployments for more details.

Multiple rules

Each ruleset contains an ordered collection of rules. You can add a rule by clicking Add rule underneath your last rule on the canvas.

  • Rules are evaluated first to last (top to bottom).
  • When a rule is matched (its condition is true), the ruleset evaluation stops (no more rules are checked).
  • The action of the matched rule is returned as the ruleset evaluation result.
  • If no rules are matched, the ruleset evaluates to an Allow action without any header modifications.

Ruleset settings

Click the Settings tab at the top to access ruleset settings. Here you can:

  • Change the ruleset Name.
  • Change the ruleset Description.
  • Enable or disable a ruleset.
    • A disabled ruleset always evaluates to a simple Allow action without any header modifications. It is equivalent to a ruleset with zero rules.
  • Deploy with Cloudflare — deploy the ruleset using a Flow worker.
  • Delete the ruleset. Note that if the ruleset is deployed, you need to remove the deployment first.

An undeployed ruleset is just a row in the Fingerprint database. To actually use the ruleset, you can deploy it to Cloudflare using a Flow worker.

Flow deployments

Flow is a no-code Fingerprint deployment method, currently supported for websites hosted on Cloudflare. For a conceptual overview, see How Cloudflare Flow deployments work.

For example, you can deploy the ruleset defined above to protect the POST api.yourwebsite.com/create-account API, called from the yourwebsite.com/signup page.

  1. Open your ruleset and switch to the Settings tab.
  2. Under Deployment, click Deploy with Cloudflare.
  3. Enter your Cloudflare Account ID, your Cloudflare Token, and click Validate.
    1. You can get your Cloudflare Account ID from the Cloudflare Dashboard -> Workers and Pages, on the bottom right corner of the page.
    2. You need to get or create a Cloudflare token with the following permissions:
      1. Workers Scripts:Edit
      2. Workers Routes:Edit for the zone the worker will use
      3. DNS:Read for the zone you want to deploy to
  4. Pick the environment of the Public and Secret API keys generated for the deployment.
  5. Define at least one page for identifying visitors. For example, to identify visitors on your sign-up page, add:
    1. [no subdomain]
    2. yourwebsite.com
    3. /signup
  6. Define at least one API endpoint to protect with your ruleset. These protected APIs need to be called from the pages in the last step. They can be on a different subdomain, but must be inside the same zone. See How Cloudflare Flow deployments work for more details. For example, to protect the sign-up endpoint, add:
    1. api.
    2. yourwebsite.com
    3. POST
    4. /create-account.
  7. Click Create Cloudflare worker.

Within a few seconds, the Flow worker is deployed into your Cloudflare account.

  • You can open your Cloudflare dashboard to confirm.
  • You can navigate to the identification page in Incognito mode and try triggering the protected API. You will be blocked by the ruleset and receive the response you defined in your rule action.
🚧

Note: The Flow worker will start intercepting protected requests and applying rules immediately after deployment. Any errors in the request instrumentation (e.g., missing or corrupted browser data) will be treated as tampering attempts and blocked with a 403 Error response from the Flow worker.

  • We recommend testing your ruleset and Flow deployment in a separate staging environment before applying it to production.
  • You can deploy an empty or disabled ruleset first to test the Flow worker without applying any rules.
  • You can delete the Flow deployment at any time using the Fingerprint Dashboard, or even manually remove the worker from your Cloudflare dashboard if needed.

Route pattern matching

The identification pages and protected APIs are converted to Cloudflare worker route patterns and follow the same format and matching behavior.

  • Each Cloudflare route can only be served by one Cloudflare worker. If you try to use a route pattern already served by another worker, your deployment will fail.
  • You can use a wildcard (*) at the end of the path but not in the middle of it.
  • Using a wildcard suffix (/path*) is required to match requests with query parameters like path?query=value.

Note: You might encounter edge cases where Cloudflare caching interacts with wildcard route matching in a way that produces unexpected behavior. In that case, do not hesitate to contact our support team. Defensively using both the base and wildcard variants of the path (path and path*) can help.

Editing Flow deployments

You can update your Flow deployment any time:

  1. Navigate to <Your ruleset> > Settings tab.
  2. Under Deployment, click ⋯ (More actions), then Edit worker.
  3. Add, remove, or update the identification pages and protected APIs.
  4. Click Save and redeploy to save your changes.

This redeploys the Flow worker with the updated configuration. Do not make manual changes to the worker code or environment variables directly through Cloudflare as they will be overwritten by Fingerprint on the next redeployment.


📘

Rules are part of the Ruleset, not the Flow deployment

  • The Flow worker only knows its Ruleset ID. Rulesets are stored and evaluated inside the Fingerprint platform, not on Cloudflare.
  • To update rules, make changes to the Ruleset and save it. It might take up to 60 seconds for the changes to take effect on your website.
  • We reccommend testing your rule changes in a separate staging ruleset and staging web environment before applying them to production.

Deleting Flow deployment

To delete the Flow deployment:

  1. Navigate to <Your ruleset> > Settings tab.
  2. Under Deployment, click ⋯ (More actions), then Delete worker.
  3. Confirm by typing your domain name and clicking Delete deployment.

This completely removes the Flow worker and its associated routes from your Cloudflare account. The ruleset itself remains stored in your Fingerprint workspace. Note that you cannot delete a deployed ruleset without removing the Flow deployment first.

How Cloudflare Flow deployments work

  • Using your Cloudflare API token and credentials, Fingerprint deploys a Cloudflare worker on your domain, which intercepts HTTP requests between browsers accessing your website and the origin server.
  • When serving the pages that identify visitors (for example, yourwebsite.com/signup page), the worker injects the Fingerprint JavaScript agent and an instrumentation script into the page markup.
  • For HTTP requests to APIs you want to protect (for example, the POST api.yourwebsite.com/create-account request), the instrumentation script collects information about the browser configuration and attaches it to the request as a custom header, fp-data.
  • The Flow worker intercepts the protected request and sends the browser information to the Fingerprint Identification API alongside the ruleset ID. In return, it receives the identification event and the rule action produced by evaluating your ruleset.
  • The Flow worker processes the rule action by blocking the protected request or allowing it to reach the origin server as normal.
  • The Flow worker code is open-sourced on GitHub.

Current limitations

  • You can define a maximum of 10 identification pages and 10 protected APIs per Flow deployment.
  • You must define at least one identification page and one protected API per Flow deployment.
  • Customizations of the JavaScript agent behavior such as tags, linked IDs, custom timeout, etc., are not supported at this time.

Troubleshooting

If you encounter any issues with your Flow deployment, you can:

  • Use the Fingerprint Dashboard > Identification page to confirm that Flow deployment is generating identification events as expected. Note that any Smart Signals not enabled for your workspace will always evaluate to false.
  • Hard reload the identification page of your website to ensure you are getting the latest version from the Flow worker. Look for instrumentor.iife.js in the Network tab of your browser's developer tools to confirm.
  • Make sure the protected API is actually called from the identification page you defined. Use the browser's developer tools to confirm that the fp-data header is being attached to the request.
  • Navigate to your Cloudflare dashboard to confirm the worker configuration matches your Flow deployment (worker code, environment variables, routes, etc.).
  • Enable Worker logs and examine them for errors. Any error returned from the Fingerprint Identification API will only be visible here, not propagated to your application.
  • Most common errors include Request filtering blocking identification requests by origin.
  • Contact our support team. Include relevant logs or screenshots of the above to aid troubleshooting.

Updated about 5 hours ago