Join our Newsletter — 33% off our NHI Course
Home› Guides› GraphQL Federation Security Guide: Gateways, Subgraph Trust and…
Guide Web & API Security

GraphQL Federation Security Guide: Gateways, Subgraph Trust and Authorisation

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 14 November 2026 15 min read
On this page

A federated GraphQL supergraph looks like one API to clients, but every request is split by a router into calls to independent subgraphs, and each subgraph has to decide whether to trust what the router tells it. When that trust is assumed rather than enforced, attackers go around the router to a subgraph, reach data through entity lookups that skip top-level authorisation, or exploit rules that compose differently from what each team intended. This guide covers the security of federated supergraphs specifically: router trust, subgraph exposure, propagation of the caller's identity, and abuse of the composed schema. It is for API platform owners, application security engineers and subgraph teams, and it assumes the single-service controls in the GraphQL Security Guide are already understood; attacks are described conceptually only.

Key takeaways

  • The router is a policy point, not the only one. Router-level authentication and authorisation directives stop unauthorised requests early, but each subgraph must still authorise the data it owns.
  • Subgraphs must only accept the router. A reachable subgraph exposes the federation fields _service and _entities and bypasses every limit the router enforces.
  • Entity resolution is a second front door. The router fetches entities by key through _entities, which never passes through your top-level query fields, so authorise inside the reference resolver.
  • Identity must travel with integrity. Forward a verified token or signed claims, never a plain header that a subgraph trusts without checking where it came from.
  • Composition changes policy. Authorisation directives accumulate across subgraphs and root-level directives spread to every field, so review the composed supergraph, not only each team's schema.

How federation changes the trust model

In federation, each team publishes a subgraph schema; a composition step merges them into a supergraph schema; and a router (also called a gateway) plans each client operation into calls to the subgraphs and stitches the results. Apollo Federation defines the widely used subgraph specification, and the GraphQL Foundation hosts the Composite Schemas Specification, a working draft for merging "source schemas" into one "composite schema" with directives such as @key, @lookup, @internal and @inaccessible. Drafts change, so check the current text before relying on a detail.

Federation creates trust boundaries that a single GraphQL server does not have:

BoundaryWhat crosses itWhat goes wrong when it is assumedControl
Client to routerOperation, credentialsUnauthenticated or oversized operations reach subgraphsToken validation, request limits, cost limits, trusted documents
Router to subgraphSub-operations, entity representations, caller identityAnyone who can reach the subgraph can impersonate the router and any userNetwork isolation, mTLS or request signing, subgraph-side token checks
Subgraph to subgraph (via router)Entity keys and @requires fields supplied by one subgraph to anotherA subgraph trusts key or field values that a client influencedValidate representations; authorise on the resolved entity
Team to supergraph (composition)Schema, directives, ownership of shared typesA new subgraph exposes a field or relaxes access without reviewSchema checks in CI, composed-schema review, ownership rules

The general move from REST to graph-shaped APIs is covered in REST vs GraphQL Security; the federation boundaries above sit on top of it.

Subgraph exposure and router trust

Every federated subgraph implements fields intended for the router alone. The Apollo subgraph specification defines Query._service { sdl }, which returns the subgraph's full schema and, per the specification, stays available even when introspection is disabled; it states that the field is "intended solely for use by the graph router". Subgraphs that contribute entity fields also expose Query._entities(representations: [_Any!]!), which fetches entities by __typename and key, and can batch different entity types in one request.

If a subgraph is reachable by anything other than the router, three things follow: its schema leaks through _service even with introspection off; arbitrary entity lookups through _entities skip the query fields where authorisation often lives; and none of the router's depth, alias, cost or rate limits apply.

  • Network isolation: place subgraphs on a private network or namespace with policy that admits only router workloads. Cosmo's hardening guide also recommends overriding routing URLs when router and subgraphs share a network, to avoid unnecessary hops and reduce attack surface.
  • Authenticate the router as a workload: use mutual TLS with workload certificates, or signed requests. Hive Gateway documents an HMAC signature (SHA-256, base64) over the query and variables, sent in extensions["hmac-signature"] and verified by each subgraph. See the mTLS vs Signed Tokens for Service Authentication guide for the trade-offs.
  • Treat the router's credential as an NHI: the shared HMAC secret or router certificate is a machine credential with access to every subgraph. Store it in a secrets manager, rotate it, and scope it per environment. See the SPIFFE and SPIRE Guide for certificate-based workload identity.
  • Do not rely on obscurity: an internal hostname or an unlisted port is not access control. Test from outside the router network that subgraphs refuse connections.

