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.

Prerequisites

Before using the authorization directives in your subgraph schemas, you must:

• Validate that your GraphOS Router uses version 1.29.1 or later and is connected to your GraphOS Enterprise organization

• Include claims in requests made to the router (for @authenticated and @requiresScopes)

Configure request claims

Claims are the individual details of a request's authentication and scope. They might include details like the ID of the user making the request and any authorization scopes—for example, read:profiles— assigned to that user. The authorization directives use a request's claims to evaluate which fields and types are authorized.

To provide the router with the claims it needs, you must either configure JSON Web Token (JWT) authentication or add an external coprocessor that adds claims to a request's context. In some cases (explained below), you may require both.

• JWT authentication configuration: If you configure JWT authentication, the GraphOS Router automatically adds a JWT token's claims to the request's context at the apollo_authentication::JWT::claims key.

• Adding claims via coprocessor: If you can't use JWT authentication, you can add claims with a coprocessor. Coprocessors let you hook into the GraphOS Router's request-handling lifecycle with custom code.

• Augmenting JWT claims via coprocessor: Your authorization policies may require information beyond what your JSON web tokens provide. For example, a token's claims may include user IDs, which you then use to look up user roles. For situations like this, you can augment the claims from your JSON web tokens with coprocessors.

Authorization directives

Authorization directives are turned on by default. To disable them, include the following in your router's YAML config file:

1authorization:
2  directives:
3    enabled: false

@requiresScopesSince 1.29.1

The @requiresScopes directive marks fields and types as restricted based on required scopes. The directive includes a scopes argument with an array of the required scopes to declare which scopes are required:

1@requiresScopes(scopes: [["scope1", "scope2", "scope3"]])

Depending on the scopes present on the request, the router filters out unauthorized fields and types.

You can use Boolean logic to define the required scopes. See Combining required scopes for details.

The directive validates the required scopes by loading the claims object at the apollo_authentication::JWT::claims key in a request's context. The claims object's scope key's value should be a space-separated string of scopes in the format defined by the OAuth2 RFC for access token scopes.

1claims = context["apollo_authentication::JWT::claims"]
2claims["scope"] = "scope1 scope2 scope3"

1fn router_service(service) {
2  let request_callback = |request| {
3    let claims = request.context["apollo_authentication::JWT::claims"];
4    let roles = claims["roles"];
5
6    let scope = "";
7    if roles.len() > 1 {
8      scope = roles[0];
9    }
10
11    if roles.len() > 2 {
12      for i in 1..roles.len() {
13        scope += ' ';
14        scope += roles[i];
15      }
16    }
17
18    claims["scope"] = scope;
19    request.context["apollo_authentication::JWT::claims"] = claims;
20  };
21  service.map_request(request_callback);
22}

Usage

To use the @requiresScopes directive in a subgraph, you can import it from the @link directive like so:

1extend schema
2  @link(
3    url: "https://specs.apollo.dev/federation/v2.5",
4    import: [..., "@requiresScopes"])

It is defined as follows:

1scalar federation__Scope
2directive @requiresScopes(scopes: [[federation__Scope!]!]!) on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

Combining required scopes with AND/OR logic

A request must include all elements in the inner-level scopes array to resolve the associated field or type. In other words, the authorization validation uses AND logic between the elements in the inner-level scopes array.

1@requiresScopes(scopes: [["scope1", "scope2", "scope3"]])

For the preceding example, a request would need scope1 AND scope2 AND scope3 to be authorized.

You can use nested arrays to introduce OR logic:

1@requiresScopes(scopes: [["scope1"], ["scope2"], ["scope3"]])

For the preceding example, a request would need scope1 OR scope2 OR scope3 to be authorized.

You can nest arrays and elements as needed to achieve your desired logic. For example:

1@requiresScopes(scopes: [["scope1", "scope2"], ["scope3"]])

This syntax requires requests to have either (scope1 AND scope2) OR just scope3 to be authorized.

Example @requiresScopes use case

Imagine the social media platform you're building lets users view other users' information only if they have the required permissions. Your schema may look like this:

