Configuring CORS

The

By default, websites running on domains that differ from your server's domain can't pass cookies with their requests. For details on enabling cross-origin cookie passing for authentication, see

Why use CORS?

Most developers know about CORS because they run into the all-too-common

Internet users should always exercise caution when installing any new software on their devices. But when it comes to browsing the web, we navigate to different sites all the time, letting our browsers load content from those sites along the way. This comes with inherent risks.

As web developers, we don't want a user's browser to do anything fishy to our server while the user is visiting another website. Browser security mechanisms (e.g., CORS or SOP) can give developers peace of mind by enabling a website's server to specify which browser origins can request resources from that server.

The

If two URLs differ in their domain, protocol, or port, then those URLs come from two different origins:

1
# Same origin
2
http://example.com:8080/ <==> http://example.com:8080/
3

4
# Different origin (difference in domain, protocol, and port)
5
http://example.com:8080/ =X= https://example1.com:8081/

However, as we all know, the internet is an exciting place full of resources that can make websites better (importing images, extra fonts, making API calls, and so on). Developers needed a new protocol to relax SOP and safely share resources across different origins.

Cross-Origin Resource Sharing is the mechanism that allows a web page to share resources across different origins. CORS provides an extra layer of protection by enabling servers and clients to define HTTP headers that specify which external clients' scripts can access their resources.

Note that both SOP and CORS are related to

Choosing CORS options for your project

When thinking about configuring CORS for your application, there are two main settings to consider:

• Which origins can access your server's resources
• Whether your server accepts user credentials (i.e., cookies) with requests

Specifying origins

CORS uses

Depending on what you're building, the origins you specify in your CORS configuration might need to change when you're ready to deploy your application.

⚠️ Applications on private networks

If your browser is running your API on a private network (i.e., not on the public internet) and it relies on the privacy of that network for security, we strongly recommend

Specifically, the

If you don't, while your personal computer is on your private network, a script on any website could potentially make your browser talk to your private API.

Federated subgraphs

If you're building a

For more information, see

APIs that require cookies

If your API needs to accept

For examples, see

APIs with known consumers

If you create an API on the public internet to serve resources to your own websites or apps, you might want to

Public or embedded APIs

If you create a public API or an API to embed in websites you don't control yourself, you probably want to allow all origins to access your server's resources. You can use the

None of the above

If your application doesn't fit into any of the above categories,

Configuring CORS options for Apollo Server

Apollo Server's standalone server (i.e.,

The

Below, we set up and customize the CORS behavior for our expressMiddleware function using the

1
import { ApolloServer } from '@apollo/server';
2
import { expressMiddleware } from '@apollo/server/express4';
3
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
4
import express from 'express';
5
import http from 'http';
6
import { typeDefs, resolvers } from './schema';
7
import cors from 'cors';
8

9
const app = express();
10
const httpServer = http.createServer(app);
11
const server = new ApolloServer({
12
  typeDefs,
13
  resolvers,
14
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
15
});
16

17
await server.start();
18

19
app.use(
20
  '/graphql',
21
  cors<cors.CorsRequest>({ origin: ['https://www.your-app.example', 'https://studio.apollographql.com'] }),
22
  express.json(),
23
  expressMiddleware(server),
24
);
25

26
await new Promise<void>((resolve) => httpServer.listen({ port: 4000 }, resolve));
27
console.log(`🚀 Server ready at http://localhost:4000/graphql`);

1
import { ApolloServer } from '@apollo/server';
2
import { expressMiddleware } from '@apollo/server/express4';
3
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer';
4
import express from 'express';
5
import http from 'http';
6
import { typeDefs, resolvers } from './schema';
7
import cors from 'cors';
8

9
const app = express();
10
const httpServer = http.createServer(app);
11
const server = new ApolloServer({
12
  typeDefs,
13
  resolvers,
14
  plugins: [ApolloServerPluginDrainHttpServer({ httpServer })],
15
});
16

17
await server.start();
18

19
app.use(
20
  '/graphql',
21
  cors({ origin: ['https://www.your-app.example', 'https://studio.apollographql.com'] }),
22
  express.json(),
23
  expressMiddleware(server),
24
);
25

26
await new Promise((resolve) => httpServer.listen({ port: 4000 }, resolve));
27
console.log(`🚀 Server ready at http://localhost:4000/graphql`);

Using the cors package directly, we can configure the Access-Control-Allow-Origin header using the

