Safelisting with persisted queries

GraphQL APIs are broadly open by design to provide flexibility and efficiency in client development. However, this openness also introduces the risk of potentially malicious requests and the subsequent need to secure your graph.

With

At runtime, the

Your router can use its persisted query list (PQL) to both protect your supergraph and speed up your clients' operations:

• When you enable safelisting, your router rejects any incoming operations not registered in its PQL.

• Client apps can execute an operation by providing its PQL-specified ID instead of the entire operation string.

  • Requesting by ID can significantly reduce latency and bandwidth usage for large operation strings.
  • Your router can require that clients provide operations by ID and reject full operation strings—even operation strings present in the PQL.

Differences from automatic persisted queries

The Apollo Router also supports a related feature called

APQ has a few limitations compared to registered persisted queries.

If you only want to improve request latency and bandwidth usage, APQ addresses your use case. If you also want to secure your supergraph with operation safelisting, you should register operations in a PQL.

Security levels

The Apollo Router supports the following security levels, in increasing order of restrictiveness:

These levels allow you to

Implementation steps

Persisted queries provide benefits to different teams:

• Safelisting helps platform teams secure the graph and optimize its performance.
• Application developers can use registered operation IDs to write performant client code.

Implementation also requires collaboration among these parties. These are the main steps for implementing persisted queries for safelisting, along with the team that usually performs them:

Continue reading for each step's details, or skip to the

1. PQL creation and linking

To use persisted queries, you first need a persisted query list (PQL) in GraphOS Studio. Platform teams create an empty PQL in GraphOS Studio so that client teams can register operations to it.

Each PQL is associated or "linked" with a single graph in GraphOS. A graph, however, can have several PQLs. For example, one graph may need multiple PQLs if you want a separate PQL for each

1.1 PQL creation

1. From your organization's Graphs page in
   GraphOS Studio
   , open the PQL page for a graph by clicking its PQL button:

2. From the PQL page:

   • If you haven't created any PQLs yet, click Create a Persisted Query List.
   • If you already have at least one PQL, click New List in the upper right.

3. In the dialog that appears, provide a name and (optional) description for your PQL, then click Create.

   • At this point, your empty PQL has been created. The remaining dialog steps help with additional setup.

4. The second dialog step (Link) enables you to link your new PQL to one existing variant of your graph.

   • You can optionally Skip this step and link variants later (covered in the next step).

5. The third dialog step (Publish) displays your new PQL's unique ID and an example Rover CLI command for publishing operations to the PQL.

   • For now, you can leave the PQL empty. Client teams can publish operations to it in a later step.
   • Save this Rover CLI command so you can pass it on to your client teams when they publish operations.

6. The fourth and final dialog step (Configure) displays the configuration options you apply to your router to begin using your PQL. We'll cover these in a later step.

7. Click Finish to close the dialog and save your newly created PQL.

1.2 Link the PQL to variants

After you create a PQL, you can link it to one or more variants of your graph. Each router instance associated with a linked variant automatically fetches its PQL from GraphOS.

1. From the table on your graph's PQL page, open the ••• menu under the Actions column for the PQL you want to link. Click Link and Unlink Variants.

2. In the dialog that appears, use the dropdown menu to select any variants you want to link your PQL to.

3. Click Save.

After you link a PQL to a variant, GraphOS makes the PQL available in

2. Router configuration

The Apollo Router is the key component that enforces safelisting.

As soon as a graph variant has a linked PQL, you can configure router instances to fetch and use the PQL by following these steps:

1. Ensure your router instances are ready to work with PQLs:

   • Make sure you're using version 1.32.0 or later of the Apollo Router. (The feature was released in
     preview
     in version 1.25.0 and made
     generally available
     in 1.32.0.)
   • Make sure your router instances are
     connected to your GraphOS Enterprise organization
     and that they're associated with a variant that your PQL is linked to.

2. Set your desired security level in your router's YAML config file. For supported options, see

   router security levels
   . When first implementing persisted queries, it's best to start with
   audit—or "dry run"—mode
   .

3. Deploy your updated router instances to begin using your PQL.

Once your organization's PQL has registered all your clients' operations and you've ensured your client apps are only sending registered operations, you can update your router configuration to the

Router security levels

The Apollo Router supports the following security levels, in increasing order of restrictiveness:

• Allow operation IDs: Clients can optionally execute an operation by providing the operation's PQL-specified ID.
  • All other levels also provide this core capability.
  • This level doesn't provide safelisting.