1type Query {
2  user(id: ID!): User @requiresScopes(scopes: [["read:others"]])
3  users: [User!]! @requiresScopes(scopes: [["read:others"]])
4  post(id: ID!): Post
5}
6
7type User {
8  id: ID!
9  username: String
10  email: String @requiresScopes(scopes: [["read:email"]])
11  profileImage: String
12  posts: [Post!]!
13}
14
15type Post {
16  id: ID!
17  author: User!
18  title: String!
19  content: String!
20}

Depending on a request's attached scopes, the router executes the following query differently. If the request includes only the read:others scope, then the router executes the following filtered query:

1query {
2  users {
3    username
4    profileImage
5    email
6  }
7}

1query {
2  users {
3    username
4    profileImage
5  }
6}

The response would include an error at the /users/@/email path since that field requires the read:emails scope. The router can execute the entire query successfully if the request includes the read:others read:emails scope set.

The router returns null for unauthorized fields and applies the standard GraphQL null propagation rules.

1{
2  "data": {
3    "me": null,
4		"post": {
5			"title": "Securing supergraphs",
6		}
7  },
8  "errors": [
9    {
10      "message": "Unauthorized field or type",
11      "path": [
12        "me"
13      ],
14      "extensions": {
15        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
16      }
17    },
18    {
19      "message": "Unauthorized field or type",
20      "path": [
21        "post",
22        "views"
23      ],
24      "extensions": {
25        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
26      }
27    }
28  ]
29}

@authenticatedSince 1.29.1

The @authenticated directive marks specific fields and types as requiring authentication. It works by checking for the apollo_authentication::JWT::claims key in a request's context, that is added either by the JWT authentication plugin, when the request contains a valid JWT, or by an authentication coprocessor. If the key exists, it means the request is authenticated, and the router executes the query in its entirety. If the request is unauthenticated, the router removes @authenticated fields before planning the query and only executes the parts of the query that don't require authentication.

Usage

To use the @authenticated directive in a subgraph, you can import it from the @link directive like so:

1extend schema
2  @link(
3    url: "https://specs.apollo.dev/federation/v2.5",
4    import: [..., "@authenticated"])

It is defined as follows:

1directive @authenticated on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

Example @authenticated use case

Diving deeper into the social media example: let's say unauthenticated users can view a post's title, author, and content. However, you only want authenticated users to see the number of views a post has received. You also need to be able to query for an authenticated user's information.

The relevant part of your schema may look like this:

1type Query {
2  me: User @authenticated
3  post(id: ID!): Post
4}
5
6type User {
7  id: ID!
8  username: String
9  email: String @requiresScopes(scopes: [["read:email"]])
10  posts: [Post!]!
11}
12
13type Post {
14  id: ID!
15  author: User!
16  title: String!
17  content: String!
18  views: Int @authenticated
19}
20

Consider the following query:

1query {
2  me {
3    username
4  }
5  post(id: "1234") {
6    title
7    views
8  }
9}

The router would execute the entire query for an authenticated request. For an unauthenticated request, the router would remove the @authenticated fields and execute the filtered query.

1query {
2  me {
3    username
4  }
5  post(id: "1234") {
6    title
7    views
8  }
9}

1query {
2  post(id: "1234") {
3    title
4  }
5}

For an unauthenticated request, the router doesn't attempt to resolve the top-level me query, nor the views for the post with id: "1234". The response retains the initial request's shape but returns null for unauthorized fields and applies the standard GraphQL null propagation rules.

1{
2  "data": {
3    "me": null,
4		"post": {
5			"title": "Securing supergraphs",
6		}
7  },
8  "errors": [
9    {
10      "message": "Unauthorized field or type",
11      "path": [
12        "me"
13      ],
14      "extensions": {
15        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
16      }
17    },
18    {
19      "message": "Unauthorized field or type",
20      "path": [
21        "post",
22        "views"
23      ],
24      "extensions": {
25        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
26      }
27    }
28  ]
29}

If every requested field requires authentication and a request is unauthenticated, the router generates an error indicating that the query is unauthorized.

@policySince 1.35.0

The @policy directive marks fields and types as restricted based on authorization policies evaluated in a Rhai script or coprocessor. This enables custom authorization validation beyond authentication and scopes. It is useful when we need more complex policy evaluation than verifying the presence of a claim value in a list (example: checking specific values in headers).