Note that an origin doesn't include the path of a URL, meaning two URLs with different paths can still have the same origin. So when specifying an origin, don't include any paths or trailing slashes (e.g., use http://example.com, not http://example.com/).

If you're using another integration of Apollo Server, you can add and configure CORS for your server using your framework's standard functionality.

You can also choose to omit CORS middleware entirely to disable cross-origin requests. This is

Passing credentials with CORS

If your server requires requests to

You can enable credentials with CORS by setting the

To enable your browser to pass credentials using expressMiddleware and the cors npm package, you can specify origins and

1
app.use(
2
  '/graphql',
3
  cors<cors.CorsRequest>({
4
    origin: yourOrigin,
5
    credentials: true,
6
  }),
7
  express.json(),
8
  expressMiddleware(server),
9
);

1
app.use(
2
  '/graphql',
3
  cors({
4
    origin: yourOrigin,
5
    credentials: true,
6
  }),
7
  express.json(),
8
  expressMiddleware(server),
9
);

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

Preventing Cross-Site Request Forgery (CSRF)

Your server's CORS policy enables you to control which websites can talk to your server. In most cases, the browser checks your server's CORS policy by sending a

However, in some circumstances, the browser will not send this preflight request. If the request is considered

Unfortunately, this means that your server might execute GraphQL operations from "simple" requests sent by sites that shouldn't be allowed to communicate with your server. And these requests can even contain cookies! Although the browser will hide your server's response data from the malicious code, that might not be sufficient. If running the operation has side effects, then the attacker might not care if it can read the response or not, as long as it can use an unsuspecting user's browser (and cookies!) to trigger those side effects. Even with a read-only query, the malicious code might be able to figure out something about the response based entirely on how long the query takes to execute.

Attacks that use simple requests for their side effects are called

To avoid CSRF and XS-Search attacks, GraphQL servers should refuse to execute any operation coming from a browser that has not "preflighted" that operation. There's no reliable way to detect whether a request came from a browser, so GraphQL servers should not execute any operation in a "simple request".

The most important rule for whether or not a request is

However, Apollo Server also handles

By default, Apollo Server 4 has a CSRF prevention feature enabled. This means your server only executes GraphQL operations if at least one of the following conditions is true:

• The incoming request includes a Content-Type header that specifies a type other than text/plain, application/x-www-form-urlencoded, or multipart/form-data. Notably, a Content-Type of application/json (including any suffix like application/json; charset=utf-8) is sufficient. This means that all POST requests (which must use Content-Type: application/json) will be executed. Additionally, all versions of
  Apollo Client Web
  that support GET requests do include Content-Type: application/json headers, so any request from Apollo Client Web (POST or GET) will be executed.
• There is a non-empty X-Apollo-Operation-Name header. This header is sent with all operations (POST or GET) by
  Apollo iOS
  (v0.13.0+) and
  Apollo Kotlin
  (all versions, including its former name "Apollo Android"), so any request from Apollo iOS or Apollo Kotlin will be executed.
• There is a non-empty Apollo-Require-Preflight header.

Note that all HTTP header names are case-insensitive.

HTTP requests that satisfy none of the conditions above will be rejected with a 400 status code and a message clearly explaining which headers need to be added in order to make the request succeed.

This feature should have no impact on legitimate use of your graph except in these two cases:

• you have clients that send GET requests and are not Apollo Client Web, Apollo iOS, or Apollo Kotlin
• you have enabled
  file uploads
  with graphql-upload

If either of these apply to you, you should configure the relevant clients to send a non-empty Apollo-Require-Preflight header along with all requests.

You can also configure the set of headers that allow execution. For example, if you use a GraphQL client that performs GET requests without sending Content-Type, X-Apollo-Operation-Name, or Apollo-Require-Preflight headers, but it does send a Some-Special-Header header, you can pass csrfPrevention: { requestHeaders: ['Some-Special-Header'] } to new ApolloServer(). This option replaces checking for the two headers X-Apollo-Operation-Name and Apollo-Require-Preflight in the CSRF prevention logic. The check for Content-Type remains the same.

Note that Apollo Server does not permit executing mutations in GET requests (just queries). As long as you ensure that only mutations can have side effects, you are somewhat protected from the "side effects" aspect of CSRFs even without enabling CSRF protection. However, you would still be vulnerable to XS-Search timing attacks.

graphql-upload

The

The graphql-upload package adds a special middleware that parses POST requests with a Content-Type of multipart/form-data. This is one of the three special Content-Types that can be set on

Apollo Server 4's default

For example, if you use the

For more information about file upload best practices, see