Configuring CORS in the Apollo Router

Control browser access to your router

This article describes CORS configuration that's specific to the Apollo Router. For a more general introduction to CORS and common considerations, see the following sections:

By default, the Apollo Router enables only Apollo Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to do one of the following in the cors section of your router's YAML config file:

Add the origins of those web applications to the router's list of allowed origins.
- Use this option if there is a known, finite list of web applications that consume your supergraph.
Add a regex that matches the origins of those web applications to the router's list of allowed origins.
- This option comes in handy if you want to match origins against a pattern, see the example below that matches subdomains of a specific namespace.
Enable the allow_any_origin option.
- Use this option if your supergraph is a public API with arbitrarily many web app consumers.
- With this option enabled, the router sends the wildcard (*) value for the Access-Control-Allow-Origin header. This enables any website to initiate browser connections to it (but they can't provide cookies or other credentials).
You must use the origins + match_origins option if clients need to authenticate their requests with cookies.

The following snippet includes an example of each option (use either allow_any_origin, or origins + match_origins):

router.yaml

1
cors:
2

3
  # Set to true to allow any origin
4
  # (Defaults to false)
5
  allow_any_origin: true
6

7
  # List of accepted origins
8
  # (Ignored if allow_any_origin is true)
9
  # (Defaults to the Apollo Studio url: `https://studio.apollographql.com`)
10
  #
11
  # An origin is a combination of scheme, hostname and port.
12
  # It does not have any path section, so no trailing slash.
13
  origins:
14
    - https://www.your-app.example.com
15
    - https://studio.apollographql.com # Keep this so Apollo Studio can run queries against your router
16
  match_origins:
17
    - "^https://([a-z0-9]+[.])*api[.]example[.]com$" # any host that uses https and ends with .api.example.com

You can also disable CORS entirely by setting origins to an empty list:

router.yaml

1
cors:
2
  origins: []

If your router serves exclusively non-browser-based clients, you probably don't need to modify the default CORS configuration.

Passing credentials

If your router requires requests to include a user's credentials (e.g., via cookies), you need to modify your CORS configuration to tell the browser those credentials are allowed.

You can enable credentials with CORS by setting the Access-Control-Allow-Credentials HTTP header to true.

Your router's config file must specify individual origins to support credentialed requests. If your router enables allow_any_origin, your browser will refuse to send credentials.

To allow browsers to pass credentials to the Apollo Router, set allow_credentials to true, like so:

router.yaml

1
cors:
2
  origins:
3
    - https://www.your-app.example.com
4
    - https://studio.apollographql.com
5
  allow_credentials: true

Additionally, you'll need to configure the router to forward the Cookie header to some (or all) of your subgraphs:

router.yaml

1
headers:
2
  all:
3
    request:
4
      - propagate:
5
          named: cookie

For examples of sending cookies and authorization headers from Apollo Client, see Authentication.

All `cors` options

The following snippet shows all CORS configuration defaults for the Apollo Router:

router.yaml

1
#
2
# CORS (Cross Origin Resource Sharing)
3
#
4
cors:
5

6
  # Set to true to allow any origin
7
  allow_any_origin: false
8

9
  # List of accepted origins
10
  # (Ignored if allow_any_origin is set to true)
11
  #
12
  # An origin is a combination of scheme, hostname and port.
13
  # It does not have any path section, so no trailing slash.
14
  origins:
15
    - https://studio.apollographql.com # Keep this so Apollo Studio can still run queries against your router
16

17
  # Set to true to add the `Access-Control-Allow-Credentials` header
18
  allow_credentials: false
19

20
  # The headers to allow.
21
  # Not setting this mirrors a client's received `access-control-request-headers`
22
  # This is equivalent to allowing any headers,
23
  # except it will also work if allow_credentials is set to true
24
  allow_headers: []
25

26
  # Allowed request methods
27
  methods:
28
    - GET
29
    - POST
30
    - OPTIONS
31

32
  # Which response headers are available to scripts running in the
33
  # browser in response to a cross-origin request.
34
  expose_headers: []
35

36
  # Adds the Access-Control-Max-Age header
37
  # Can be set to a duration in time units 
38
  # If not set, the header is not included
39
  max_age: 2h

Response `Vary` header

A plugin may set a response Vary header. If, after all plugins are processed, there is no response Vary header, then the router will add one with a value of "origin".

Traffic shaping

CSRF prevention

Configuring CORS in the Apollo Router

Control browser access to your router

Passing credentials

All cors options

Response Vary header

All `cors` options

Response `Vary` header