feat(router): support authenticated and requiresScopes directives (#538)

The implementation is based on the analysis from issue #351.

The authorization logic can be configured to operate in two modes:

- **`filter` (default mode):** This mode silently removes any fields
from the incoming GraphQL operation that the user is not authorized to
access. For each field removed, a corresponding `AuthorizationError` is
added to the `errors` array in the GraphQL response, while the rest of
the accessible data is returned as requested.
- **`reject` mode:** In this mode, the router will reject any GraphQL
operation that attempts to access one or more unauthorized fields. The
entire request is denied, and a descriptive error is returned.

Access control is defined within the supergraph schema using the
following directives:

- `@authenticated`: Restricts access to a field to only authenticated
users.
- `@requiresScopes(scopes: [[String]])`: Provides more granular control
by requiring the user to possess specific scopes. The directive supports
`AND` logic for scopes within a nested list (e.g., `["read:users",
"write:users"]`) and `OR` logic for scopes across nested lists (e.g.,
`[["read:users"], ["admin:users"]]`).

## Key Implementation Details

- **Three-Phase Process:** The authorization logic is designed for high
performance and is executed in three phases:
1. **Build Authorization Metadata:** when router loads the supergraph,
it parses also the supergraph schema to create an in-memory
representation of all `@authenticated` and `@requiresScopes` directives.
This metadata is built once and reused for all incoming requests.
2. **Collect Unauthorized Paths:** For each incoming operation, the
authorization logic traverses the query. It checks each field against
the pre-built metadata and the current `UserAuthContext`. An
`UnauthorizedPathTree` data structure is used to efficiently collect all
field paths that the user is not permitted to access.
3. **Transform or Reject the Operation:** Based on the findings from the
previous phase and the configured mode, a final decision is made. In
`filter` mode, if any unauthorized paths were found, the original
operation is rebuilt, stripping out only the unauthorized fields to
create a new, sanitized operation. In `reject` mode, the presence of any
unauthorized path leads to an rejection of the entire request.
- **Performance-First Design:** Authorization is a critical path in the
request pipeline, this feature was developed with efficiency as a core
principle. A new suite of benchmarks has been added to measure its
performance impact. The results are good, demonstrating that the entire
authorization process adds a negligible overhead of just **1-4
microseconds** for medium-sized queries, ensuring that security does not
come at the cost of performance.
- **Pre-Query Planning Execution:** Authorization is performed on the
operation's Abstract Syntax Tree (AST) before the query planning and
execution stages. This ensures that unauthorized field requests never
reach the subgraphs, preventing potential data leaks and unnecessary
processing.
- **Decoupled from Authentication:** The core logic operates on a
`UserAuthContext` struct, which contains the user's authentication
status and a set of scopes. This decouples the authorization mechanism
from the specific authentication method (e.g., JWT validation).
- **Comprehensive GraphQL Support:** The implementation correctly
handles various GraphQL features to ensure authorization is applied
accurately, including:
- Conditional directives (`@include` and `@skip`), where authorization
is bypassed for fields that are not included in the final operation.
- Complex inheritance scenarios with interfaces and object types,
correctly applying authorization rules defined on both.
- **Test Coverage:** Suite of end-to-end tests for both `filter` and
`reject` modes, covering various scenarios.

Author: kamilkisiela

.changeset/authz-directives.md

@@ -0,0 +1,46 @@
+---
+router: minor
+---
+
+## Directive-Based Authorization
+
+Introducing directive-based authorization. This allows you to enforce fine-grained access control directly from your subgraph schemas using the `@authenticated` and `@requiresScopes` directives.
+
+This new authorization layer runs before the query planner, ensuring that unauthorized requests are handled efficiently without reaching your subgraphs.
+
+### Configuration
+
+You can configure how the router handles unauthorized requests with two modes:
+
+- **`filter`** (default): Silently removes any fields the user is not authorized to see from the query. The response will contain `null` for the removed fields and an error in the `errors` array.
+- **`reject`**: Rejects the entire GraphQL operation if it requests any field the user is not authorized to access.
+
+To configure this, add the following to your `router.yaml` configuration file:
+
+```yaml
+authentication:
+  directives:
+    unauthorized:
+      # "filter" (default): Removes unauthorized fields from the query and returns errors.
+      # "reject": Rejects the entire request if any unauthorized field is requested.
+      mode: reject
+```
+
+If this section is omitted, the router will use `filter` mode by default.
+
+### JWT Scope Requirements
+
+When using the `@requiresScopes` directive, the router expects the user's granted scopes to be present in the JWT payload. The scopes should be in an array of strings or a string (scopes separated by space), within a claim named `scope`.
+
+Here is an example of a JWT payload with the correct format:
+
+```json
+{
+  "sub": "user-123",
+  "scope": [
+    "read:products",
+    "write:reviews"
+  ],
+  "iat": 1516239022
+}
+```

Cargo.lock

@@ -1,4 +1,6 @@
-use async_graphql::{EmptyMutation, EmptySubscription, Object, Schema, SimpleObject, ID};
+use async_graphql::{
+    ComplexObject, EmptyMutation, EmptySubscription, Interface, Object, Schema, SimpleObject, ID,
+};
 use lazy_static::lazy_static;
 
 lazy_static! {
@@ -42,14 +44,71 @@ lazy_static! {
     ];
 }
 
+#[derive(Interface, Clone)]
+#[allow(clippy::duplicated_attributes)] // async_graphql needs `ty` "duplicated"
+#[graphql(
+    field(name = "url", ty = "String"),
+    field(name = "handle", ty = "String")
+)]
+pub enum SocialAccount {
+    TwitterAccount(TwitterAccount),
+    GitHubAccount(GitHubAccount),
+}
+
+#[derive(SimpleObject, Clone)]
+pub struct TwitterAccount {
+    url: String,
+    handle: String,
+    followers: i32,
+}
+
+#[derive(SimpleObject, Clone)]
+pub struct GitHubAccount {
+    url: String,
+    handle: String,
+    repo_count: i32,
+}
+
 #[derive(SimpleObject, Clone)]