• Audit mode: Executing operations by providing a PQL-specified ID is still optional, but the router also logs any unregistered operations.
  • The level serves as a dry run and helps you identify operations you may still need to register before turning on safelisting.
• Safelisting: The router rejects any incoming operations not present in its PQL. Requests can use either ID or operation string.
  • Before moving to this security level, ensure all your client operations are present in your PQL.
• Safelisting with IDs only: The router rejects any freeform GraphQL operations. Clients can only execute operations by providing their PQL-specified IDs.
  • Before moving to this security level, ensure all your clients execute operations by providing their PQL-specified ID.

When adopting persisted queries, you should start with a less restrictive security such as

See below for sample YAML configurations for each level. Refer to the

Allow operation IDs

To use persisted queries only to reduce network bandwidth and latency (not for safelisting), add the following minimal configuration:

1
persisted_queries:
2
  enabled: true

This mode lets clients execute operations by providing their PQL-specified ID instead of the full operation string. Your router also continues to accept full operation strings, even for operations that don't appear in its PQL.

Audit mode (dry run)

Turning on logging is crucial for gauging your client apps' readiness for safelisting. The logs identify which operations you need to either add to your PQL or stop your client apps from making.

To enable logging for unregistered queries, enable the log_unknown property:

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true

Unregistered operations appear in your

For example:

1
2023-08-02T11:51:59.833534Z  WARN [trace_id=5006cef73e985810eb086e5900945807] unknown operation operation_body="query ExampleQuery {\n  me {\n    id\n  }\n}\n"

If your router receives an operation registered in the PQL, no log message will be output.

You can use these router logs to audit operations sent to your router and ask client teams to

Safelisting

With the following configuration, your router allows only GraphQL operations that are present in its PQL while rejecting all other operations:

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true
4
  safelist:
5
    enabled: true
6
    require_id: false
7
apq:
8
  enabled: false # APQ must be turned off

To execute an operation, clients can provide its PQL-specified ID or full operation string. The router rejects unregistered operations, and if log_unknown is true, those operations appear in your

Safelisting with IDs only

With the following configuration, your router rejects all operation strings and only accepts registered operation IDs:

1
persisted_queries:
2
  enabled: true
3
  log_unknown: true
4
  safelist:
5
    enabled: true
6
    require_id: true 
7
apq:
8
  enabled: false # APQ must be turned off

If you want to use this security level, you should always first set up

With log_unknown set to true, the router

3. Operation registration

Registering operations to a PQL has two steps:

1. Generating persisted query manifests (PQM) using client-specific tooling
2. Publishing PQMs to the PQL using the Rover CLI tool

Building both of these into your CI/CD pipeline incorporates new operations automatically whenever you release a new client app version.

3.1 Generate persisted query manifests

Once a PQL exists in GraphOS, client teams can start publishing operations to it. To do so, you must generate JSON manifests of the operations to publish. You generate a separate manifest for each of your client apps.

1
{
2
  "format": "apollo-persisted-query-manifest",
3
  "version": 1,
4
  "operations": [
5
    {
6
      "id": "dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f",
7
      "body": "query UniversalQuery { __typename }",
8
      "name": "UniversalQuery",
9
      "type": "query"
10
    },
11
    {
12
      "id": "f11e4dcb28788af2e41689bb366472084aa1aa1e1ba633c3d605279cff08ed59",
13
      "body": "query FragmentedQuery { post { ...PostFragment } }  fragment PostFragment on Post { id title }",
14
      "name": "FragmentedQuery",
15
      "type": "query"
16
    }
17
  ]
18
}

You perform manifest generation in your CI/CD pipeline. Doing so automatically incorporates new operations when you release a new client app version.

Generation methods

Apollo Client for Web, Kotlin, and iOS each provide a mechanism for generating a manifest file from your app source. Apollo also supports manifests

See the instructions for your client library:

Apollo Client Web

1. In your app's project, install the @apollo/generate-persisted-query-manifest package as a development dependency:

   Bash

   npm install --save-dev @apollo/generate-persisted-query-manifest

   Copy

   This package includes a CLI command to generate a manifest file from your application source.

