introspection.mdx

import { PackageCmd, Callout } from '@theguild/components'

Introspection

A powerful feature of GraphQL is schema introspection. This feature is used by GraphiQL for exploring the schema and also by tooling such as GraphQL Code Generator for generating type-safe client/frontend code.

GraphQL schema introspection is also a feature that allows clients to ask a GraphQL server what GraphQL features it supports (e.g. defer/stream or subscriptions).

Disabling Introspection

If your goal is to avoid unknown actors from reverse-engineering your GraphQL schema and executing arbitrary operations, it is highly recommended to use persisted operations.

Learn more about persisted operations.

import { createYoga } from 'graphql-yoga'
import { useDisableIntrospection } from '@graphql-yoga/plugin-disable-introspection'

// Provide your schema
const yoga = createYoga({
  graphiql: false,
  plugins: [useDisableIntrospection()]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Disable Introspection based on the GraphQL Request

Somnetimes you want to allow introspectition for certain users. You can access the Request object and determine based on that whether introspection should be enabled or not. E.g. you can check the headers.

import { createYoga } from 'graphql-yoga'
import { useDisableIntrospection } from '@graphql-yoga/plugin-disable-introspection'

// Provide your schema
const yoga = createYoga({
  graphiql: false,
  plugins: [
    useDisableIntrospection({
      isDisabled: (request) =>
        request.headers.get('x-allow-introspection') !== 'secret-access-key'
    })
  ]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Disabling Field Suggestions

When executing invalid GraphQL operation the GraphQL engine will try to construct smart suggestions that hint typos in the executed GraphQL document. This can be considered a security issue, as it can leak information about the GraphQL schema, even if introspection is disabled.

If your goal is to avoid unknown actors from reverse-engineering your GraphQL schema and executing arbitrary operations, it is highly recommended to use persisted operations.

Learn more about persisted operations.

Disabling the "did you mean x" suggestion feature can be achieved via the blockFieldSuggestionsPlugin from graphql-armor.

<PackageCmd packages={['@escape.tech/graphql-armor-block-field-suggestions']} />

import { createYoga } from 'graphql-yoga'
import { blockFieldSuggestionsPlugin } from '@escape.tech/graphql-armor-block-field-suggestions'

// Provide your schema
const yoga = createYoga({
  graphiql: false,
  plugins: [useDisableIntrospection(), blockFieldSuggestionsPlugin()]
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})