Authentication and identity propagation

The router should validate the client's credential once, then pass the caller's identity to subgraphs in a form they can verify. The common patterns, with their trade-offs:

PatternHow it worksStrengthRisk to manage
Forward the original tokenRouter validates the JWT and forwards the Authorization header; each subgraph validates it againSubgraphs verify signature, issuer, audience and expiry themselvesEvery subgraph needs consistent validation code; token audience must cover subgraphs
Claims as headersRouter extracts claims and sends them as headers (for example an x-claims style header)Simple for subgraphs to readA header is only trustworthy if the subgraph can be reached solely by the router; pair with mTLS or signing
Claims in request extensionsRouter places claims in the GraphQL request extensionsTravels with the operation; can be covered by an HMAC signatureSubgraphs must verify the signature before reading claims
Token exchangeRouter exchanges the client token for a downstream token scoped to the subgraphLeast privilege per subgraph; audience-boundMore moving parts and latency; see OAuth Token Exchange and Delegation Guide

Whatever the pattern, strip any client-supplied header with the same name as the trusted identity header at the router, so a client cannot inject claims. Validate algorithm, issuer and audience against an allowlist; the JWT Security Guide covers token validation detail.

Authorisation across router and subgraphs

Federated routers commonly support schema directives for authorisation: @authenticated requires a verified identity, @requiresScopes requires scopes from the token's claims (inner arrays are combined with AND, outer arrays with OR), and @policy defers to custom logic. Unauthorised fields are removed or nulled, or the whole operation is rejected, depending on configuration. These directives let the router stop a request before it costs anything downstream, but they cannot see business rules such as "this user may read only orders for their own tenant".

  • Layer the checks: coarse-grained authentication and scope checks at the router; object-level and tenant checks in each subgraph's business logic, including in every reference resolver used for _entities. The BOLA vs BFLA guide explains the two failure types this prevents.
  • Directive placement: Apollo's documentation warns that a directive placed on Query, Mutation or Subscription as a whole applies to every field from every subgraph; place directives on individual root fields.
  • Accumulation: when a shared field carries different directives in different subgraphs, Apollo composes the requirements with AND. Review the composed result: a stricter rule in one subgraph silently tightens access everywhere the field appears, and a missing rule in a new subgraph may not be noticed until it is the only owner of a field.
  • Keys and nulls: an authorised @key field still helps compose entities but cannot be queried directly; nulling a non-null key can null its parent object. Test responses for both authorised and unauthorised callers.
  • Introspection: authorisation directives do not hide fields from introspection. Control schema visibility separately.
  • Dry run first: use dry-run or report-only modes where available to see which paths would be filtered before enforcing.

Router controls by implementation

Several routers implement federation. Platforms are listed alphabetically; the order is not a ranking. Each paragraph lists the security settings the vendor's own documentation describes, as of November 2026.

Apollo GraphOS Router

The JWT authentication plugin validates tokens against JWKS endpoints and blocks unauthenticated requests before they reach subgraphs unless on_error is set to Continue; a coprocessor can implement other schemes and add headers. Authorisation directives @authenticated, @requiresScopes and @policy are enforced by the router, with reject_unauthorized to fail the whole operation and dry_run for testing. Request limits include max_depth, max_height, max_aliases and max_root_fields, parser token and recursion limits, http_max_request_bytes (default 2 MB) and http_max_response_size for subgraph responses. Demand control, based on the IBM GraphQL Cost Directive specification, uses @cost and @listSize with measure and enforce modes and per-subgraph maximums. Availability: directive support depends on router version and plan as stated in Apollo's documentation; the directives are a router feature rather than an @apollo/gateway feature.

