HMAC Signature

Step 1: Gather your secret key

Before you start, you need to have a secret key that will be used for HMAC signing and verification.

The secret key should be a random, opaque string, that will be shared between the Hive Gateway and the subgraphs validating the HMAC signature.

Step 2: HMAC Signing in Hive Gateway

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  hmacUpstreamSignature: {
    secret: myHMACSecret // see step 1 for the secret key
  }
  // ...
})

Now, every GraphQL request sent to the upstream GraphQL subgraphs will be signed with the HMAC and the extensions of the upstream request will contain the HMAC signature.

To configure the subgraph verification of the HMAC signature, please follow the next step.

Step 3: HMAC Verification in Subgraph services

The next step is to perform a verification over the sent HMAC signature in the subgraph services:

With GraphQL Yoga

If you are using Yoga, you can use the gateway package:

npm i @graphql-hive/gateway

pnpm add @graphql-hive/gateway

yarn add @graphql-hive/gateway

bun add @graphql-hive/gateway

import { createYoga } from 'graphql-yoga'
import { useHmacSignatureValidation } from '@graphql-hive/gateway'
 
const myYogaSubgraphServer = createYoga({
  // ...
  plugins: [
    useHmacSignatureValidation({
      secret: myHMACSecret // see step 1 for the secret key
    })
    // other Yoga plugins
    // ...
  ]
})

With Apollo Server

If you are using Apollo-Server for your subgraph services, you can implement a custom plugin to verify the HMAC signature. You can still use the utilities from the @graphql-hive/gateway library to serialize the request parameters and verify the HMAC signature in a stable way.

Start by installing the @graphql-hive/gateway package:

npm i @graphql-hive/gateway

pnpm add @graphql-hive/gateway

yarn add @graphql-hive/gateway

bun add @graphql-hive/gateway

Now, configure your Apollo Server with the HMAC verification plugin:

import { createHmac } from 'crypto'
import { ApolloServer, ApolloServerPlugin } from '@apollo/server'
import { defaultParamsSerializer } from '@graphql-hive/gateway'
 
const verifyHmacPlugin = {
  async requestDidStart({ request, contextValue }) {
    const signature = request.extensions?.['hmac-signature']
 
    if (!signature) {
      throw new Error('HMAC signature is missing')
    }
 
    const serializedParams = defaultParamsSerializer({
      query: request.query,
      variables: request.variables
    })
 
    const incomingReqSignature = createHmac('sha256', HMAC_SIGNING_SECRET)
      .update(serializedParams)
      .digest('base64')
 
    if (incomingReqSignature !== signature) {
      throw new Error('HMAC signature is invalid')
    }
  }
} satisfies ApolloServerPlugin<{}>
 
const server = new ApolloServer({
  plugins: [
    verifyHmacPlugin
    // ... other Apollo plugins
  ]
})

Other GraphQL servers

To implement HMAC verification in other GraphQL servers, you should implement a HMAC verification using the following specification:

• The incoming request to your server will contain an extensions field with a hmac-signature key.

• The hmac-signature value is a base64 encoded HMAC signature of the request parameters, using the SHA-256 algorithm.

• The request parameters should be serialized in a stable way, so the signature can be verified correctly. I should consist of the GraphQL query and variables:

  {
    "query": "query { comments { id author { id name } } ",
    "variables": {}
  }

• The HMAC signature should be calculated using the secret key shared between the Hive Gateway and the subgraph services.

Here’s an example of an incoming subgraph request with the HMAC signature:

{
  "query": "query { comments { id author { id name } } ",
  "variables": {},
  "extensions": {
    "hmac-signature": "AbC123"
  }
}

The signature is produced by the Hive Gateway using the shared secret key, and the serialized request (query and variables).