Castle Cloudflare Worker Sample

Overview

The Castle Cloudflare Worker allows you to put Castle's risk engine right on the edge, in a Cloudflare worker.

How it works

Once you've installed the worker and configured the CASTLE_API_SECRET, the worker will listen for POSTs to the /users/sign_up route.

The POST must include a Castle request_token, and optionally an email field that is used map events to existing users.

When the worker receives the POST, it will in turn make a POST to Castle, and receive a risk score in return. If result has deny action, then the worker will respond with a defined response. Otherwise worker with simply forward the request to the upstream.

Prerequisites

You'll need a Castle account and a Cloudflare account to get started.

Additionally you need to install the Castle.js script, which will be used to generate a unique "request token" for each request to your server. Without this request token, requests to Castle's API will be rejected.

Castle

If you don't have a Castle account already, you can set up a free trial. You will need your Castle API Secret, which can be found in the Settings section of your Castle dashboard.

Cloudflare

If you're going to use the Deploy with Workers option (see below), you'll need your Cloudflare account ID and an API Token.

Installation

There are two options for installing this worker, a "manual" method and a Deploy with Workers method.

Manual installation

1. Create or open the Cloudflare worker where you would like to install the Castle worker code.

2. Add Environment Variable to your worker:

   • CASTLE_API_SECRET — assign your Castle API Key to this variable.

   You can retrieve your CASTLE_API_SECRET from the settings section of your Castle dashboard.

3. Copy and paste the contents of the index.js file in this repo to your Worker.

4. Customize for your needs

5. Preview/Save and deploy!

Installation using Deploy with Workers

Press the Deploy with Workers button. You will be redirected to a dedicated deployment page.

Detailed Installation steps

1. Authorize GitHub with Workers

   Authorization allows to fork the project from Github and deploy it after finishing the setup.

2. Configure Cloudflare Account

   Add Cloudflare Account ID (CF_ACCOUNT_ID) and Cloudflare API Token with "Edit Workers" permissions (CF_API_TOKEN). They will be auto-uploaded as Github actions secrets.

   After this step, castle-cloudflare-worker-sample repository should be forked to your organization.

3. Deploy with GitHub Actions

   Navigate to Settings > Secrets tab of the forked repository.

   Update Repository Secrets — add Castle API secret available in Castle Dashboard as CASTLE_API_SECRET to Github actions secrets.

   Now you can finalize the deployment by pressing the Deploy button.