Field-Level Authorization

## Why the shape of GraphQL changes the question Authorization in a request/response API is usually reasoned about per endpoint. A REST route such as `GET /shipments/{id}` has exactly one handler; put the check at the top of that handler and there is no other way to obtain a shipment. The route *is* the access point, and enumerating routes enumerates the attack surface. GraphQL removes that one-to-one mapping. There is a single endpoint, and what a caller can obtain is decided by the **type graph**, not by a route table. A document names a root field and then descends through fields, and every field that returns an object type is an edge into that type. If your schema declares `Shipment` in five places, there are five ways to arrive at a shipment, and a check written in one of them is a check the other four never run. ## A concrete freight-tracking example ```graphql type Query { shipment(id: ID!): Shipment carriers: [Carrier!]! } type Carrier { id: ID! legalName: String! shipments: [Shipment!]! } type Shipment { id: ID! status: ShipmentStatus! rateAgreement: RateAgreement } type RateAgreement { negotiatedRateCents: Int! fuelSurchargePct: Float! } ``` Suppose the team writes the check in the resolver for `Query.shipment` — it loads the shipment, compares its account against the viewer's account and refuses if they differ. That resolver is now safe. But this document never calls it: ```graphql query { carriers { shipments { id rateAgreement { negotiatedRateCents } } } } ``` `Carrier.shipments` produced the same objects by a different edge, and `Shipment.rateAgreement` handed over a competitor's negotiated rate. Nothing about the request was malformed; the schema promised those edges and execution delivered them. ## The unit that must be authorized Every resolver invocation carries four things: the **parent object** it is resolving on, the **field** being resolved, the **arguments**, and a per-request **context** that carries the viewer. Authorization is a decision over exactly that tuple. Two useful consequences follow. First, the decision can be *static* — does this viewer hold the role or scope that this field requires? — or *instance-level* — is this viewer a party to *this* shipment? Static rules can be attached to the field once. Instance-level rules need the parent object in hand, which means they can only be answered while the field is being resolved. Second, a check on arguments is not a check on results. `Query.shipments(carrierId: ID!)` verifying that the viewer belongs to `carrierId` looks correct, and stays correct only until someone adds a filter argument, a sort, or a nested edge that crosses carriers. Authorize what you are about to return, not what you were asked for. ## What the specification does and does not give you The GraphQL specification defines the type system, document validation and the execution algorithm. It defines no authorization phase, no viewer concept, no reserved directive for access control, and no rule that unauthorized fields disappear. Everything in this area is convention implemented by servers and teams. The one property execution does give you is that a failure while resolving one field is a *field error* — the rest of the response still executes and the response can carry both partial data and an error entry describing that field. (What happens to parents when the denied field is non-nullable is a separate topic in its own right.) ## Where the check can live Three placements are common, and real systems mix them: - **In each resolver.** Explicit and easy to read, and the one that scales worst: coverage depends on every author of every new field remembering. - **Declaratively on schema fields**, via a team-defined directive the server enforces. Makes the rule visible in the schema and lintable, but a static marker cannot answer instance-level questions on its own. - **In the data-loading layer**, so every traversal that fetches the object passes the same gate — coverage by construction rather than by discipline. ## Failure modes an interviewer listens for - Guarding only root fields, or only mutations, because "reads are harmless". - Treating a field's absence from a generated client as protection. Any caller can name any field the schema declares. - Treating a disabled introspection endpoint as authorization; it hides the map, not the data. - Accepting a tenant identifier from the client and authorizing against it rather than against the viewer's own identity. - Filtering in the UI. The response already left the server. ## What a good answer sounds like "Because the graph has more than one path to the same object. The check has to sit where the object is produced — on the edge, with the parent and the viewer in hand — and I would rather enforce it in the loading layer than trust every future resolver author to remember."