Authenticating Requests with the GraphOS Router

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

• Use authorization directives
• 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!

Use authorization directives

In addition to the approaches outlined below, you can use authorization directives to enforce authorization at the router layer. This allows you to authorize requests prior to them hitting your subgraphs saving on bandwidth and processing time.

Once the request's claims are made available via the JWT validation or a coprocessor, they can be used to match against the required type and field scopes to enforce authorization policies.

1
# Request's authorization claims must contain `read:users`
2
type Query {
3
  users: [User!]! @requiresScopes(scopes: [["read:users"]])
4
}
5

6
# Request must be authenticated
7
type Mutation {
8
  updateUser(input: UpdateUserInput!): User! @authenticated
9
}

Pros:

• Validating authorization before processing requests enables the early termination of unauthorized requests reducing the load on your services
• Declarative approach that can be adopted and maintained by each subgraph while enforced centrally

Cons

• Schema updates will need to be made to each subgraph to opt into this authorization model

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 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 the JWT Authentication plugin to validate JWT-based authentication tokens.
2. Use auth directives to enforce authentication and authorization and at the supergraph layer
3. Use a coprocessor to identify traffic using a legacy authentication strategy and convert legacy session tokens to JWTs.
4. Forward JWTs to subgraphs for additional authorization.