The @policy directive includes a policies argument that defines an array of the required policies that are a list of strings with no formatting constraints. In general you can use the strings as arguments for any format you like. The following example shows a policy that might require the support role:

1@policy(policies: [["roles:support"]])

Using the @policy directive requires a Supergraph plugin to evaluate the authorization policies. This is useful to bridge router authorization with an existing authorization stack or link policy execution with lookups in a database.

An overview of how @policy is processed through the router's request lifecycle:

• At the RouterService level, the GraphOS Router extracts the list of policies relevant to a request from the schema and then stores them in the request's context in apollo_authorization::policies::required as a map policy -> null|true|false.

• At the SupergraphService level, you must provide a Rhai script or coprocessor to evaluate the map. If the policy is validated, the script or coprocessor should set its value to true or otherwise set it to false. If the value is left to null, it will be treated as false by the router. Afterward, the router filters the requests' types and fields to only those where the policy is true.

• If no field of a subgraph query passes its authorization policies, the router stops further processing of the query and precludes unauthorized subgraph requests. This efficiency gain is a key benefit of the @policy and other authorization directives.

Usage

To use the @policy directive in a subgraph, you can import it from the @link directive like so:

1extend schema
2  @link(
3    url: "https://specs.apollo.dev/federation/v2.6",
4    import: [..., "@policy"])

The @policy directive is defined as follows:

1scalar federation__Policy
2directive @policy(policies: [[federation__Policy!]!]!) on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM

