Fastly Integration Workflow
The Fastly integration lets you deploy Monocle without changing your application code.
This is the no-code setup path for customers who serve traffic through Fastly. Once configured, Monocle assesses traffic on the domain you choose and surfaces results in the dashboard.
Blocking is only applied when policy-based enforcement is enabled.
How it works
The Fastly integration deploys a Compute service into your Fastly account, named spur-monocle-<app id>, and moves the protected domain onto it. The service sits in front of your site: every request is assessed, and verified traffic is forwarded to your origin.
Alongside the service, Monocle creates two account-level stores, both named after the app:
- A Config Store holding the integration's configuration: the assessed and enforced paths, the excluded paths, the block response and the origin settings
- A Secret Store holding the app's secret key and the cookie-signing secret
Monocle manages all of this through the API token you connect. Configuration changes made in the dashboard are written to the Config Store, which the running service reads live, so most changes apply without a redeploy.
You can use the integration to:
- Assess traffic without adding code to your site
- Choose which pages on the domain Monocle assesses, and which it leaves alone
- Configure a block response
- Keep your existing Fastly service in the request path (chaining)
- Redeploy when plugin updates are available
- Remove the service when it is no longer needed
Before you begin
You need access to:
- A Fastly account with the domain you want to protect already served by Fastly
- Permission to create a Fastly API token with the Global scope, from a user with the Engineer or Superuser role
- An account with Compute enabled (a free trial is available under Account → Products)
Create a Monocle app
To start the Fastly integration:
- Create a new Monocle app.
- Enter the app name.
- Choose Fastly as the integration type.
- Continue to the Connect Fastly step.
Connect your Fastly account
In Fastly, go to Account → API tokens → Personal tokens and select Create token.
| Setting | Value |
|---|---|
| Type | User token |
| Scope | Global API access |
| Access | All services |
| Expiration | Never, or a date you will renew before |
A user token has the permissions of the user who creates it, so it must belong to a user with the Engineer or Superuser role: Monocle creates a service, stores and domains in your account, which other roles, and read-only or purge-only tokens, cannot do.
Paste the token into Monocle and select Validate token. Monocle checks the scope and role before saving the token encrypted.
Choose your domain and origin
Monocle protects one domain per app. Pick it from the domains on your Fastly account, or type it if the list is empty. A classic domain has to be migrated to a versionless one in Fastly first: Monocle attaches domains through Fastly's Domain Management, and setup says so when it finds a classic one.
Monocle then looks up the service currently serving the domain and detects its origin automatically. Depending on what it finds, you choose how verified traffic is forwarded:
- Forward to your origin copies the origin backend onto the Monocle service, host override, TLS settings and shielding included. Best when your existing service has no custom rules.
- Keep my existing Fastly setup chains the Monocle service through your existing service, so its VCL, WAF and caching stay in the request path. Monocle adds an internal host to your service and a guard that rejects traffic not signed by Monocle. A VCL service is configured automatically with your authorisation. A Compute service shows you a snippet to add to its code: Monocle checks that your service refuses traffic it did not sign, and only then moves the domain.
A domain that is on your Fastly account but not attached to any service asks you for the origin instead.
When you deploy, the domain moves to the Monocle Compute service. The domain is fixed at setup, as on the other integrations: to protect another domain, create a separate app; to change this one, remove the service from the app's Fastly page, which returns the domain to the service it came from, then set up again.
Choose where Monocle runs
The whole domain moves to the Monocle service, so the Assessment step chooses what happens on it:
- Assessed paths choose which pages Monocle assesses. Site-wide is recommended: assessment runs in the background on each page load and does not block visitors. Monocle adds its script to the pages it assesses, so no tag has to be added by hand.
- Excluded paths name paths Monocle must never act on, such as a public API. The Compute service still receives these requests, since the whole domain is on it, but passes them straight to your origin untouched: nothing is assessed, enforced or changed. An excluded path is
/pathexactly,/path/*for a section, or/path*for everything starting with it. - Enforced paths (on the app's Configure Policy page) choose where a Policy block decision is applied. An enforced path cannot sit inside an excluded one; Monocle refuses the combination wherever it is saved.
Assessed and excluded paths can be changed later from the app's Fastly page, and apply to the running service without a redeploy.
Configure the block response
The block response controls what users see when traffic is blocked.
You can configure:
- Response body
- Page title
- HTTP status code (401, 403 or 404)
- Redirect URL, which must point to a path on the protected domain
The default response status is 403. A redirect can also be applied to blocked background requests, which the Monocle script navigates to the block page.
Deploy the service
Once the token, domain, assessment and block response are configured, select Deploy Service.
Monocle creates the Compute service and stores, writes the configuration, attaches the domain, uploads the Monocle package and activates the service. A new version reaches every Fastly POP within about a minute.
After deployment, Monocle begins testing for traffic on the domain. When traffic is detected, the integration status updates to show that Monocle is assessing traffic.
Check the deployment
The app's Fastly page has a Run check button. It fetches the protected domain as a visitor would and reports whether Monocle is running there: the page carries the Monocle script or the verification screen, and the service's own endpoints answer.
A check that finds a problem names what stopped Monocle, for example a Content-Security-Policy the script cannot be added to, a page served as something other than HTML, or a domain that no longer points at the Monocle service.
WebSockets
Monocle hands a WebSocket connection to Fastly to proxy, which needs WebSocket passthrough enabled on the service in your Fastly account. It is a paid Fastly product and Monocle does not enable it for you. Without it, WebSocket connections to the protected domain fail.
On an enforced path, a WebSocket needs a verdict like any other request: a visitor without one is refused, and a cleared visitor connects. An open connection stays open if the visitor's verdict later changes.
Blocking requires Policy API
The Fastly integration can assess traffic without code changes.
However, assessment is not the same as blocking.
By default, Monocle will allow all traffic unless your policy configuration returns a block decision.
To actively block traffic, you must:
- Have access to policy enforcement.
- Enable the Policy API.
- Select a blocking strategy.
- Configure the policy rules you want to apply, including the enforced paths.
If your policy is set to Allow All, the service continues allowing traffic even though it is deployed.
Plugin version updates
Monocle may release new versions of the Compute plugin.
When a new version is available, the Fastly page shows that an update is available. To update, select Update Service. The service is redeployed with the latest package and your current configuration; traffic keeps flowing during the deploy.
A service deployed with a previous version of the plugin shows a notice on the Fastly page until it is redeployed. Its path rules are replaced by the assessed paths chosen on that page.
Updating an API token
If your Fastly API token is rotated, revoked, or expires, Monocle loses permission to manage the service.
The deployed service keeps running, but Monocle cannot update its configuration, redeploy it, or remove it until a valid token is provided.
If you see an invalid token warning:
- Create a new Fastly API token with the same scope.
- Update the token in Monocle from the Fastly page.
- Validate the token again.
Removing the service
You can remove the Monocle Compute service from the Fastly page.
Removing the service first moves the domain back to the service that served it before Monocle, then undoes any chaining changes made to your existing service and deletes the Monocle service and its stores from your Fastly account. Traffic is no longer assessed.
If the domain cannot be moved back, nothing is removed and your site keeps running through Monocle. Retry the removal, or move the domain in the Fastly dashboard first.
Related
- Monocle Assessment — Understand the decrypted assessment payload
- Cloudflare Integration — The same workflow on Cloudflare Workers
- CloudFront Integration — The same workflow on Amazon CloudFront