Trusted Documents
This plugin allows you to define a list of trusted GraphQL documents that can be executed by the gateway (also called Persisted Operations).
For additional information, please refer to Trusted Documents.
Configuration
Examples
This example is using a local file called trusted_documents.json
as a store, using the Key->Value map format. The protocol exposed is based on HTTP POST
, using the documentId
parameter from the request body.
YAML
config:
protocols:
- field_name: "documentId"
type: "document_id"
store:
format: "json_key_value"
path: "trusted_documents.json"
source: "file"
enabled: true
type: "trusted_documents"
JSON
{
"config": {
"protocols": [
{
"field_name": "documentId",
"type": "document_id"
}
],
"store": {
"format": "json_key_value",
"path": "trusted_documents.json",
"source": "file"
}
},
"enabled": true,
"type": "trusted_documents"
}
Reference
store
The store defines the source of trusted documents. The store contents is a list of hashes and GraphQL documents that are allowed to be executed.
file
File-based store configuration. The path specified is relative to the location of the root configuration file. The file contents are loaded into memory on startup. The file is not reloaded automatically. The file format is specified by the format
field, based on the structure of your file.
source
file
To use this variation, please specify the type: file
in your configuration.
path
A path to a local file on the file-system. Relative to the location of the root configuration file.
format
The format and the expected structure of the loaded store file.
apollo_persisted_query_manifest
JSON file formated based on Apollo Persisted Query Manifest.
json_key_value
A simple JSON map of key-value pairs.
Example: {"key1": "query { __typename }"}
protocols
A list of protocols to be exposed by this plugin. Each protocol defines how to obtain the document ID from the incoming request. You can specify multiple kinds of protocols, if needed.
apollo_manifest_extensions
This protocol is based on Apollo’s Persisted Query Extensions. The GraphQL operation key is sent over POST
and contains extensions
field with the GraphQL document hash.
Example: POST /graphql {"extensions": {"persistedQuery": {"version": 1, "sha256Hash": "123"}}
type
apollo_manifest_extensions
To use this variation, please specify the type: apollo_manifest_extensions
in your configuration.
document_id
This protocol is based on a POST
request with a JSON body containing a field with the document ID. By default, the field name is documentId
.
Example: POST /graphql {"documentId": "123", "variables": {"code": "AF"}, "operationName": "test"}
type
document_id
To use this variation, please specify the type: document_id
in your configuration.
field_name
"documentId"
The name of the JSON field containing the document ID in the incoming request.
http_get
This protocol is based on a HTTP GET
request. You can customize where to fetch each one of the parameters from. Each request parameter can be obtained from a different source: query, path, or header. By defualt, all parameters are obtained from the query string.
Unlike other protocols, this protocol does not support sending GraphQL mutations.
Example: GET /graphql?documentId=123&variables=%7B%22code%22%3A%22AF%22%7D&operationName=test
type
http_get
To use this variation, please specify the type: http_get
in your configuration.
document_id_from
{
"name": "documentId",
"source": "search_query"
}
Instructions for fetching the document ID parameter from the incoming HTTP request.
search_query
Instructs the plugin to extract this parameter from the query string of the HTTP request.
source
search_query
To use this variation, please specify the type: search_query
in your configuration.
name
The name of the HTTP query parameter.
path
Instructs the plugin to extract this parameter from the path of the HTTP request.
source
path
To use this variation, please specify the type: path
in your configuration.
position
The numeric value specific the location of the argument (starting from 0).
header
Instructs the plugin to extract this parameter from a header in the HTTP request.
source
header
To use this variation, please specify the type: header
in your configuration.
name
The name of the HTTP header.
variables_from
{
"name": "variables",
"source": "search_query"
}
Instructions for fetching the variables parameter from the incoming HTTP request. GraphQL variables must be passed as a JSON-encoded string.
search_query
Instructs the plugin to extract this parameter from the query string of the HTTP request.
source
search_query
To use this variation, please specify the type: search_query
in your configuration.
name
The name of the HTTP query parameter.
path
Instructs the plugin to extract this parameter from the path of the HTTP request.
source
path
To use this variation, please specify the type: path
in your configuration.
position
The numeric value specific the location of the argument (starting from 0).
header
Instructs the plugin to extract this parameter from a header in the HTTP request.
source
header
To use this variation, please specify the type: header
in your configuration.
name
The name of the HTTP header.
operation_name_from
{
"name": "operationName",
"source": "search_query"
}
Instructions for fetching the operationName parameter from the incoming HTTP request.
search_query
Instructs the plugin to extract this parameter from the query string of the HTTP request.
source
search_query
To use this variation, please specify the type: search_query
in your configuration.
name
The name of the HTTP query parameter.
path
Instructs the plugin to extract this parameter from the path of the HTTP request.
source
path
To use this variation, please specify the type: path
in your configuration.
position
The numeric value specific the location of the argument (starting from 0).
header
Instructs the plugin to extract this parameter from a header in the HTTP request.
source
header
To use this variation, please specify the type: header
in your configuration.
name
The name of the HTTP header.
allow_untrusted
By default, this plugin does not allow untrusted operations to be executed. This is a security measure to prevent accidental exposure of operations that are not persisted.