From fed322a67f7b095cd0a0603ee5b156048e55549f Mon Sep 17 00:00:00 2001
From: Erik Sulymosi <erik.sulymosi@gmail.com>
Date: Thu, 18 Jun 2026 15:57:30 +0200
Subject: [PATCH 1/2] Add authentication and authorization directives for
 federation

---
 .../Directives/AuthenticatedDirective.php     | 32 +++++++++++++++
 src/Federation/Directives/PolicyDirective.php | 38 ++++++++++++++++++
 .../Directives/RequiresScopesDirective.php    | 39 +++++++++++++++++++
 src/Federation/FederationPrinter.php          |  6 +++
 .../Federation/FederationSchemaTest.php       | 22 +++++++++++
 5 files changed, 137 insertions(+)
 create mode 100644 src/Federation/Directives/AuthenticatedDirective.php
 create mode 100644 src/Federation/Directives/PolicyDirective.php
 create mode 100644 src/Federation/Directives/RequiresScopesDirective.php

diff --git a/src/Federation/Directives/AuthenticatedDirective.php b/src/Federation/Directives/AuthenticatedDirective.php
new file mode 100644
index 0000000000..c735075bd4
--- /dev/null
+++ b/src/Federation/Directives/AuthenticatedDirective.php
@@ -0,0 +1,32 @@
+<?php declare(strict_types=1);
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class AuthenticatedDirective extends BaseDirective
+{
+    public const NAME = 'authenticated';
+
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */ <<<'GRAPHQL'
+"""
+Indicates to composition that the target element is accessible only to authenticated users.
+
+```graphql
+extend schema
+    @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@authenticated"])
+
+type User @key(fields: "id") @authenticated {
+  id: ID!
+  email: String!
+}
+```
+
+https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives#authenticated
+"""
+directive @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
+GRAPHQL;
+    }
+}
diff --git a/src/Federation/Directives/PolicyDirective.php b/src/Federation/Directives/PolicyDirective.php
new file mode 100644
index 0000000000..ad3a22c741
--- /dev/null
+++ b/src/Federation/Directives/PolicyDirective.php
@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class PolicyDirective extends BaseDirective
+{
+    public const NAME = 'policy';
+
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */ <<<'GRAPHQL'
+"""
+Indicates to composition that the target element is restricted based on authorization policies.
+
+```graphql
+extend schema
+    @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@policy"])
+
+type User @key(fields: "id")
+@policy(policies: [["read:user"], ["admin"]]) {
+  id: ID!
+  email: String!
+}
+```
+
+https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives#policy
+"""
+directive @policy(policies: [[federation__Policy!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
+
+"""
+An authorization policy value required by `@policy`.
+"""
+scalar federation__Policy
+GRAPHQL;
+    }
+}
diff --git a/src/Federation/Directives/RequiresScopesDirective.php b/src/Federation/Directives/RequiresScopesDirective.php
new file mode 100644
index 0000000000..e9d56b18fa
--- /dev/null
+++ b/src/Federation/Directives/RequiresScopesDirective.php
@@ -0,0 +1,39 @@
+<?php declare(strict_types=1);
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class RequiresScopesDirective extends BaseDirective
+{
+    public const NAME = 'requiresScopes';
+
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */ <<<'GRAPHQL'
+"""
+Indicates to composition that the target element is accessible only to authenticated users
+with the appropriate JWT scopes.
+
+```graphql
+extend schema
+    @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@requiresScopes"])
+
+type User @key(fields: "id")
+@requiresScopes(scopes: [["profile.read"], ["admin"]]) {
+  id: ID!
+  email: String!
+}
+```
+
+https://www.apollographql.com/docs/graphos/schema-design/federated-schemas/reference/directives#requiresscopes
+"""
+directive @requiresScopes(scopes: [[federation__Scope!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
+
+"""
+A JWT scope required by `@requiresScopes`.
+"""
+scalar federation__Scope
+GRAPHQL;
+    }
+}
diff --git a/src/Federation/FederationPrinter.php b/src/Federation/FederationPrinter.php
index a1713b4a01..911f3da4b1 100644
--- a/src/Federation/FederationPrinter.php
+++ b/src/Federation/FederationPrinter.php
@@ -21,13 +21,16 @@
 use Nuwave\Lighthouse\Federation\Directives\ComposeDirectiveDirective;
 use Nuwave\Lighthouse\Federation\Directives\ExtendsDirective;
 use Nuwave\Lighthouse\Federation\Directives\ExternalDirective;
+use Nuwave\Lighthouse\Federation\Directives\AuthenticatedDirective;
 use Nuwave\Lighthouse\Federation\Directives\InaccessibleDirective;
 use Nuwave\Lighthouse\Federation\Directives\InterfaceObjectDirective;
 use Nuwave\Lighthouse\Federation\Directives\KeyDirective;
 use Nuwave\Lighthouse\Federation\Directives\LinkDirective;
 use Nuwave\Lighthouse\Federation\Directives\OverrideDirective;
+use Nuwave\Lighthouse\Federation\Directives\PolicyDirective;
 use Nuwave\Lighthouse\Federation\Directives\ProvidesDirective;
 use Nuwave\Lighthouse\Federation\Directives\RequiresDirective;
+use Nuwave\Lighthouse\Federation\Directives\RequiresScopesDirective;
 use Nuwave\Lighthouse\Federation\Directives\ShareableDirective;
 use Nuwave\Lighthouse\Federation\Directives\TagDirective;
 use Nuwave\Lighthouse\Schema\RootType;
@@ -59,6 +62,9 @@ class FederationPrinter
         TagDirective::NAME,
         LinkDirective::NAME,
         ComposeDirectiveDirective::NAME,
+        AuthenticatedDirective::NAME,
+        RequiresScopesDirective::NAME,
+        PolicyDirective::NAME,
     ];
 
     public static function print(Schema $schema): string
diff --git a/tests/Integration/Federation/FederationSchemaTest.php b/tests/Integration/Federation/FederationSchemaTest.php
index 0c5dc1311f..c04e7f782a 100644
--- a/tests/Integration/Federation/FederationSchemaTest.php
+++ b/tests/Integration/Federation/FederationSchemaTest.php
@@ -175,6 +175,28 @@ public function testPaginationTypesAreMarkedAsSharableWhenUsingFederationV2(): v
         $this->assertStringContainsString('type SimplePaginatorInfo @shareable {', $sdl);
     }
 
+    public function testServiceQueryShouldReturnFederationV2AccessControlDirectives(): void
+    {
+        $schemaExtension = /** @lang GraphQL */ <<<'GRAPHQL'
+        extend schema @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@key", "@authenticated", "@requiresScopes", "@policy"])
+        GRAPHQL;
+
+        $typeUser = /** @lang GraphQL */ <<<'GRAPHQL'
+        type User @key(fields: "id") @authenticated @requiresScopes(scopes: [["profile.read"], ["admin"]]) @policy(policies: [["read:user"], ["admin"]]) {
+          id: ID!
+          email: String! @authenticated @requiresScopes(scopes: [["email.read"]]) @policy(policies: [["email_policy"]])
+        }
+        GRAPHQL;
+
+        $this->schema = "{$schemaExtension} {$typeUser}";
+
+        $sdl = $this->_serviceSdl();
+
+        $this->assertSdlContainsString($schemaExtension, $sdl);
+        $this->assertStringContainsString('type User @key(fields: "id") @authenticated @requiresScopes(scopes: [["profile.read"], ["admin"]]) @policy(policies: [["read:user"], ["admin"]]) {', $sdl);
+        $this->assertStringContainsString('email: String! @authenticated @requiresScopes(scopes: [["email.read"]]) @policy(policies: [["email_policy"]])', $sdl);
+    }
+
     private function _serviceSdl(): string
     {
         $response = $this->graphQL(/** @lang GraphQL */ <<<'GRAPHQL'

From 203bf52f5903d87db8b46bfdfe95a2f25f653904 Mon Sep 17 00:00:00 2001
From: Erik Sulymosi <erik.sulymosi@gmail.com>
Date: Thu, 18 Jun 2026 16:18:10 +0200
Subject: [PATCH 2/2] Update federation getting started guide with new
 directive imports and updated federation spec URL

---
 docs/6/federation/getting-started.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/6/federation/getting-started.md b/docs/6/federation/getting-started.md
index 9074497dc4..979894c359 100644
--- a/docs/6/federation/getting-started.md
+++ b/docs/6/federation/getting-started.md
@@ -28,8 +28,9 @@ See [the Apollo documentation on federated directives](https://www.apollographql
 ```graphql
 extend schema
   @link(
-    url: "https://specs.apollo.dev/federation/v2.3"
+    url: "https://specs.apollo.dev/federation/v2.9"
     import: [
+      "@authenticated"
       "@composeDirective"
       "@extends"
       "@external"
@@ -37,8 +38,10 @@ extend schema
       "@interfaceObject"
       "@key"
       "@override"
+      "@policy"
       "@provides"
       "@requires"
+      "@requiresScopes"
       "@shareable"
       "@tag"
     ]