Skip to main content

Webhook Mode

Introduction​

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

You will need to provide a URL that RelyChan will call with the original request headers, and it should return a body with the session variables after the request is authenticated.

Enabling Webhook authentication​

Update your configurations​

Edit the auth.yaml file. Add a webhook mode to the definitions array.

An example for webhook mode:
version: v1
kind: RelyAuth
definition:
  modes:
    - mode: webhook
      url:
        env: AUTH_WEBHOOK_URL
      method: POST
      customRequest:
        headers:
          forward:
            - Authorization
          additional:
            user-agent:
              default:
                value: "RelyChan"

Shaping the webhook request and response​

Request​

Below is an example of the header object your webhook might receive in the body of a POST request:

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

Headers are forwarded to the auth webhook from the client on each request received by the API gateway either as headers for a GET request or as a JSON object in the body of a POST request under a headers key.

Custom Request Configuration

You can configure the headers that are sent to the webhook in the optional customRequest field. If the field is not provided, the default behavior is to forward all headers (after filtering out commonly used headers - GET method only) received by the DDN engine on the query to the webhook.

When using customRequest, you can explicitly forward any headers, including those that are ignored by default. This gives you full control over which headers are sent to the webhook.

It is recommended to use the customRequest field to configure only the headers that are required by the webhook and not forward any other headers. This will help in reducing the size of the request and improve the performance of the webhook.

In this example, we're passing an encoded JWT in the Authorization header, however webhook mode is flexible and you can pass any headers you wish.

Forward all headers

If you want to forward all headers received by the engine on the query to the webhook, you can set forward: "*". This will forward all headers received by the engine on the query to the webhook, excluding the ignored headers.

Token Parsing​

In this example, the webhook is then responsible for validating and parsing 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 with the secret key.

  • Extract Claims: Decode the token to extract the claims.

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).

You should respond with session variables in an object in the body of your response. The value of each session variable can be any JSON value.

Example response from your webhook
HTTP/1.1 200 OK
Content-Type: application/json

{
    "X-Rely-Role": "user",
    "X-Rely-User-Id": 25
}

Next steps​

Check webhook configurations for more details.