Safelisting with Persisted Queries

With GraphOS Enterprise, you can enhance your supergraph's security by maintaining a persisted query list (PQL) for your GraphOS Router. To create and update the PQL, first-party apps register trusted operations to the PQL at build time.

At runtime, the router checks incoming requests against the PQL, which can act as operation safelist, depending on your router configuration.

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 Core also supports a related feature called automatic persisted queries (APQ). With APQ, clients can execute a GraphQL operation by sending the SHA256 hash of its operation string instead of the entire string. APQ doesn't support safelisting because the router updates its APQ cache over time with any operations it receives.

For more details on differences between APQ and this feature, see the GraphOS persisted queries documentation.

Implementation

Enabling operation safelisting has a few steps:

1. PQL creation and linking

2. Router configuration

3. Operation registration

4. Client updates

This article details the router configuration step. For more information on other configuration aspects, see the GraphOS persisted queries documentation.

Router configuration

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 v1.32.0 or later of the router. (The feature was released in preview in version v1.25.0 and made generally available in v1.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 safelisting security level.

Router security levels

The GraphOS 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 audit mode. You can then enable increasingly restrictive levels after your teams have updated all clients.

See below for sample YAML configurations for each level. Refer to the router configuration options for option details.

Allow operation IDs

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

1persisted_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:

1persisted_queries:
2  enabled: true
3  log_unknown: true

Unregistered operations appear in your router's logs.

For example:

12023-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 add new ones to your PQL if necessary.

Safelisting

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

1persisted_queries:
2  enabled: true
3  log_unknown: true
4  safelist:
5    enabled: true
6    require_id: false
7apq:
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 router's logs.

You can opt out of safelist enforcement for individual requests via a router customization (Rhai script, coprocessor, etc).

Safelisting with IDs only

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

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

If you want to use this security level, you should always first set up safelisting with operation strings allowed. ID-only safelisting requires all your clients to execute operations via PQL-specified ID instead of an operation string. While making those necessary changes, you can use the less restrictive safelisting mode in your router.

With log_unknown set to true, the router logs all rejected operations, including those registered to your PQL but that used the full operation string rather than the PQL-specified ID.

You can opt out of safelist enforcement for individual requests via a router customization (Rhai script, coprocessor, etc).

Configuration options

The router provides four configuration options that you can combine to create the recommended security levels. This section details each configuration option. Refer to the security levels section for recommended combinations.

persisted_queriesSince 1.32.0

This base configuration enables the feature. All other configuration options build off this one.

1persisted_queries:
2  enabled: true

log_unknownSince 1.32.0

Adding log_unknown: true to persisted_queries configures the router to log any incoming operations not registered to the PQL.

1persisted_queries:
2  enabled: true
3  log_unknown: true

If used with the safelist option, the router logs unregistered and rejected operations. With safelist.require_id off, the only rejected operations are unregistered ones. If safelist.require_id is turned on, operations can be rejected even when registered because they use operation IDs rather than operation strings.

experimental_prewarm_query_plan_cacheSince 1.55.0

By default, the router prewarms the query plan cache using all operations on the PQL when a new schema is loaded, but not at startup. Using the experimental_prewarm_query_plan_cache option, you can tell the router to prewarm the cache using the PQL on startup as well, or tell it not to prewarm the cache when reloading the schema. (This does not affect whether the router prewarms the query plan cache with recently-used operations from its in-memory cache.) Prewarming the cache can reduce request latency by ensuring that operations are pre-planned when requests are received, but can make startup or schema reloads slower.

1persisted_queries:
2  enabled: true
3  experimental_prewarm_query_plan_cache:
4    on_startup: true # default: false
5    on_reload: false # default: true

local_manifestsSince 1.55.0

Adding local_manifests to your persisted-queries configuration lets you use local persisted query manifests instead of the hosted Uplink version. This is helpful when you're using an offline Enterprise license and can't use Uplink. With local_manifests, the router doesn't reload the manifest from the file system, so you need to restart the router to apply changes.

1persisted_queries:
2  enabled: true
3  local_manifests:
4    - ./path/to/persisted-query-manifest.json

You can download a version of your manifest to use locally from GraphOS Studio. Open the PQL page for a graph by clicking the Go to persisted query lists to the left of the graph's name. Then, click the ••• menu under the Actions column to download a PQL's manifest as a JSON file. Save this file locally and update your local_manifests configuration with the path the file.

hot_reloadSince 2.1.0

If you configure local_manifests, you can set hot_reload to true to automatically reload manifest files whenever they change. This lets you update local manifest files without restarting the router.

1persisted_queries:
2  enabled: true
3  local_manifests:
4    - ./path/to/persisted-query-manifest.json
5  hot_reload: true

safelistSince 1.32.0

Adding safelist: true to persisted_queries causes the router to reject any operations that haven't been registered to your PQL.

1persisted_queries:
2  enabled: true
3  safelist:
4    enabled: true
5apq:
6  enabled: false

By default, the require_id suboption is false, meaning the router accepts both operation IDs and operation strings as long as the operation is registered.

require_idSince 1.32.0

Adding require_id: true to the safelist option causes the router to reject any operations that either:

• haven't been registered to your PQL

• use a full operation string rather than the operation ID

1persisted_queries:
2  enabled: true
3  safelist:
4    enabled: true
5    require_id: true
6apq:
7  enabled: false

Customization via request context

GraphOS Router can be customized via several mechanisms such as Rhai scripts and coprocessors. These plugins can affect your router's persistent query processing by writing to the request context.

apollo_persisted_queries::client_name

When publishing operations to a PQL, you can specify a client name associated with the operation (by including a clientName field in the individual operation in your manifest, or by including the --for-client-name option to rover persisted-queries publish). If an operation has a client name, it will only be executed by requests that specify that client name. (Your PQL can contain multiple operations with the same ID and different client names.)

Your customization (Rhai script, coprocessor, etc) can examine a request during the Router Service stage of the request path and set the apollo_persisted_queries::client_name value in the request context to the request's client name.

If this context value is not set by a customization, your router will use the same client name used for client awareness in observability. This client name is read from an HTTP header specified by telemetry.apollo.client_name_header, or apollographql-client-name by default.

If your request specifies an ID and a client name but there is no operation in the PQL with that ID and client name, your router will look to see if there is an operation with that ID and no client name specified, and use that if it finds it.

apollo_persisted_queries::safelist::skip_enforcement

If safelisting is enabled, you can still opt out of safelist enforcement on a per-request basis.

Your customization (Rhai script, coprocessor, etc) can examine a request during the Router Service stage of the request path and set the apollo_persisted_queries::safelist::skip_enforcement value in the request context to the boolean value true.

For any request where you set this value, Router will skip safelist enforcement: requests with a full operation string will be allowed even if they are not in the safelist, and even if safelist.required_id is enabled.

This does not affect the behavior of the log_unknown option: unknown operations will still be logged if that option is set.

Limitations

• Unsupported with offline license. An GraphOS Router using an offline Enterprise license cannot use safelisting with persisted queries. The feature relies on Apollo Uplink to fetch persisted query manifests, so it doesn't work as designed when the router is disconnected from Uplink.