2. Generate your first manifest with the following command:

   Bash

   npx generate-persisted-query-manifest

   Copy
   • If the command succeeds, your manifest is written to persisted-query-manifest.json.
   • If the command fails (or if your manifest doesn't include all the operations you expect it to), you can configure the command's behavior using the options described in the
     package README
     .

Apollo Kotlin

To generate an operation manifest with Apollo Kotlin, you modify your project's

1
apollo {
2
  service("myapi") {
3
    packageName.set("com.example.myapi")
4
    operationManifestFormat.set("persistedQueryManifest") 
5
  }
6
}

The manifest will be generated in build/generated/manifest/apollo/myapi/persistedQueryManifest.json

Apollo iOS

To generate an operation manifest with Apollo iOS, you use the same

Relay compiler

The Rover CLI has a

3.2 Publish manifests to the PQL

After you

rover persisted-queries publish my-graph@my-variant \
  --manifest ./persisted-query-manifest.json

• The my-graph@my-variant argument is the
  graph ref
  of any variant the PQL is
  linked to
  .
  • Graph refs have the format graph-id@variant-name.
• Use the --manifest option to provide the path to the manifest you want to publish.

The persisted-queries publish command does the following:

1. Publishes all operations in the provided manifest file to the PQL linked to the specified variant, or to the specified PQL.

   • Publishing a manifest to a PQL is additive. Any existing entries in the PQL remain.
   • If you publish an operation with the same id but different details from an existing entry in the PQL, the entire publish command fails with an error.

2. Updates any other variants that the PQL is applied to so that routers associated with those variants can fetch their updated PQL.

As with

Test operations

You can send some test operations to test that you've successfully published your manifests:

First, start your GraphOS-connected router:

APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router --config ./router.yaml

2023-05-11T15:32:30.684460Z  INFO Apollo Router v1.18.1 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)
2023-05-11T15:32:30.684480Z  INFO Anonymous usage data is gathered to inform Apollo product development.  See https://go.apollo.dev/o/privacy for details.
2023-05-11T15:32:31.507085Z  INFO Health check endpoint exposed at http://127.0.0.1:8088/health
2023-05-11T15:32:31.507823Z  INFO GraphQL endpoint exposed at http://127.0.0.1:4000/ 🚀

Next, make a POST request with curl, like so:

curl http://localhost:4000 -X POST --json \
'{"extensions":{"persistedQuery":{"version":1,"sha256Hash":"dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f"}}}'

If your router's PQL includes an operation with an ID that matches the value of the provided sha256Hash property, it executes the corresponding operation and returns its result.

4. Client updates

With your

To execute operations using their PQL-specified ID instead of full operations strings, clients can use the same protocol used for automatic persisted queries (APQ).

Here's the JSON body of a request to execute an operation by its ID:

1
{
2
  "variables": null,
3
  "extensions": {
4
    "persistedQuery": {
5
      "version": 1,
6
      "sha256Hash": "PQL_ID_HERE"
7
    }
8
  }
9
}

Apollo's mobile clients let you use the same mechanism for executing persisted queries operations as APQs. Refer to their persisted query documentation for implementation details.

• Apollo iOS
• Apollo Kotlin

With Apollo Client Web, sending persisted queries by ID requires you to use an

Refer to the Apollo Client Web's

Incremental adoption path

Persisted queries'

1. Identify the first client you want to implement persisted queries with. It could be the client or team you're most comfortable with or the one most comfortable with GraphOS.

2. Follow all

   implementation steps
   for your chosen client:
   • Create and link a PQL
     to a staging or development variant.
   • When
     configuring the router
     , begin with
     audit mode
     .
   • Use the
     client-specific tooling
     to generate an
     operation manifest
     and
     publish it to the PQL
     as part of your client's CI/CD pipeline.
   • (Optional) Update your chosen client to use only registered operations, either by full operation string or operation ID.
     • Teams working with Apollo Client Web need to use an
       additional package
       at runtime to send persisted queries.

3. Continue to monitor your router logs: once you consistently see that unregistered operations are being logged and registered ones aren't, you've completed the setup for this client! 🎉

If safelisting is your goal, you'll need to

Once your router's logs are completely clear of unexpected operations, you can configure your router to use

Once you've confirmed all client apps use IDs, you can move to the most restrictive security level:

Coordinate with client teams

Once you've followed the implementation steps for one client, you can coordinate across all your client teams:

1. Identify all the client apps that execute operations against your router, and the GraphQL client libraries that those apps use.
   • Before you enable safelisting in your router, your client apps must start publishing their operations to your PQL.
2. Communicate to your client development teams that adopting persisted queries will require adding tooling to their CI/CD pipeline.
   • Specifically, each client team will need to generate client operation
     manifests
     and
     publish manifests to the PQL
     .
3. Identify which team members will assist with adding tooling to their respective CI/CD pipelines.

Guide each client team to follow the implementation steps presented in the

Persisted query list management

