Overview of Authorization in the GraphOS Router

APIs provide access to business-critical data. Unrestricted access can result in data breaches, monetary losses, or potential denial of service. Even for internal services, checks can be essential to limit data to authorized parties.

Services may have their own access controls, but enforcing authorization in the Apollo Router is valuable for a few reasons:

• Optimal query execution: Validating authorization before processing requests enables the early termination of unauthorized requests. Stopping unauthorized requests at the edge of your graph reduces the load on your services and enhances performance.

  • If every field in a particular subquery requires authorization, the router's query planner can eliminate entire subgraph requests for unauthorized requests. For example, a request may have permission to view a particular user's posts on a social media platform but not have permission to view any of that user's personally identifiable information (PII). Check out How it works to learn more.

  • Also, query deduplication groups requested fields based on their required authorization. Entire groups can be eliminated from the query plan if they don't have the correct authorization.

• Declarative access rules: You define access controls at the field level, and GraphOS composes them across your services. These rules create graph-native governance without the need for an extra orchestration layer.

• Principled architecture: Through composition, the router centralizes authorization logic while allowing for auditing at the service level. This centralized authorization is an initial checkpoint that other service layers can reinforce.

How access control works

The GraphOS Router provides access controls via authorization directives that define access to specific fields and types across your supergraph:

• The @requiresScopes directive allows granular access control through the scopes you define.

• The @authenticated directive allows access to the annotated field or type for authenticated requests only.

• The @policy directive offloads authorization validation to a Rhai script or a coprocessor and integrates the result in the router. It's useful when your authorization policies go beyond simple authentication and scopes.

For example, imagine you're building a social media platform that includes a Users subgraph. You can use the @requiresScopes directive to declare that viewing other users' information requires the read:user scope:

1type Query {
2  users: [User!]! @requiresScopes(scopes: [["read:users"]])
3}

You can use the @authenticated directive to declare that users must be logged in to update their own information:

1type Mutation {
2  updateUser(input: UpdateUserInput!): User! @authenticated
3}

You can define both directives—together or separately—at the field level to fine-tune your access controls. When directives are declared both on a field and the field's type, they will all be tried, and the field will be removed if any of them does not authorize it. GraphOS composes restrictions into the supergraph schema so that each subgraph's restrictions are respected. The router then enforces these directives on all incoming requests.

Next steps

• Learn how to use authorization directives in your GraphQL schemas to secure access to your graphs.