Using the @policy directive requires a Supergraph plugin to evaluate the authorization policies. You can do this with a Rhai script or coprocessor. Refer to the following example use case for more information. (Although a native plugin can also evaluate authorization policies, we don't recommend using it.)

Combining policies with AND/OR logic

Authorization validation uses AND logic between the elements in the inner-level policies array, where a request must include all elements in the inner-level policies array to resolve the associated field or type. For the following example, a request would need policy1 AND policy2 AND policy3 to be authorized:

1@policy(policies: [["policy1", "policy2", "policy3"]])

Alternatively, to introduce OR logic you can use nested arrays. For the following example, a request would need policy1 OR policy2 OR policy3 to be authorized:

1@policy(policies: [["policy1"], ["policy2"], ["policy3"]])

You can nest arrays and elements as needed to achieve your desired logic. For the following example, its syntax requires requests to have either (policy1 AND policy2) OR just policy3 to be authorized:

1@policy(policies: [["policy1", "policy2"], ["policy3"]])

Example @policy use case

Usage with a coprocessor

Diving even deeper into the social media example: suppose you want only a user to have access to their own profile and credit card information. Of the available authorization directives, you use @policy instead of @requiresScopes because the validation logic relies on more than the scopes of an access token.

You can add the authorization policies read_profile and read_credit_card. The relevant part of your schema may look like this:

1type Query {
2  me: User @authenticated @policy(policies: [["read_profile"]])
3  post(id: ID!): Post
4}
5
6type User {
7  id: ID!
8  username: String
9  email: String @requiresScopes(scopes: [["read:email"]])
10  posts: [Post!]!
11  credit_card: String @policy(policies: [["read_credit_card"]])
12}
13
14type Post {
15  id: ID!
16  author: User!
17  title: String!
18  content: String!
19  views: Int @authenticated
20}
21

You can use a coprocessor called at the Supergraph request stage to receive and execute the list of policies.

If you configure your router like this:

1coprocessor:
2  url: http://127.0.0.1:8081
3  supergraph:
4    request:
5      context: true

A coprocessor can then receive a request with this format:

1{
2    "version": 1,
3    "stage": "SupergraphRequest",
4    "control": "continue",
5    "id": "d0a8245df0efe8aa38a80dba1147fb2e",
6    "context": {
7        "entries": {
8            "apollo_authentication::JWT::claims": {
9                "exp": 10000000000,
10                "sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
11            },
12            "apollo_authorization::policies::required": {
13                "read_profile": null,
14                "read_credit_card": null
15            }
16        }
17    },
18    "method": "POST"
19}

A user can read their own profile, so read_profile will succeed. But only the billing system should be able to see the credit card, so read_credit_card will fail. The coprocessor will then return:

1{
2    "version": 1,
3    "stage": "SupergraphRequest",
4    "control": "continue",
5    "id": "d0a8245df0efe8aa38a80dba1147fb2e",
6    "context": {
7        "entries": {
8            "apollo_authentication::JWT::claims": {
9                "exp": 10000000000,
10                "sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
11            },
12            "apollo_authorization::policies::required": {
13                "read_profile": true,
14                "read_credit_card": false
15            }
16        }
17    }
18}

Usage with a Rhai script

For another example, suppose that you want to restrict access for posts to a support user. Given that the policies argument is a string, you can set it as a "<key>:<value>" format that a Rhai script can parse and evaluate.

The relevant part of your schema may look like this:

1type Query {
2  me: User @policy(policies: [["kind:user"]])
3}
4
5type User {
6  id: ID!
7  username: String @policy(policies: [["roles:support"]])
8}

You can then use the following Rhai script to parse and evaluate the policies string:

1fn supergraph_service(service) {
2  let request_callback = |request| {
3    let claims = request.context["apollo_authentication::JWT::claims"];
4    let policies = request.context["apollo_authorization::policies::required"];
5
6    if policies != () {
7      for key in policies.keys() {
8        let array = key.split(":");
9        if array.len == 2 {
10          switch array[0] {
11            "kind" => {
12              policies[key] = claims[`kind`] == array[1];
13            }
14            "roles" => {
15              policies[key] = claims[`roles`].contains(array[1]);
16            }
17            _ => {}
18          }
19        }
20      }
21    }
22    request.context["apollo_authorization::policies::required"] = policies;
23  };
24  service.map_request(request_callback);
25}

Special case for subscriptions

When using subscriptions along with @policy authorization, subscription events restart from the execution service, which means that if the authorization status of the subscription session changed, then it cannot go through query planning again, and the session should be closed. To that end, the policies should be evaluated again at the execution service level, and if they changed, an error should be returned to stop the subscription.

Composition and federation

GraphOS's composition strategy for authorization directives is intentionally accumulative. When you define authorization directives on fields and types in subgraphs, GraphOS composes them into the supergraph schema. In other words, if subgraph fields or types include @requiresScopes, @authenticated, or @policy directives, they are set on the supergraph too. Whether composition uses AND or OR logic depends on how the authorization directives are used.

Composed fields with different authorization directives

If a shared field uses different authorization directives across subgraphs, composition merges them using AND logic. For example, suppose the me query requires @authenticated in one subgraph and the read:user scope in another subgraph:

1type Query {
2  me: User @authenticated
3}
4
5type User {
6  id: ID!
7  username: String
8  email: String
9}

1type Query {
2  me: User @requiresScopes(scopes: [["read:user"]])
3}
4
5type User {
6  id: ID!
7  username: String
8  email: String
9}

A request must both be authenticated AND have the required read:user scope to succeed.

Composed fields with the same authorization directives

If a shared field uses the same authorization directives across subgraphs, composition merges them using OR logic. For example, suppose two subgraphs use the @requiresScopes directive on the users query. One subgraph requires the read:others scope, and another subgraph requires the read:profiles scope:

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

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

A request would need either the read:others OR the read:profiles scope to be authorized.

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

Using OR logic for shared directives simplifies schema updates. If requirements change suddenly, you don't need to update the directive in all subgraphs simultaneously.

Combining AND/OR logic with @requiresScopes

As with [combining scopes for a single use of @requiresScopes, you can use nested arrays to introduce AND logic in a single subgraph:

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

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

Since both subgraphs use the same authorization directive, composition merges them using OR logic:

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

This syntax means a request needs either (read:others AND read:users) scopes OR just the read:profiles scope to be authorized.

Authorization and @key fields

The @key directive lets you create an entity whose fields resolve across multiple subgraphs. If you use authorization directives on fields defined in @key directives, Apollo still uses those fields to compose entities between the subgraphs, but the client cannot query them directly.

Consider these example subgraph schemas:

1type Query {
2  product: Product
3}
4
5type Product @key(fields: "id") {
6  id: ID! @authenticated
7  name: String!
8  price: Int @authenticated
9}

1type Query {
2  product: Product
3}
4
5type Product @key(fields: "id") {
6  id: ID! @authenticated
7  inStock: Boolean!
8}

An unauthenticated request would successfully execute this query:

1query {
2  product {
3    name
4    inStock
5  }
6}

Specifically, under the hood, the router would use the id field to resolve the Product entity, but it wouldn't return it.

For the following query, an unauthenticated request would resolve null for id. And since id is a non-nullable field, product would return null.

1query {
2  product {
3    id
4    username
5  }
6}

This behavior resembles what you can create with contracts and the @inaccessible directive.

Authorization and interfaces

If a type implementing an interface requires authorization, unauthorized requests can query the interface, but not any parts of the type that require authorization.

For example, consider this schema where the Post interface doesn't require authentication, but the PrivateBlog type, which implements Post, does:

1type Query {
2  posts: [Post!]!
3}
4
5type User {
6  id: ID!
7  username: String
8  posts: [Post!]!
9}
10
11interface Post {
12  id: ID!
13  author: User!
14  title: String!
15  content: String!
16}
17
18type PrivateBlog implements Post @authenticated {
19  id: ID!
20  author: User!
21  title: String!
22  content: String!
23  publishAt: String
24  allowedViewers: [User!]!
25}

If an unauthenticated request were to make this query:

1query {
2  posts {
3    id
4    author
5    title
6    ... on PrivateBlog {
7      allowedViewers
8    }
9  }
10}

The router would filter the query as follows:

1query {
2  posts {
3    id
4    author
5    title
6  }
7}

The response would include an "UNAUTHORIZED_FIELD_OR_TYPE" error at the /posts/@/allowedViewers path.

Query deduplication

You can enable query deduplication in the router to reduce redundant requests to a subgraph. The router does this by buffering similar queries and reusing the result.

Query deduplication takes authorization into account. First, the router groups unauthenticated queries together. Then it groups authenticated queries by their required scope set. It uses these groups to execute queries efficiently when fulfilling requests.

Introspection

Introspection is turned off in the router by default, as is best production practice. If you've chosen to enable it, keep in mind that authorization directives don't affect introspection. All fields that require authorization remain visible. However, directives applied to fields aren't visible. If introspection might reveal too much information about internal types, then be sure it hasn't been enabled in your router configuration.

With introspection turned off, you can use GraphOS's schema registry to explore your supergraph schema and empower your teammates to do the same. If you want to completely remove fields from a graph rather than just preventing access (even with introspection on), consider building a contract graph.

Configuration options

The behavior of the authorization plugin can be modified with various options.

reject_unauthorized

The reject_unauthorized option configures whether to reject an entire query if any authorization directive failed, or any part of the query was filtered by authorization directives. When enabled, a response contains the list of paths that are affected.

1authorization:
2  directives:
3    enabled: true
4    reject_unauthorized: true # default: false

errors

By default, when part of a query is filtered by authorization, the list of filtered paths is added to the response and logged by the router. This behavior can be customized for your needs.

log

By enabling the log option, you can choose if query filtering will result in a log event being output.

1authorization:
2  directives:
3    errors:
4      log: false # default: true

response

You can configure response to define what part of the GraphQL response should include filtered paths:

• errors (default) : place filtered paths in GraphQL errors

• extensions: place filtered paths in extensions. Useful to suppress exceptions on the client side while still giving information that parts of the query were filtered

• disabled: suppress all information that the query was filtered.

1authorization:
2  directives:
3    errors:
4      response: "errors" # possible values: "errors" (default), "extensions", "disabled"

dry_run

The dry_run option allows you to execute authorization directives without modifying a query, and evaluate the impact of authorization policies without interfering with existing traffic. It generates and returns the list of unauthorized paths as part of the response.

1authorization:
2  directives:
3    enabled: true
4    dry_run: true # default: false

Additional resources

Refer to the guide on authenticating requests with the GraphOS Router for an overview of authorization and authentication techniques.

• See the Apollo Solutions auth coprocessor example for how to set up a JavaScript coprocessor that applies custom auth checks.

• See the Apollo Solutions @policy coprocessor example for how to set up a JavaScript coprocessor that evaluates policy-based authorization

• See the following Apollo Solutions repositories for examples of how to use JWT authentication with the @requiresScopes directive:

  • Standard JWT authentication and authorization

  • Non-standard authorization with Rhai scripts