+#[graphql(complex)]
 pub struct User {
     id: ID,
     name: Option<String>,
     username: Option<String>,
     birthday: Option<i32>,
 }
 
+#[ComplexObject]
+impl User {
+    async fn social_accounts(&self) -> Vec<SocialAccount> {
+        vec![
+            SocialAccount::TwitterAccount(TwitterAccount {
+                url: format!(
+                    "https://twitter.com/{}",
+                    self.username.as_ref().unwrap_or(&"unknown".to_string())
+                ),
+                handle: format!(
+                    "@{}",
+                    self.username.as_ref().unwrap_or(&"unknown".to_string())
+                ),
+                followers: 1000,
+            }),
+            SocialAccount::GitHubAccount(GitHubAccount {
+                url: format!(
+                    "https://github.com/{}",
+                    self.username.as_ref().unwrap_or(&"unknown".to_string())
+                ),
+                handle: self
+                    .username
+                    .as_ref()
+                    .unwrap_or(&"unknown".to_string())
+                    .clone(),
+                repo_count: 42,
+            }),
+        ]
+    }
+}
+
 impl User {
     fn me() -> User {
         USERS[0].clone()

bench/subgraphs/accounts.rs

@@ -8,54 +8,72 @@ lazy_static! {
             name: Some("Table".to_string()),
             price: Some(899),
             weight: Some(100),
+            notes: Some("Notes for table".to_string()),
+            internal: Some("Internal for table".to_string()),
         },
         Product {
             upc: "2".to_string(),
             name: Some("Couch".to_string()),
             price: Some(1299),
             weight: Some(1000),
+            notes: Some("Notes for couch".to_string()),
+            internal: Some("Internal for couch".to_string()),
         },
         Product {
             upc: "3".to_string(),
             name: Some("Glass".to_string()),
             price: Some(15),
             weight: Some(20),
+            notes: Some("Notes for glass".to_string()),
+            internal: Some("Internal for glass".to_string()),
         },
         Product {
             upc: "4".to_string(),
             name: Some("Chair".to_string()),
             price: Some(499),
             weight: Some(100),
+            notes: Some("Notes for chair".to_string()),
+            internal: Some("Internal for chair".to_string()),
         },
         Product {
             upc: "5".to_string(),
             name: Some("TV".to_string()),
             price: Some(1299),
             weight: Some(1000),
+            notes: Some("Notes for TV".to_string()),
+            internal: Some("Internal for TV".to_string()),
         },
         Product {
             upc: "6".to_string(),
             name: Some("Lamp".to_string()),
             price: Some(6999),
             weight: Some(300),
+            notes: Some("Notes for lamp".to_string()),
+            internal: Some("Internal for lamp".to_string()),
         },
         Product {
             upc: "7".to_string(),
             name: Some("Grill".to_string()),
             price: Some(3999),
             weight: Some(2000),
+            notes: Some("Notes for grill".to_string()),
+            internal: Some("Internal for grill".to_string()),
         },
         Product {
             upc: "8".to_string(),
             name: Some("Fridge".to_string()),
             price: Some(100000),
             weight: Some(6000),
+            notes: Some("Notes for fridge".to_string()),
+            internal: Some("Internal for fridge".to_string()),
         },
         Product {
             upc: "9".to_string(),
             name: Some("Sofa".to_string()),
             price: Some(9999),
             weight: Some(800),
+            notes: Some("Notes for sofa".to_string()),
+            internal: Some("Internal for sofa".to_string()),
         }
     ];
 }
@@ -65,6 +83,8 @@ pub struct Product {
     name: Option<String>,
     price: Option<i64>,
     weight: Option<i64>,
+    notes: Option<String>,
+    internal: Option<String>,
 }
 
 pub struct Query;

bench/subgraphs/products.rs

@@ -82,6 +82,8 @@ type Product
   shippingEstimate: Int @join__field(graph: INVENTORY, requires: "price weight")
   name: String @join__field(graph: PRODUCTS)
   reviews: [Review] @join__field(graph: REVIEWS)
+  notes: String @join__field(graph: PRODUCTS)
+  internal: String @join__field(graph: PRODUCTS)
 }
 
 type Query

bench/supergraph.graphql

@@ -54,3 +54,13 @@ tokio-util = "0.7.16"
 cookie = "0.18.1"
 regex-automata = "0.4.10"
 arc-swap = "1.7.1"
+lasso2 = "0.8.2"
+ahash = "0.8.12"
+
+[dev-dependencies]
+criterion = { workspace = true }
+insta = { workspace = true }
+
+[[bench]]
+name = "router_benches"
+harness = false