Hive Gateway

The JWT plugin reads tokens from headers, cookies or a custom function, verifies issuer, audience and algorithms against an inline key or JWKS, and rejects missing or invalid tokens with 401 by default. Claims are forwarded to subgraphs in extensions.jwt.payload, with the raw token optional. The Generic Auth plugin provides @authenticated, @requiresScopes and @policy, the last resolving roles through a policy service. Hive's documentation recommends pairing claim forwarding with HMAC request signing so subgraphs can confirm requests came from the gateway, keeping signing keys out of code, and using persisted documents.

WunderGraph Cosmo Router

The router verifies JWTs against one or more JWKS endpoints with optional algorithm allowlists, audiences and issuers. require_authentication blocks anonymous requests, reject_operation_if_unauthorized rejects instead of nulling, and enable_pre_fetch_field_authorization checks protected fields before any subgraph fetch. Authentication headers are not forwarded to subgraphs unless forwarding is configured. The hardening guide covers turning off introspection and development mode, signing router configuration, Redis-backed rate limiting, restrictive CORS, persisted operations with non-persisted operations blocked, blocking mutations or subscriptions where unused, and TLS.

Composed schema abuse and resource limits

The composed supergraph is larger than any team's view of it, and query plans fan out. Controls must apply to the client operation as planned, not per subgraph in isolation.

Abuse patternWhy federation amplifies itControlOWASP API Top 10 2023
Cross-subgraph fan-outOne nested query triggers many entity fetches across subgraphs (the N+1 pattern the entity docs warn about)Router cost estimation with list size hints; per-subgraph cost caps; data loaders in reference resolversAPI4:2023 Unrestricted Resource Consumption
Alias and batch brute forceMany attempts in one HTTP request evade gateway rate limits counted per requestAlias and root-field limits; per-operation rate limits; disable batching for sensitive mutationsAPI4:2023, API2:2023 Broken Authentication
Entity lookup by guessed key_entities or a @lookup field returns an entity for any well-formed keyObject-level authorisation in reference resolvers; subgraph isolationAPI1:2023 Broken Object Level Authorization
Property exposure through shared typesA new subgraph adds fields to a shared entity that inherit weaker access than the owning team expectedField-level directives in the owning subgraph; composed schema review; @inaccessible for internal fieldsAPI3:2023 Broken Object Property Level Authorization
Schema leak_service returns full SDL; field suggestions leak namesSubgraph isolation; introspection and suggestions off at the router; trusted documentsAPI8:2023 Security Misconfiguration
Shadow subgraphsOld or test subgraphs remain routable or composedSubgraph inventory tied to the schema registry; decommissioning checksAPI9:2023 Improper Inventory Management

Trusted documents (persisted operations) are the strongest single control for first-party clients: the router runs only operations registered at build time, which removes most abuse of the composed schema. They do not replace authorisation, because a registered operation can still be called with another user's IDs.

Implementation roadmap

  1. Inventory: list every subgraph, its routing URL, owner, network location and whether it is reachable outside the router network. Record it alongside the schema registry; the API Inventory Template is a starting point.
  2. Isolate subgraphs: apply network policy so only router workloads can connect, then add mTLS or request signing. Test from an untrusted network that _service and _entities are unreachable.
  3. Centralise authentication at the router: validate tokens with issuer, audience and algorithm allowlists, reject anonymous requests where the API is not public, and strip client copies of trusted identity headers.
  4. Propagate identity verifiably: choose token forwarding, signed claims or token exchange, and make each subgraph verify it.
  5. Add router authorisation in report-only mode: apply directives to root fields and sensitive types, review filtered paths, then enforce.
  6. Close entity bypasses: add object-level checks to every reference resolver and test entity fetches as an unauthorised user.
  7. Set limits: start depth, alias, root-field and cost limits in measure or warn-only mode, set thresholds from observed traffic, then enforce. Add trusted documents for first-party clients.
  8. Gate composition: run schema checks in CI that flag new fields on shared entities without directives, root-type directives and removed authorisation. Roll back by publishing the previous supergraph schema.