From the Persisted Query Lists page, you can perform the following actions by clicking the ••• menu under the Actions column on the right of any PQL:

• Download the list as a JSON file
• Publish operations
• Update the PQL's name and description
• Link and unlink variants
• Delete the PQL entirely

The Publish operations action provides the

Operation management

You can add new operations to a PQL by using the

Adding operations

To add new operations to a PQL, you need to

Deleting operations

If you want to delete an operation, you must do so from Studio. From the Persisted Query Lists page, click a persisted query list to open it. Then, click the ••• menu under the Actions column next to a particular operation and select Delete.

You should only delete operations that are problematic and shouldn't be executed. Even for such operations, it's important to recognize that operation deletions can cause application errors for legitimate clients, depending on your router's

• Regardless of security level, if a client sends an operation ID of a deleted operation, the router rejects the operation.
• If you enabled
  safelisting
  , the router rejects any operations you deleted from the PQL but that your clients still perform, whether clients send operation IDs or full operation strings for the deleted operation.
• When the router
  allows operation IDs
  or is in
  audit mode
  , if a client sends the full operation string of a deleted operation, the router executes it.

Although you can't undo operation deletions directly via the Studio UI, you can always republish a deleted operation using

Manifest format

A persisted query manifest has the following minimal structure:

1
{
2
  "format": "apollo-persisted-query-manifest",
3
  "version": 1,
4
  "operations": [
5
    {
6
      "id": "dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f",
7
      "body": "query UniversalQuery { __typename }",
8
      "name": "UniversalQuery",
9
      "type": "query"
10
    }
11
  ]
12
}

Manifest properties are documented below.

Top-level properties

Per-operation properties

Each entry in a manifest's operations array is a JSON object that describes a single GraphQL operation to publish:

1
{
2
  "id": "dc67510fb4289672bea757e862d6b00e83db5d3cbbcfb15260601b6f29bb2b8f",
3
  "body": "query UniversalQuery { __typename }",
4
  "name": "UniversalQuery",
5
  "type": "query"
6
}

Each operation object has the following properties:

Generating IDs

When generating operation IDs for a manifest, you should use a value that's unique to each operation, such as the query document's cryptographic hash. Apollo's

By generating identifiers based on query documents this way, you ensure that different operations always have different IDs. ID uniqueness prevents unexpected collisions in your PQL. It also allows the router to execute operations both by full operation strings and PQL-specified IDs.

Ensuring consistent operation documents

Whenever a client sends an operation string to a router with safelisting enabled, the router checks for that operation string's presence in its persisted query list.

When comparing an incoming freeform GraphQL document to the registered operations in its PQL, the router ignores some aspects of the document that have no semantic impact:

• Ignored tokens
  such as white space, comments, and commas are ignored.
• The order of top-level definitions (operation and fragment definitions) is ignored. This means that when assembling a full GraphQL document from its operation and fragments, there's no need to ensure that fragments are put in the same order at build time and at run time.

However, all other details of the document must match. For example, field order, argument order, $variable names, alias names, string and numeric literals, and the presence of __typename fields must match between the incoming freeform GraphQL document and the document in the persisted query list.

For example, most applications treat responses from the following queries equivalently, but the router would reject the client operation because it doesn't match the PQL entry exactly. (The operations do semantically differ because GraphQL servers

query GetBooks {
  books {
    publishDate
    title
  }
}

query GetBooks {
  books {
    title
    publishDate
  }
}

Ordering differences (other than the order of top-level definitions) between a registered operation and the operation a client sends can similarly cause the router to reject client operations, even if they have no semantic impact on the operation.

query GetBooks($limit: Int, $offset: Int) {
  books(limit: $limit, offset: $offset) {
    title
  }
}

query GetBooks($limit: Int, $offset: Int) {
  books(offset: $offset, limit: $limit) {
    title
  }
}

To ensure that you generate manifest entries correctly, it's important to note that your app's client library may modify the operation strings you define in your source before executing those corresponding operations. For example, by default, all Apollo Client libraries add the __typename field to every object in a query if that field isn't already present:

query GetBooks {
  books {
    author
    title
  }
}

query GetBooks {
  books {
    author
    title
    __typename 
  }
}

If you're building your own manifest generation tool, ensure it accounts for any such operation changes in your chosen client library. Otherwise, the router will reject your app's operations due to an operation string mismatch if safelisting is enabled.

Similarly, if your clients execute operations by providing their PQL-specified ID, they might execute an operation without the augmentation added by your client library if you don't account for these operation changes.