Validate GraphQL request

APPLIES TO: All API Management tiers

The validate-graphql-request policy validates the GraphQL request and authorizes access to specific query paths in a GraphQL API. An invalid query is a "request error". Authorization is only done for valid requests.

Policy statement

<validate-graphql-request error-variable-name="variable name" max-size="size in bytes" max-depth="query depth">
    <authorize>
        <rule path="query path, for example: '/listUsers' or '/__*'" action="string or policy expression that evaluates to 'allow | remove | reject | ignore'" />
    </authorize>
</validate-graphql-request>

Attributes

Attribute	Description	Required	Default
error-variable-name	Name of the variable in context.Variables to log validation errors to. Policy expressions are allowed.	No	N/A
max-size	Maximum size of the request payload in bytes. Maximum allowed value: 102,400 bytes (100 KB). (Contact support if you need to increase this limit.) Policy expressions are allowed.	Yes	N/A
max-depth	An integer. Maximum query depth. Policy expressions are allowed.	No	6

Elements

Name	Description	Required
authorize	Add this element to set an appropriate authorization rule for one or more paths.	No
rule	Add one or more of these elements to authorize specific query paths. Each rule can optionally specify a different action. May be specified conditionally using a policy expression.	No

rule attributes

Attribute	Description	Required	Default
path	Path to execute authorization validation on. It must follow the pattern: /type/field.	Yes	N/A
action	Action to perform if the rule applies. May be specified conditionally using a policy expression.	No	allow

Introspection system

The policy for path=/__* is the introspection system. You can use it to reject introspection requests (__schema, __type, etc.).

Request actions

Available actions are described in the following table.

Action	Description
reject	A request error happens, and the request is not sent to the backend. Additional rules if configured are not applied.
remove	A field error happens, and the field is removed from the request.
allow	The field is passed to the backend.
ignore	The rule is not valid for this case and the next rule is applied.

Usage

• Policy sections: inbound
• Policy scopes: global, workspace, product, API
• Gateways: classic, consumption, self-hosted

Usage notes

• Configure the policy for a pass-through or synthetic GraphQL API that has been imported to API Management.

• This policy can only be used once in a policy section.

• Because GraphQL queries use a flattened schema, permissions may be applied at any leaf node of an output type:

  • Mutation, query, or subscription
  • Individual field in a type declaration

  Permissions may not be applied to:

  • Input types
  • Fragments
  • Unions
  • Interfaces
  • The schema element

Error handling

Failure to validate against the GraphQL schema, or a failure for the request's size or depth, is a request error and results in the request being failed with an errors block (but no data block).

Similar to the Context.LastError property, all GraphQL validation errors are automatically propagated in the GraphQLErrors variable. If the errors need to be propagated separately, you can specify an error variable name. Errors are pushed onto the error variable and the GraphQLErrors variable.

Examples

Query validation

This example applies the following validation and authorization rules to a GraphQL query:

• Requests larger than 100 kb or with query depth greater than 4 are rejected.
• Requests to the introspection system are rejected.
• The /Missions/name field is removed from requests containing more than two headers.

<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/__*" action="reject" /> 
        <rule path="/Missions/name" action="@(context.Request.Headers.Count > 2 ? "remove" : "allow")" />
    </authorize>
</validate-graphql-request> 

Mutation validation

This example applies the following validation and authorization rules to a GraphQL mutation:

• Requests larger than 100 kb or with query depth greater than 4 are rejected.
• Requests to mutate the deleteUser field are denied except when the request is from IP address 198.51.100.1.

<validate-graphql-request error-variable-name="name" max-size="102400" max-depth="4"> 
    <authorize>
        <rule path="/Mutation/deleteUser" action="@(context.Request.IpAddress <> "198.51.100.1" ? "deny" : "allow")" />
    </authorize>
</validate-graphql-request> 

Related policies

• Content validation

Next steps

For more information about working with policies, see:

• Tutorial: Transform and protect your API
• Policy reference for a full list of policy statements and their settings
• Policy expressions
• Set or edit policies
• Policy samples