Skip to main content

Integrate RelyAuth with Hasura

Basics​

Hasura engines can integrate with RelyAuth using the webhook mode. In this guide, you will learn how to integrate RelyAuth to an existing DDN project locally using Docker Compose.

Hasura DDN​

Step 1. Configure RelyAuth service​

Create a RelyAuth configuration file to auth/auth.yaml. This guide uses the API key authentication mode with the admin role in session variables. This simulates the admin secret authentication of Hasura GraphQL Engine v2.

auth/auth.yaml
version: v1
kind: RelyAuth
definition:
  modes:
    - mode: apiKey
      tokenLocation:
        in: header
        name: x-hasura-admin-secret
      value:
        env: HASURA_GRAPHQL_ADMIN_SECRET
      sessionVariables:
        x-hasura-role:
          value: admin

Add the value of HASURA_GRAPHQL_ADMIN_SECRET environment variable to the .env file.

.env
# ...
HASURA_GRAPHQL_ADMIN_SECRET=adminsecret

Add the RelyAuth service to the compose.yaml file to the root project folder.

compose.yaml
services:
  # ...
  auth-hook:
    image: ghcr.io/relychan/rely-auth:latest
    volumes:
      - ./auth:/etc/rely-auth
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: http://local.hasura.dev:4317
      HASURA_GRAPHQL_ADMIN_SECRET: ${HASURA_GRAPHQL_ADMIN_SECRET}

Step 2. Configure DDN metadata​

Update the AuthConfig in the auth-config.hml file of the globals subgraph. See the official Hasura DDN docs for more details.

globals/metadata/auth-config.hml
kind: RelyAuth
version: v4
definition:
  mode:
    webhook:
      url:
        valueFromEnv: AUTH_WEBHOOK_URL
      method: POST
      customHeadersConfig:
        body:
          headers:
            forward:
              - authorization
Example .env file
AUTH_WEBHOOK_URL=http://auth-hook:8080/auth/ddn
GET vs POST

Common origin headers such as Origin, Host, User-Agent etc... are discarded by the GET method. Use the POST method if you want to validate client IPs or origins.

Step 3. Build your supergraph​

ddn supergraph build local
ddn run docker-start
ddn console --local

Hasura GraphQL Engine v2​

Step 1. Configure RelyAuth service​

Create a RelyAuth configuration file to auth/auth.yaml. This guide uses the API key authentication mode with a custom header and a custom role for internal services, say agent in session variables. We can add a noAuth mode to simulate the HASURA_GRAPHQL_UNAUTHORIZED_ROLE configuration in Hasura GraphQL Engine v2 for the public access.

auth/auth.yaml
version: v1
kind: RelyAuth
definition:
  modes:
    - mode: apiKey
      tokenLocation:
        in: header
        name: x-your-api-key
      value:
        env: YOUR_API_KEY
      sessionVariables:
        x-hasura-role:
          value: agent
    - mode: noAuth
      sessionVariables:
        x-hasura-role:
          value: anonymous

Add the value of YOUR_API_KEY environment variable to the .env file.

.env
# ...
YOUR_API_KEY=your-api-key

Add the RelyAuth service to the compose.yaml file to the root project folder.

docker-compose.yaml
services:
  # ...
  auth-hook:
    image: ghcr.io/relychan/rely-auth:latest
    volumes:
      - ./auth:/etc/rely-auth
    environment:
      YOUR_API_KEY: ${YOUR_API_KEY}

Step 2. Configure Hasura GraphQL Engine​

Update the HASURA_GRAPHQL_AUTH_HOOK and the optional HASURA_GRAPHQL_AUTH_HOOK_MODE environment variables to the Docker manifest of GraphQL Engine.

docker-compose.yaml
services:
  # ...
  graphql-engine:
    image: hasura/graphql-engine:v2.48.7
    environment:
      HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
      HASURA_GRAPHQL_AUTH_HOOK: http://auth-hook:8080/auth/hasura
      HASURA_GRAPHQL_AUTH_HOOK_MODE: POST
      # other environment variables...
GET vs POST

Similar to Hasura DDN. Common origin headers such as Origin, Host, User-Agent etc... are discarded by the GET method. Use the POST method if you want to validate client IPs or origins.

Why different endpoint?

Hasura GraphQL Engine v2 and Hasura DDN are slightly different in the session variables response format. Values of session variables in Hasura GraphQL Engine v2 must have the string format. Meanwhile, Hasura DDN allows any type. The /auth/hasura handler automatically serializes session variable values to string.

The following manifest is the full example of the docker compose manifest:

docker-compose.yaml
services:
  postgres:
    image: postgres:18
    restart: always
    ports:
      - 5432:5432
    environment:
      POSTGRES_PASSWORD: "password"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  hasura:
    image: hasura/graphql-engine:v2.48.7
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy
      auth-hook:
        condition: service_started
    environment:
      HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:password@postgres:5432/postgres
      DATA_DATABASE_URL: postgres://postgres:password@postgres:5432/postgres
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
      HASURA_GRAPHQL_AUTH_HOOK: http://auth-hook:8080/auth/hasura
      HASURA_GRAPHQL_AUTH_HOOK_MODE: POST
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/healthz || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 10

  auth-hook:
    image: ghcr.io/relychan/rely-auth:latest
    volumes:
      - ./auth:/etc/rely-auth
    environment:
      YOUR_API_KEY: ${YOUR_API_KEY}

Step 3. Start Docker services​

docker compose up -d

Open the console at http://localhost:8000 and make GraphQL requests to verify.

Use Cases​

Enabling Admin Secret in Hasura DDN​

Up to now, Hasura DDN hasn't supported the admin secret. You need to deploy a custom webhook to emulate that authentication, use JWT authentication or public access with the noAuth mode. You can easily configure that with RelyAuth using the apiKey authentication mode.

Fallback Authentication Modes​

Hasura DDN does not support the HASURA_GRAPHQL_UNAUTHORIZED_ROLE configuration for the JWT authentication mode. We can workaround it with the multiple auth modes and handle the logic to set the X-Hasura-Auth-Mode from the client side:

  • If the access token exists, the client includes the X-Hasura-Auth-Mode: jwt header or omits it if default mode into HTTP requests.
  • If the access token doesn't exist, the client includes the X-Hasura-Auth-Mode: <no-auth-mode-id> header into HTTP requests.

With RelyAuth, authenticate modes are automatically fallback. You just configure it easily on the backend side.

Multiple Admin Secrets and JWT Secrets​

Multiple Admin Secrets and Multiple JWT Secrets modes are available in the Enterprise and Cloud Editions of Hasura GraphQL Engine v2 only.

Even though Hasura DDN supports multiple auth modes, you can configure multiple JWT authentication modes only. Multiple admin secrets aren't supported.

RelyAuth supports multiple authentication modes seamlessly. You can configure both API key and JWT authentication modes with fallback to public access via the noAuth mode.