Enabling Webhook Authentication

Introduction

You can enable your Hasura DDN instance to use an auth webhook in just a few steps.

Step 1. Shaping the webhook request and response

Request

Your webhook should accept either a GET or POST request. Below is an example of the request headers your webhook might process:

Example headers present in a POST request to your webhook endpoint

{
  "headers": {
    "Authorization": "Bearer some-token",
    "Content-Type": "application/json"
  }
}

When a request is sent to Hasura, these headers will be forwarded to your webhook.

Parsing

Your webhook is then responsible for parsing, validating, and using the token passed in the header. It will need to:

• Extract the Token: Retrieve the Authorization header from the incoming request and extract the token.

• Validate the Token: Use a library or your own logic to validate the token. This involves verifying the token's signature and decoding its payload to extract user information.

Response

Based on the validation result, the webhook will need to respond with either a 200 status code (for a valid token) or a 401 status code (for an invalid or missing token).

To allow the GraphQL request to go through, your webhook must return a 200 status code. You should respond with session variables beginning with X-Hasura-* in the body of your response. The value of each session variable can be any JSON value. These will be available to your permissions in Hasura.

You will, at least, need to set the X-Hasura-Role session variable to let the Hasura DDN know which role to use for this request. Unlike JWT auth mode, you do not have to pass X-Hasura-Allowed-Roles or X-Hasura-Default-Role session variables. This is because the webhook is called for each request, allowing the auth service to easily switch the user role if needed.

In the example below the X-Hasura-Is-Owner and X-Hasura-Custom are examples of custom session variables which can be used to enforce permissions in your supergraph.

Example response from your webhook to Hasura DDN

HTTP/1.1 200 OK
Content-Type: application/json

{
    "X-Hasura-User-Id": 25,
    "X-Hasura-Role": "user",
    "X-Hasura-Is-Owner": "true",
    "X-Hasura-Custom": "custom value"
}

Step 2. Update your AuthConfig

Hasura utilizes an AuthConfig object that allows you to define the configuration for your authentication service. The auth-config.hml file can be found in your globals directory.

You can use Hasura's VS Code extension to scaffold out your AuthConfig object by typing AuthConfig and selecting this object from the list of available options. As you navigate through the skeleton, you can type CTRL+SPACEBAR at any point to reveal options for the different key-value pairs.

In the example below, we're demonstrating a sample authentication webhook.

globals/metadata/auth-config.hml

kind: AuthConfig
version: v2
definition:
  mode:
    webhook:
      url: http://auth_hook:3050/validate-request
      method: Post

Other configuration options are available

What we've provided above is a sample configuration. However, there are many options available, which you can learn about here.

Step 3. Rebuild your supergraph

Once you've updated your auth-config.hml, you can rebuild your supergraph and test it locally.

For example, from the root of your project, run:

ddn supergraph build local \
  --supergraph supergraph.yaml \
  --env-file .env

Step 4. Make an authenticated request

In the example above, we're using the BearerAuthorization method. As such, as we can make a request to our Hasura DDN instance by including a header with the key-value of Authorization: Bearer <our-encoded-token>. For testing, you can pass this value in the Hasura DDN console's header section.

Authentication is only part of the puzzle!

Hasura DDN empowers you to easily write your access-control rules, commonly known as authorization, using declarative metadata. You can use the values passed in your response to then limit which models and types a user has access to with each request.