Skip to content

Latest commit

 

History

History
988 lines (739 loc) · 36.4 KB

authorization.mdx

File metadata and controls

988 lines (739 loc) · 36.4 KB
title subtitle description
Authorization in the GraphOS Router
Strengthen subgraph security with a centralized governance layer
Enforce authorization in the GraphOS Router with the @requireScopes, @authenticated, and @policy directives.

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.

    flowchart LR;
  clients(Client);
  subgraph Router[" "]
    router(["<b>GraphOS Router</b>"]);
    serviceB[Users<br/>API];
    serviceC[Posts<br/>API];
  end
  router -.->|"❌ Subquery"| serviceB & serviceC;
  clients -->|"⚠️Unauthorized <br/>request"| router;
    Loading
    • 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.
    flowchart LR;
  clients(Client);
  subgraph Router[" "]
    router(["<b>GraphOS Router</b>"]);
    serviceB[Users<br/>API];
    serviceC[Posts<br/>API];
  end
  router -->|"✅ Authorized <br/> subquery"| serviceC;
    router -.->|"❌ Unauthorized <br/> subquery"| serviceB;
  clients -->|"⚠️ Partially authorized <br/>request"| router;
    Loading
    • 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.

    flowchart LR;
  clients(Client);
  Level2:::padding
  subgraph Level1["<br>🔐 Router layer&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp"]
    router(["<b>GraphOS Router</b>"]);
      subgraph Level2["🔐 Service layer"]
        serviceB[Users<br/>API];
        serviceC[Posts<br/>API];
        end
  end

  router -->|"Subquery"| serviceB & serviceC;
  clients -->|"Request"| router;

classDef padding padding-left:1em, padding-right:1em
    Loading

To learn more about why authorization is ideal at the router layer, watch Andrew Carlson's talk at Austin API Summit 2024: Centralize Data Access Control with GraphQL.

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:

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

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

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

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

Only the GraphOS Router supports authorization directives—@apollo/gateway does not. Check out the migration guide if you'd like to use them.

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

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:

authorization:
  directives:
    enabled: false

@requiresScopes

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:

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

Use @requiresScopes when access to a field or type depends only on claims associated with a claims object or access token.

If your authorization validation logic or data are more complex—such as checking specific values in headers or looking up data from other sources such as databases—and aren't solely based on a claims object or access token, use @policy instead.

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.

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

If the apollo_authentication::JWT::claims object holds scopes in another format, for example, an array of strings, or at a key other than "scope", you can edit the claims with a Rhai script.

The example below extracts an array of scopes from the "roles" claim and reformats them as a space-separated string.

fn router_service(service) {
  let request_callback = |request| {
    let claims = request.context["apollo_authentication::JWT::claims"];
    let roles = claims["roles"];

    let scope = "";
    if roles.len() > 1 {
      scope = roles[0];
    }

    if roles.len() > 2 {
      for i in 1..roles.len() {
        scope += ' ';
        scope += roles[i];
      }
    }

    claims["scope"] = scope;
    request.context["apollo_authentication::JWT::claims"] = claims;
  };
  service.map_request(request_callback);
}

Usage

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

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

It is defined as follows:

scalar federation__Scope
directive @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.

@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:

@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:

@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:

type Query {
  user(id: ID!): User @requiresScopes(scopes: [["read:others"]]) #highlight-line
  users: [User!]! @requiresScopes(scopes: [["read:others"]]) #highlight-line
  post(id: ID!): Post
}

type User {
  id: ID!
  username: String
  email: String @requiresScopes(scopes: [["read:email"]]) #highlight-line
  profileImage: String
  posts: [Post!]!
}

type Post {
  id: ID!
  author: User!
  title: String!
  content: String!
}

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:

query {
  users {
    username
    profileImage
    email
  }
}
query {
  users {
    username
    profileImage
  }
}

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.

{
  "data": {
    "me": null,
    "post": {
      "title": "Securing supergraphs"
    }
  },
  "errors": [
    {
      "message": "Unauthorized field or type",
      "path": ["me"],
      "extensions": {
        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
      }
    },
    {
      "message": "Unauthorized field or type",
      "path": ["post", "views"],
      "extensions": {
        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
      }
    }
  ]
}

@authenticated

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:

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

It is defined as follows:

directive @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:

type Query {
  me: User @authenticated #highlight-line
  post(id: ID!): Post
}

type User {
  id: ID!
  username: String
  email: String @requiresScopes(scopes: [["read:email"]])
  posts: [Post!]!
}

type Post {
  id: ID!
  author: User!
  title: String!
  content: String!
  views: Int @authenticated #highlight-line
}

Consider the following query:

query {
  me {
    username
  }
  post(id: "1234") {
    title
    views
  }
}

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.

query {
  me {
    username
  }
  post(id: "1234") {
    title
    views
  }
}
query {
  post(id: "1234") {
    title
  }
}

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.

