Authenticating requests with the Apollo Router

When using the Apollo Router as the entry point to your federated supergraph, you have a few options for authenticating incoming client requests:

• Delegate authentication to your subgraphs.
• Use the JWT Authentication plugin to your supergraph.
• Use a coprocessor.

In fact, we recommend you combine all three strategies to create a more robust authentication system!

Authenticate in subgraphs

The simplest authentication strategy is to delegate authentication to your individual subgraph services.

To pass Authentication headers from client requests to your subgraphs, add the following to your router's YAML configuration file:

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

Pros

• Requires minimal changes to your router configuration.
• Can take advantage of existing authentication code in subgraphs, which is often tied to authorization logic for data sources.

Cons

• Each subgraph that contributes to resolving a request needs to authenticate that request.
• If subgraphs are written in different languages, maintaining consistent authentication code for each is complex.

Use the JWT Authentication plugin

As of Apollo Router v1.13, you can use the JWT Authentication plugin to validate JWT-based authentication tokens in your supergraph.

1
authentication:
2
  jwt:
3
    jwks:
4
      - url: https://dev-zzp5enui.us.auth0.com/.well-known/jwks.json

Pros:

• The router prevents unauthenticated requests from reaching your subgraphs.
• The router can extract claims from the JWT and pass them to your subgraphs as headers, reducing logic needed in your subgraphs.

Cons:

• It supports only JWT-based authentication with keys from a JWKS endpoint.

Use a coprocessor

If you have a custom authentication strategy, you can use a coprocessor to implement it.

1
coprocessor:
2
  url: http://127.0.0.1:8081
3
  router:
4
    request:
5
      headers: true

This example coprocessor is written in Node.js and uses Express:

1
const app = express();
2
app.use(bodyParser.json());
3
app.post('/', async (req, res) => {
4
  const {headers} = req.body;
5
  const token = headers.authorization;
6
  const isValid = await validateToken(token);
7
  if (!isValid) {
8
    res.json({
9
      ...req.body,
10
      control: {break: 401}
11
    });
12
  } else {
13
    res.json({
14
      ...req.body,
15
      control: 'continue',
16
      headers: {'x-claims': extractClaims(token)}
17
    });
18
  }
19
});

Pros:

• You can implement any authentication strategy in any language or framework, as long as the coprocessor provides an HTTP endpoint.
• You can use the coprocessor to add headers to requests, which can be used by your subgraphs for additional authorization.

Cons:

• The initial lift of implementing a coprocessor is non-trivial, but once it's in place you can leverage it for any number of router customizations.

Combining authentication strategies

You can combine the strategies to handle a number of authentication requirements and practice "defense-in-depth":

1. Use a coprocessor to identify traffic using a legacy authentication strategy and convert legacy session tokens to JWTs.
2. Use the JWT Authentication plugin to validate JWT-based authentication tokens.
3. Forward JWTs to subgraphs for additional authorization.