GraphQL Authorization and Query Security Guide

Treat a query as a requested execution plan

GraphQL authorization and query security must evaluate which fields, objects, relationships, and mutations a caller may use and how much work the operation can consume. A single endpoint and HTTP request count conceal the actual execution shape.

Official GraphQL security guidance recommends depth, breadth, batch, rate, and complexity controls. Authentication supplies identity context; authorization still belongs in business logic and must apply to each field and object reached by resolvers.

Enforce policy at fields, nodes, edges, and mutations

Centralize business authorization, pass the authenticated principal and tenant into every resolver, and constrain data-store queries by authorized scope. Check direct node(id:) access, nested edges, field-level sensitive data, mutation targets, and parent-child relationships.

Reuse the matrix method from API BOLA authorization testing. Possession of a global ID, alias, fragment, or cursor never grants access. Test partial-response behavior so a forbidden child does not leak through errors or sibling fields.

Budget depth, breadth, list size, batches, and resolver cost

Set maximum operation depth, stricter nested-list depth, top-level and alias breadth, operations per batch, page size, execution time, and cost. Weight expensive fields and multiply cost through list cardinality. Reject over-budget operations before resolver work where possible.

Apply per-principal and business-object budgets, not only per-IP request rates. Persisted or trusted documents reduce arbitrary query shapes for first-party clients, but document registration needs review and versioning.

Log operation shape and policy decisions without raw secrets

Record request ID, principal and tenant, operation name, persisted-document hash, normalized query hash, selected root fields, depth, breadth, aliases, batch count, estimated and actual cost, resolver count, objects returned, policy denials, duration, error class, and response size. Avoid raw variables containing tokens or personal data.

Detect first-seen query shapes, repeated forbidden nodes, alias-based enumeration, introspection from unauthorized clients, cost estimate divergence, timeouts, and high object counts. A gateway sees one request; resolver telemetry explains its work.

Test permissions and resource limits as one regression suite

Build boundary and regression tests for every role, tenant, node, edge, field, and mutation. Add cyclic fragments, nested lists, aliases, batches, large pages, slow resolvers, and cancellation. Assert denial, bounded work, safe errors, and no side effects.

Measure one operation from document to data store

Next step: choose one sensitive query. Document its policy matrix and expected cost, instrument every resolver, add allowed and denied tenant tests, then generate an authorized high-cost synthetic query in staging. Tune the budget from measured work, not guesswork; never load-test production without approval.