Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS Studio
Since 1.25.0

Safelisting with persisted queries

Secure your graph while minimizing request latency


This feature is available only with a GraphOS Enterprise plan. If your organization doesn't currently have an Enterprise plan, you can test this functionality by signing up for a free Enterprise trial.

This feature is currently in preview. Your questions and feedback are highly valueddon't hesitate to get in touch with your Apollo contact or on the official Apollo GraphQL Discord.

With GraphOS Enterprise, you can enhance your 's security by maintaining a persisted query list (PQL) for your 's self-hosted . The Apollo Router checks incoming requests against the PQL, an safelist made by your first-party apps.

Queries
Trusted
queries
Supergraph
GraphQL API
GraphQL API
GraphQL API
Apollo Router
Graph
Router
Persisted
Query List
First-party apps
Web client
Android client
iOS client

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

  • When you enable safelisting, your rejects any incoming s not registered in its PQL.
  • Client apps can execute an by providing its PQL-specified ID instead of an entire string.
    • Querying by ID can significantly reduce latency and bandwidth usage for very large strings.
    • Your can require that clients provide s by ID and reject full strings—even operation strings present in the PQL.

Differences from automatic persisted queries

The Apollo also supports a related feature called automatic persisted queries (APQ). With APQ, clients can execute a GraphQL by sending the SHA256 hash of its operation string instead of the entire string. APQ doesn't support safelisting because the dynamically populates its APQ cache over time with any s it receives.

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

Implementation

Enabling safelisting has a few steps:

  1. PQL creation and linking
  2. configuration
  3. Preregistering trusted s
  4. Client updates

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

Router configuration

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

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

    • Make sure you're using version 1.25.0 or later of the Apollo .
    • Make sure your instances are connected to your GraphOS Enterprise organization and that they're associated with a that your PQL is linked to.
  2. Set your desired security level in your '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 instances to begin using your PQL.

Once your organization's PQL has preregistered all your clients' s and you've ensured your client apps are only sending preregistered operations, you can update your configuration to the safelisting security level.

Router security levels

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

  • Allow operation IDs: Clients can optionally execute an on your 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 s by providing a PQL-specified ID is still optional, but the also logs any unregistered operations.
    • The level serves as a dry run and helps you identify s you may still need to preregister before turning on safelisting.
  • Safelisting: The rejects any incoming s not present in its PQL. Requests can use either ID or operation string.
    • Before moving to this security level, ensure all your client s are present in your PQL.
  • Safelisting with IDs only: The rejects any freeform GraphQL s. Clients can only execute s by providing their PQL-specified IDs.
    • Before moving to this security level, ensure all your clients execute s 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:

router.yaml
preview_persisted_queries:
enabled: true

Note: You can use this security level with or without automatic persisted queries enabled.

This mode lets clients execute s by providing their PQL-specified ID instead of the full operation string. Your 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 s 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:

router.yaml
preview_persisted_queries:
enabled: true
log_unknown: true

Note: You can use audit mode with or without automatic persisted queries enabled.

Unregistered s appear in your router's logs.

For example:

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 receives an preregistered in the PQL, no log message will be output.

You can use these logs to audit s sent to your router and ask client teams to add new ones to your PQL if necessary.

Safelisting

⚠️ Before applying this configuration, ensure your PQL contains all GraphQL s that all active versions of your clients execute. If you enable safelisting without ensuring this, your will reject any unpublished client s.

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

router.yaml
preview_persisted_queries:
enabled: true
log_unknown: true
safelist:
enabled: true
require_id: false
apq:
enabled: false # APQ must be turned off

Note: To enable safelisting, you must turn off automatic persisted queries (APQs). APQs let clients register arbitrary operations at runtime while safelisting restricts s to those that have been explicitly preregistered.

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

So you can monitor the s your rejects, it's best to keep log_unknown as true while adopting safelisting. Once you're confident that all your clients are properly configured, you can turn it off to reduce noise in your logs.

Safelisting with IDs only

⚠️ Do not start with this configuration: It requires all your clients to execute s by providing their PQL-specified ID. If any clients still provide full operation strings, the rejects those operations, even if they're included in the safelist.

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

router.yaml
preview_persisted_queries:
enabled: true
log_unknown: true
safelist:
enabled: true
require_id: true
apq:
enabled: false # APQ must be turned off

Note: To enable safelisting, you must turn off automatic persisted queries (APQs). APQs let clients register arbitrary operations at runtime while safelisting restricts s to those that have been explicitly preregistered.

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 s via PQL-specified ID instead of an operation string. While making those necessary changes, you can use the less restrictive safelisting mode in your .

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

So you can monitor the s your rejects, it's best to keep log_unknown as true while adopting safelisting. Once you're confident that all your clients are properly configured, you can turn it off to reduce noise in your logs.

Configuration options

The 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.

preview_persisted_queries

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

router.yaml
preview_persisted_queries:
enabled: true

log_unknown

Adding log_unknown: true to preview_persisted_queries configures the to log any incoming s not preregistered to the PQL.

router.yaml
preview_persisted_queries:
enabled: true
log_unknown: true

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

safelist

Adding safelist: true to preview_persisted_queries causes the to reject any s that haven't been preregistered to your PQL.

router.yaml
preview_persisted_queries:
enabled: true
safelist:
enabled: true
apq:
enabled: false

Note: To enable safelisting, you must turn off automatic persisted queries (APQs). APQs let clients register arbitrary operations at runtime while safelisting restricts s to those that have been explicitly preregistered.

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

require_id

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

  • haven't been preregistered to your PQL
  • use a full string rather than the operation ID
router.yaml
preview_persisted_queries:
enabled: true
safelist:
enabled: true
require_id: true
apq:
enabled: false

Note: To enable safelisting, you must turn off automatic persisted queries (APQs). APQs let clients register arbitrary operations at runtime while safelisting restricts s to those that have been explicitly preregistered.

Previous
Operation limits
Next
Privacy and data collection
Edit on GitHubEditForumsDiscord