GraphOS authorization: add an example of scope manipulation with router service level rhai

.changesets/feat_geal_authorization_directives.md

@@ -0,0 +1,24 @@
+### GraphOS Enterprise: authorization directives ([PR #3397](https://github.com/apollographql/router/pull/3397), [PR #3662](https://github.com/apollographql/router/pull/3662))
+
+We introduce two new directives, `requiresScopes` and `@authenticated`, that define authorization policies for fields and types in the supergraph schema.
+
+They are defined as follows:
+
+```graphql
+scalar federation__Scope
+directive @requiresScopes(scopes: [[federation__Scope!]!]!) on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM
+
+directive @authenticated on OBJECT | FIELD_DEFINITION | INTERFACE | SCALAR | ENUM
+```
+
+The implementation hooks into the request lifecycle at multiple steps:
+- In query analysis, we extract the list of scopes necessary to authorize the query.
+- In a supergraph plugin, we calculate the authorization status and put it in the request context:
+    - for `@requiresScopes`, this is the intersection of the query's required scopes and the scopes provided in the request token
+    - for `@authenticated`, it is `is_authenticated` or not
+- In the query planning phase, we filter the query to remove unauthorized fields before proceeding with query planning.
+- At the subgraph level, if query deduplication is active, the authorization status is used to group queries together.
+- At the execution service level, the response is first formatted according to the filtered query, which removed any unauthorized information, then to the shape of the original query, which propagates nulls as needed.
+- At the execution service level, errors are added to the response indicating which fields were removed because they were not authorized.
+
+By [@Geal](https://github.com/Geal) in https://github.com/apollographql/router/pull/3397 https://github.com/apollographql/router/pull/3662

.changesets/maint_geal_authorization_analytics.md

@@ -0,0 +1,8 @@
+### Add a metric tracking authorization usage ([PR #3660](https://github.com/apollographql/router/pull/3660))
+
+The new metric is a counter called `apollo.router.operations.authorization` and contains the following boolean attributes:
+- `filtered`: the query has one or more filtered fields 
+- `requires_scopes`: the query uses fields or types tagged with the `@requiresScopes` directive
+- `authenticated`: the query uses fields or types tagged with the `@authenticated` directive
+
+By [@Geal](https://github.com/Geal) in https://github.com/apollographql/router/pull/3660

docs/source/config.json

@@ -42,6 +42,13 @@
             "enterprise"
           ]
         ],
+        "Authorization": [
+          "/configuration/authorization",
+          [
+            "enterprise",
+            "experimental"
+          ]
+        ],      
         "Subgraph Authentication": "/configuration/authn-subgraph",
         "Operation limits": [
           "/configuration/operation-limits",