Proxy Configuration

Configuring proxy settings for outgoing requests


Certain features require Apollo Server to make outgoing requests to Apollo GraphOS or another server in your infrastructure. Depending on security policies, you might need to configure an outgoing HTTP proxy in order to allow these requests. Specifically, the Usage Reporting and Schema Reporting plugins make requests to Apollo GraphOS, and the Subscription Callback plugin makes requests to your GraphOS Router.

You can override the fetcher function these plugins use to make HTTP requests. This page assumes you're using the default fetcher. If you're overriding the fetcher, check the documentation for the implementation of fetch you've selected to learn how it supports HTTP proxies.

We recommend using environment variables to configure Node.js and HTTP proxy settings.

Proxy configuration variables

You can use the following environment variables to configure the proxy:

  • HTTP_PROXY

    The URL of your proxy server.

  • HTTPS_PROXY

    The URL where HTTPS traffic (i.e. encrypted SSL/TLS traffic) is proxied. If this is not set, HTTPS traffic will route through the HTTP proxy.

  • NO_PROXY

    A comma-separated list of domains that should be excluded from being proxied. For example, '*.foo.com,10.0.1.100,baz.com'.

If you are using AS4, the environment variables need to be prefixed with GLOBAL_AGENT_ (for example, GLOBAL_AGENT_HTTP_PROXY, GLOBAL_AGENT_HTTPS_PROXY and GLOBAL_AGENT_NO_PROXY).

To enable the use of these environment variables, refer to the sections below for instructions specific to your Apollo Server and Node.js versions.

By default, Apollo Server v5 uses the Node.js built-in fetch implementation.

If you are using Node.js v24 or newer, this implementation has built-in support for configuring your HTTP proxy via environment variables. You can enable this using the NODE_USE_ENV_PROXY environment variable.

Bash
1NODE_USE_ENV_PROXY=1

You can now use the proxy configuration variables defined above.

Configuring AS5 with Node.js v20 or v22

If you are running Apollo Server v5 with Node.js v20 or v22, you need to use a bit of code to enable proxy configuration with the built-in fetch implementation.

First, install the undici library in your app. The built-in fetch implementation is based on Undici, but you still need to install the package from the npm registry in order to change this global configuration.

Bash
1npm install undici

Then, add the following to the top of your main server file, before constructing your ApolloServer object.

TypeScript
1import { setGlobalDispatcher, EnvHttpProxyAgent } from 'undici'
2
3setGlobalDispatcher(new EnvHttpProxyAgent());

You can now use the proxy configuration variables defined above. (You don't need to set NODE_USE_ENV_PROXY.)

Configuring AS4

By default, Apollo Server v4 uses the node-fetch npm package instead of the built-in Node.js fetch implementation to make requests to Apollo GraphOS. (Despite the similar names, these are completely different implementations.) This is implemented in terms of the Node.js HTTP request API, not its fetch API, and configuring this API to use HTTP proxies works differently.

Although Apollo Server supports standard Node.js "agent" configuration via https.globalAgent and http.globalAgent directly, we recommend using the global-agent package to reduce the amount of necessary configuration involved with creating a custom agent.

First, install the global-agent package:

Text
1npm install global-agent

Invoke its bootstrap method before Apollo Server is initialized:

TypeScript
1import { ApolloServer } from '@apollo/server';
2import { bootstrap } from 'global-agent';
3
4// Set up global support for environment variable based proxy configuration.
5bootstrap();
6
7// The following represents existing configuration, though it is
8// important to bootstrap the agent before Apollo Server.
9const server = new ApolloServer({
10  typeDefs,
11  resolvers,
12});

You can configure the proxy with the GLOBAL_AGENT_HTTP_PROXY, GLOBAL_AGENT_HTTPS_PROXY, and GLOBAL_AGENT_NO_PROXY environment variables, which work identically to the environment variables defined above.

If you would prefer to use environment variable names without the GLOBAL_AGENT_ prefix (e.g., if HTTP_PROXY is already set in your environment), you can set the GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE environment variable to an empty string.

Text
1GLOBAL_AGENT_ENVIRONMENT_VARIABLE_NAMESPACE=""

You can now use the proxy configuration variables defined above.

Specifying a custom SSL/TLS certificate

Depending on the proxy communication, it may be necessary to extend the default "root" certificates which Node.js trusts to include a certificate provided by the proxy administrator. These certificates will usually allow the proxy to handle SSL/TLS traffic and permit the proxy to analyze such traffic.

This can be done via Node.js' NODE_EXTRA_CA_CERTS environment variable:

  1. The appropriate certificate (i.e. PEM file) must be present on the file-system where the server is running.

  2. Start the server with the NODE_EXTRA_CA_CERTS environment variable set to that path, combined with the proxy configuration variables defined above.

shell
1$ NODE_EXTRA_CA_CERTS=/full/path/to/certificate.pem \
2  NODE_USE_ENV_PROXY=1 \
3  HTTP_PROXY=http://proxy:3128/ \
4  node index.js
Feedback

Edit on GitHub

Ask Community