{
  "data": {
    "me": null,
    "post": {
      "title": "Securing supergraphs"
    }
  },
  "errors": [
    {
      "message": "Unauthorized field or type",
      "path": ["me"],
      "extensions": {
        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
      }
    },
    {
      "message": "Unauthorized field or type",
      "path": ["post", "views"],
      "extensions": {
        "code": "UNAUTHORIZED_FIELD_OR_TYPE"
      }
    }
  ]
}

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

@policy

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).

If access to a field or type is restricted solely by the claims associated with a claims object or access token, consider using @requiresScopes instead.

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:

@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::required_policies 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:

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

The @policy directive is defined as follows:

scalar federation__Policy
directive @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:

@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:

@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:

@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:

type Query {
  me: User @authenticated @policy(policies: [["read_profile"]]) #highlight-line
  post(id: ID!): Post
}

type User {
  id: ID!
  username: String
  email: String @requiresScopes(scopes: [["read:email"]])
  posts: [Post!]!
  credit_card: String @policy(policies: [["read_credit_card"]]) #highlight-line
}

type Post {
  id: ID!
  author: User!
  title: String!
  content: String!
  views: Int @authenticated
}

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:

coprocessor:
  url: http://127.0.0.1:8081
  supergraph:
    request:
      context: true

A coprocessor can then receive a request with this format:

{
  "version": 1,
  "stage": "SupergraphRequest",
  "control": "continue",
  "id": "d0a8245df0efe8aa38a80dba1147fb2e",
  "context": {
    "entries": {
      "apollo_authentication::JWT::claims": {
        "exp": 10000000000,
        "sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
      },
      "apollo::authorization::required_policies": {
        "read_profile": null,
        "read_credit_card": null
      }
    }
  },
  "method": "POST"
}

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:

{
  "version": 1,
  "stage": "SupergraphRequest",
  "control": "continue",
  "id": "d0a8245df0efe8aa38a80dba1147fb2e",
  "context": {
    "entries": {
      "apollo_authentication::JWT::claims": {
        "exp": 10000000000,
        "sub": "457f6bb6-789c-4e8b-8560-f3943a09e72a"
      },
      "apollo::authorization::required_policies": {
        "read_profile": true,
        "read_credit_card": false
      }
    }
  }
}
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:

type Query {
  me: User @policy(policies: [["kind:user"]]) #highlight-line
}

type User {
  id: ID!
  username: String @policy(policies: [["roles:support"]]) #highlight-line
}

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

fn supergraph_service(service) {
  let request_callback = |request| {
    let claims = request.context["apollo_authentication::JWT::claims"];
    let policies = request.context["apollo::authorization::required_policies"];

    if policies != () {
      for key in policies.keys() {
        let array = key.split(":");
        if array.len == 2 {
          switch array[0] {
            "kind" => {
              policies[key] = claims[`kind`] == array[1];
            }
            "roles" => {
              policies[key] = claims[`roles`].contains(array[1]);
            }
            _ => {}
          }
        }
      }
    }
    request.context["apollo::authorization::required_policies"] = policies;
  };
  service.map_request(request_callback);
}

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:

type Query {
  me: User @authenticated
}

type User {
  id: ID!
  username: String
  email: String
}
type Query {
  me: User @requiresScopes(scopes: [["read:user"]])
}

type User {
  id: ID!
  username: String
  email: String
}

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

Recall that the @authenticated directive only checks for the existence of the apollo_authentication::JWT::claims key in a request's context, so authentication is guaranteed if the request includes scopes.

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:

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

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

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

Refer to the section on Combining policies with AND/OR logic for a refresher of @requiresScopes boolean syntax.

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:

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

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

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

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:

type Query {
  product: Product
}

type Product @key(fields: "id") {
  id: ID! @authenticated
  name: String!
  price: Int @authenticated
}
type Query {
  product: Product
}

type Product @key(fields: "id") {
  id: ID! @authenticated
  inStock: Boolean!
}

An unauthenticated request would successfully execute this query:

query {
  product {
    name
    inStock
  }
}

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.

query {
  product {
    id
    username
  }
}

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:

type Query {
  posts: [Post!]!
}

type User {
  id: ID!
  username: String
  posts: [Post!]!
}

interface Post {
  id: ID!
  author: User!
  title: String!
  content: String!
}

type PrivateBlog implements Post @authenticated {
  id: ID!
  author: User!
  title: String!
  content: String!
  publishAt: String
  allowedViewers: [User!]!
}

If an unauthenticated request were to make this query:

query {
  posts {
    id
    author
    title
    ... on PrivateBlog {
      allowedViewers
    }
  }
}

The router would filter the query as follows:

query {
  posts {
    id
    author
    title
  }
}

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.

authorization:
  directives:
    enabled: true
    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.

authorization:
  directives:
    errors:
      log: false # default: true

The log option should be disabled if filtering parts of queries according to the client's rights is approved as normal operation by platform operators.

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.
authorization:
  directives:
    errors:
      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.

authorization:
  directives:
    enabled: true
    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.