Quickstart
Introduction
For this quickstart, we'll use the allowlist plugin. This adds an allowlist layer on top of your supergraph to restrict access to only specific queries or mutations.
In this example, we're using Cloudflare Wrangler to deploy our plugin as a Cloudflare Worker. However, you can use any other tool or service that hosts HTTPS services you wish. You can get started with Wrangler here.
Step 1. Create a new Wrangler project
Create a Wrangler project with the allowlist
plugin template.
wrangler generate allowlist-plugin https://github.com/hasura/engine-plugin-allowlist
This will create a new local Wrangler project using the allowlist plugin as a template in your current directory.
Step 2. Install the dependencies
Navigate to the new directory and install the dependencies.
cd allowlist-plugin
npm install
Also, start the local development server.
npm start
Step 3. Add the plugin configuration
We'll let the engine know about the plugin and to execute it as a pre-parse plugin by creating a new metadata file. In
your global
subgraph's metadata directory, create a new file named allow-list.hml
and add the following
configuration.
kind: LifecyclePluginHook
version: v1
definition:
name: cloudflare allowlist
url:
valueFromEnv: ALLOW_LIST_URL
pre: parse
config:
request:
headers:
additional:
hasura-m-auth:
valueFromEnv: M_AUTH_KEY
session: {}
rawRequest:
query: {}
variables: {}
We've used valueFromEnv
so that we can dynamically and securely add values from our environment variables. You can add
these values to your root-level .env
and then map them in the globals
subgraph.yaml file. Alternatively, you can
include raw strings here using value
instead of valueFromEnv
and passing the keys.
Next, update the subgraph.yaml
file to include the metadata file and the environment variables.
kind: Subgraph
version: v2
definition:
name: globals
...
includePaths:
...
- allowlist-plugin.hml
envMapping:
ALLOW_LIST_URL:
fromEnv: ALLOW_LIST_URL
M_AUTH_KEY:
fromEnv: M_AUTH_KEY
Finally, we need to add the environment variables to the .env
file.
ALLOW_LIST_URL="http://local.hasura.dev:8787"
M_AUTH_KEY="your-strong-m-auth-key"
The hasura-m-auth
header is a custom header that is used to authenticate the requests to the allowlist plugin. You can
use any strong key here to authenticate the plugin. DDN will automatically add this header to the requests to the
plugin. Also, make sure to update the src/config.ts
file (in step 5) with the same key.
Step 4. Create a new build for local development
Create a new supergraph build.
ddn supergraph build local
Start the console for the local supergraph.
ddn console --local
You can now test the plugin by running queries or mutations that are not in the allowlist. The plugin will restrict access to only the queries or mutations you've defined.
Step 5. Update the plugin config
Update the src/config.ts
file with the queries and mutations that you want to allow, using a strong m-auth key.
export const Config = {
headers: {
"hasura-m-auth": "your-strong-m-auth-key",
},
allowlist: [
...,
"query MyQuery {\n getAuthorById(author_id: 10) {\n first_name\n id\n last_name\n }\n}",
],
};
The local wrangler development server will automatically reload the plugin when you make changes to the code.
Step 6. Configure the plugin variables
To enable tracing for the plugin, you need to update the wrangler.toml
file with the required configurations. If you
don't want to enable tracing for the plugin, you can skip this step.
In allowlist-plugin
directory, update the wrangler.toml
file with the required configurations.
...
[vars]
OTEL_EXPORTER_OTLP_ENDPOINT = "https://gateway.otlp.hasura.io:443/v1/traces"
OTEL_EXPORTER_PAT = "<PAT>"
Replace <PAT>
with the Personal Access Token (PAT) for the Hasura Cloud account. You can generate this using the
ddn auth print-pat
command.
Step 7. Deploy the plugin
For your plugin to be reachable by your hosted supergraph, we'll need to deploy using Cloudflare Wrangler. The deploy
command included in your plugin's package.json
will do this automatically for you and return the hosted service's URL.
Note: Please also update the wrangler.toml
with your cloud PAT for the tracing to work.
npm run deploy
This will deploy the plugin to Cloudflare Workers and return the URL of the hosted service. Next, update the .env.cloud file with the URL.
ALLOW_LIST_URL="https://<your-deployed-plugin>.workers.dev"
M_AUTH_KEY="your-strong-m-auth-key"
Step 8. Create a new build
Create a new supergraph build.
ddn supergraph build create
The engine will execute the plugin before each request using the queries or mutations you defined.