Decision guidance

  • Small supergraph, one team: network isolation plus forwarded JWTs validated in each subgraph is usually enough; router directives add early rejection.
  • Many teams, many languages: centralise authentication and coarse authorisation at the router, use signed claims so subgraphs need minimal auth code, and keep object-level rules in subgraphs.
  • Public third-party API: trusted documents are rarely possible, so lean on cost limits, per-client rate limits and strict introspection control.
  • Regulated data in one subgraph: use token exchange for that subgraph so it receives an audience-bound token and can apply its own policy.

Detection and measurement

Log at both layers: the router sees the client operation, identity and plan; subgraphs see what they were actually asked for.

  • Router logs: operation name or document ID, client identity, authorisation filtering events (for example UNAUTHORIZED_FIELD_OR_TYPE errors), limit rejections and estimated versus actual cost.
  • Subgraph logs: source of each connection (alert on anything other than router identities), _entities calls with representation counts, and failed signature or token checks.
  • Alerts: any direct client request to a subgraph; spikes in _entities representations per request; a client repeatedly hitting authorisation filtering; new operations appearing when trusted documents should be enforced.

Metrics that show the controls work:

  • Percentage of subgraphs that reject connections from outside the router network (target 100%).
  • Percentage of subgraphs that verify identity cryptographically rather than trusting a plain header.
  • Percentage of reference resolvers with object-level authorisation tests.
  • Share of traffic served from trusted documents, for first-party clients.
  • Count of operations rejected by cost or depth limits per week, reviewed for both attacks and false positives.
  • Schema changes merged that failed authorisation checks in CI (target zero).

Framework mapping

FrameworkReferenceFederation control
OWASP API Security Top 10 2023API1, API3, API4, API8, API9Entity authorisation, field authorisation, cost limits, schema exposure, subgraph inventory
NIST SP 800-53 Rev 5AC-3, AC-4, IA-9, SC-7, SC-8, SI-10, AU-12Access enforcement, flow control between router and subgraphs, service authentication, boundary protection, protected transport, input validation, logging
NIST CSF 2.0PR.AA-05, PR.DS-02, PR.PS-04, DE.CM-09Least-privilege authorisation, data in transit, log generation, runtime monitoring
OWASP Cheat Sheet SeriesGraphQL Cheat SheetBatching limits, introspection, depth and amount limits, authorisation on nodes and edges

Common failure patterns

  • Public subgraph endpoints: subgraphs deployed behind their own public load balancer for convenience, exposing _service and _entities with no router limits.
  • Trusting a user ID header: subgraphs read x-user-id from the request without verifying that the router sent it, so anyone reaching the subgraph can act as any user.
  • Authorising only the root query: checks on Query.order but none in the Order reference resolver, so the same object is reachable through another subgraph's entity relationship.
  • Root-type directives: a directive on Query intended for one subgraph applies to every subgraph's fields, breaking public fields or hiding a mistake elsewhere.
  • Limits set per subgraph only: each subgraph sees modest requests while the client operation as a whole fans out to thousands of calls.
  • Router credential sprawl: one long-lived HMAC secret or certificate shared across environments and never rotated.

Practitioner checklist

  • Confirm from an untrusted network that no subgraph, _service or _entities field is reachable.
  • Authenticate router to subgraph with mTLS or request signing, and manage that credential as a rotated machine identity.
  • Validate client tokens at the router with issuer, audience and algorithm allowlists; strip client copies of trusted identity headers.
  • Make every subgraph verify the propagated identity cryptographically.
  • Apply authorisation directives to individual root fields and sensitive types, never to root types as a whole.
  • Add object-level authorisation to every reference resolver and test it as an unauthorised caller.
  • Enforce depth, alias, root-field and cost limits at the router on the planned operation, after a measure period.
  • Use trusted documents for first-party clients and turn off introspection and field suggestions in production.
  • Gate supergraph composition with CI checks for missing or weakened authorisation.
  • Alert on any non-router connection to a subgraph.

Standards and references

Related NHI Mgmt Group resources: GraphQL Security Guide · REST vs GraphQL Security · API Gateway Security Guide · Microservices Security Guide · API Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 14 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.