chore: implementing comments

keraron · keraron · commit 4b7fb2839cce · 2026-02-19T20:21:37.000+01:00
Signed-off-by: Aron Kerekes &lt;arkereke@cisco.com&gt;
diff --git a/docs/dir/.index b/docs/dir/.index
@@ -9,10 +9,10 @@ nav:
   - Validation: validation.md
   - Trust Model: trust-model.md
   - Features and Usage: scenarios.md
-  - Directory Sandbox:
-    - Overview: directory-sandbox.md
+  - Directory Testbed:
+    - Overview: directory-testbed.md
+    - Testbed Deployment: directory-testbed-deployment.md
     - Public Staging Environment: directory-public-staging.md
-    - Deployment: directory-sandbox-deployment.md
   - CLI Reference: directory-cli.md
   - GUI Application: directory-gui.md
   - SDK Reference: directory-sdk.md
diff --git a/docs/dir/directory-public-staging.md b/docs/dir/directory-public-staging.md
@@ -1,13 +1,18 @@
 # Directory Public Staging Environment
 
-This is a public staging environment for development and testing. Keep in mind the following:
+This page describes the Directory public staging environment and how to connect your organization to it. You establish trust by federating your SPIRE server with the Directory SPIRE server using one of two supported bundle endpoint profiles: `https_web` (used by the testbed and recommended for most cases) or `https_spiffe` (SPIFFE mutual TLS).
 
-* There are no SLA or data persistence guarantees.
-* This environment is not for production use.
-* This environment is ideal for prototyping, integration, and exploration.
+!!! note
+    The public staging environment is for development and testing. Keep in mind the following:
+
+    - There are no SLA or data persistence guarantees.
+    - This environment is not for production use.
+    - This environment is ideal for prototyping, integration, and exploration.
 
 ## Architecture Overview
 
+The following diagram shows how your application, the Directory network, and other federation members connect via the Directory API and SPIRE federation.
+
 ```mermaid
 flowchart LR
     subgraph YourApplication["Your Application"]
@@ -31,6 +36,8 @@ flowchart LR
 
 ## Available Endpoints
 
+Use the following endpoints to reach the public staging Directory API, SPIRE federation, and status dashboard.
+
 | Service              | URL                                   | Purpose                                     |
 | -------------------- | ------------------------------------- | ------------------------------------------- |
 | Directory API    | `https://api.directory.agntcy.org`    | Main API for agent discovery and management |
@@ -46,6 +53,8 @@ For the testbed production deployment the following endpoints are available:
 
 ## Quick Start Guide
 
+This section walks you through preparing your environment, configuring the client, and completing federation so you can use the public staging Directory.
+
 ### Prerequisites
 
 Before you begin, ensure you have:
@@ -171,10 +180,28 @@ To interact with the Directory, you need to establish a trusted federation betwe
 
 ### Step 1: Prepare Your Federation Request
 
-Create a file with your SPIRE server details using the template below:
+Create a federation file with your SPIRE server details. The Directory supports two bundle endpoint profiles; choose the one that matches your environment.
+
+**Option A: https_web profile** (recommended for testbed and most deployments)
+
+Federation over standard HTTPS using CA-signed certificates. No bootstrap bundle exchange is required. The testbed uses this profile.
+
+```yaml
+# onboarding/federation/your-org.com.yaml
+className: dir-spire
+trustDomain: your-org.com
+bundleEndpointURL: https://spire.your-org.com
+bundleEndpointProfile:
+  type: https_web
+```
+
+**Option B: https_spiffe profile**
+
+Federation over SPIFFE mutual TLS using X.509-SVIDs. Requires a one-time bootstrap bundle exchange with the Directory and SSL passthrough on your ingress.
 
 ```yaml
-# onboarding/your-org.com.yaml
+# onboarding/federation/your-org.com.yaml
+className: dir-spire
 trustDomain: your-org.com
 bundleEndpointURL: https://spire.your-org.com
 bundleEndpointProfile:
@@ -194,47 +221,54 @@ trustDomainBundle: |-
   }
 ```
 
-!!! tip
-    To get your trust bundle:
+!!! note
+    Organizations must establish their own secure procedures for exchanging bootstrap bundles with federation partners. The bundle exchange mechanism (email, file transfer, version control, etc.) should align with organizational security policies.
 
-    ```bash
-    # Export your SPIRE server trust bundle
-    spire-server bundle show -format spiffe > your-trust-bundle.json
-    ```
+To get your trust bundle (for `https_spiffe` or for sharing with the Directory):
+
+```bash
+# Export your SPIRE server trust bundle
+spire-server bundle show -format spiffe > your-trust-bundle.json
+```
 
 ### Step 2: Submit Federation Request
 
-1. Fork the [AGNTCY Directory repository](https://github.com/agntcy/dir)
+Submit your federation configuration to the Directory by adding a file to the [dir-staging](https://github.com/agntcy/dir-staging) repository and opening a pull request:
 
-2. Create your federation file:
+1. Fork and clone the dir-staging repository:
 
-      ```bash
-      git clone https://github.com/your-username/dir.git
-      cd dir/deployment/onboarding/
-      cp spire.template.yaml your-org.com.yaml
-      # Edit your-org.com.yaml with your details
-      ```
+   ```bash
+   git clone https://github.com/your-username/dir-staging.git
+   cd dir-staging
+   ```
 
-3. Submit a Pull Request:
+2. Add your federation file under `onboarding/federation/` using the same structure as in Step 1. Name the file after your trust domain (e.g. `your-org.com.yaml`):
 
-      - Title: `federation(<Trust Domain>): add [Your Organization]`.
-      - Description: Brief description of your organization and use case.
-      - Files: Include your completed federation configuration.
+   ```bash
+   # Create or edit your federation file
+   # Path: onboarding/federation/your-org.com.yaml
+   ```
 
-### Step 3: Configure Your SPIRE Server
+   For `https_web` (testbed / recommended): include `className`, `trustDomain`, `bundleEndpointURL`, and `bundleEndpointProfile.type: https_web`.  
+   For `https_spiffe`: also include `endpointSPIFFEID` and `trustDomainBundle` in the same file.
 
-Add the Directory SPIRE server as a federation peer in your SPIRE server configuration
-by obtaining the [Directory trust bundle](https://github.com/agntcy/dir-staging/tree/feat/deploy/onboarding).
+3. Submit a pull request to the upstream [agntcy/dir-staging](https://github.com/agntcy/dir-staging) repo:
+
+   - Title: `federation(<Trust Domain>): add [Your Organization]`
+   - Description: Brief description of your organization and use case.
+   - Files: Your new or updated file under `onboarding/federation/`.
+
+### Step 3: Configure Your SPIRE Server
 
-Save the trust bundle to the specified path.
+Add the Directory SPIRE server as a federation peer in your SPIRE server configuration. Obtain the Directory trust bundle from the [dir-staging onboarding resources](https://github.com/agntcy/dir-staging/tree/main/onboarding) (or from the Directory team after your federation request is approved) and configure it in your SPIRE server per your deployment method.
 
 ### Step 4: Verify Federation
 
 ```bash
 # Check federation status
 spire-server federation list
 
-# Should show federated trust domain
+# Should show the federated trust domain
 spire-server federation show --trustDomain dir.agntcy.org
 ```
 
diff --git a/docs/dir/directory-testbed-deployment.md b/docs/dir/directory-testbed-deployment.md
@@ -1,4 +1,4 @@
-# Sandbox Deployment
+# Testbed Deployment
 
 The [dir-staging](https://github.com/agntcy/dir-staging) repository contains the deployment manifests for AGNTCY Directory project. It is designed to be used with Argo CD for GitOps-style continuous deployment.
 
@@ -362,3 +362,190 @@ with the Directory Server, follow these steps:
     dirctl info baeareiesad3lyuacjirp6gxudrzheltwbodtsg7ieqpox36w5j637rchwq
     ```
 
+## GitHub OAuth Authentication
+
+The Directory server can be deployed with an optional Envoy gateway that provides GitHub OAuth authentication, allowing users to access the Directory API using their GitHub identity.
+
+### Features
+
+- Device Flow (default) — No OAuth App registration required.
+- Casbin RBAC — Policy-driven, role-based authorization.
+- Multi-Role Support — Define admin, reader, and custom roles.
+- Per-Method Permissions — Fine-grained API access control
+- User & Org Roles — Assign roles to individual users or entire GitHub orgs.
+- Default Role — Automatic role for any authenticated user.
+- Token Caching — Automatic credential management.
+- CI/CD Support — Use GitHub PATs for automation.
+- Helm Integration — Fully integrated as `envoy-authz` subchart.
+
+### Quick Start
+
+1. Enable in your deployment values:
+
+    Edit `applications/dir/dev/values.yaml`:
+
+    ```yaml
+    apiserver:
+      # Enable the Envoy auth gateway subchart
+      envoyAuthz:
+        enabled: true
+
+      # Configure the subchart
+      envoy-authz:
+        envoy:
+          replicaCount: 1  # Increase for production
+          backend:
+            address: "dir-dir-dev-argoapp-apiserver.dir-dev-dir.svc.cluster.local"
+            port: 8888
+          spiffe:
+            enabled: true
+            trustDomain: example.org
+            className: dir-spire
+
+        authServer:
+          replicaCount: 1  # Increase for production
+
+          # Casbin RBAC Configuration
+          authorization:
+            # Default role for any authenticated GitHub user
+            defaultRole: "reader"
+
+            # Role definitions
+            roles:
+              # Admin role - full access
+              admin:
+                allowedMethods:
+                  - "*"  # Wildcard grants all methods
+                users:
+                  - "github:alice"
+                  - "github:bob"
+                orgs: []
+
+              # Reader role - read-only access
+              reader:
+                allowedMethods:
+                  - "/agntcy.dir.store.v1.StoreService/Pull"
+                  - "/agntcy.dir.search.v1.SearchService/SearchCIDs"
+                  - "/agntcy.dir.routing.v1.RoutingService/List"
+                users: []  # Inherited by defaultRole
+                orgs: []
+
+          # GitHub provider configuration
+          github:
+            enabled: true
+            cacheTTL: 5m
+
+        ingress:
+          enabled: true
+          className: "nginx"
+          host: "dev.gateway.example.org"
+          annotations:
+            # Required for gRPC over HTTPS
+            nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
+            nginx.ingress.kubernetes.io/grpc-backend: "true"
+    ```
+
+2. Deploy GitHub OAuth authentication
+
+    ArgoCD syncs automatically after git push.
+
+3. Authenticate:
+
+    ```bash
+    # Device Flow (recommended - no OAuth App needed)
+    export DIRECTORY_CLIENT_SERVER_ADDRESS="dev.gateway.example.org:443"
+    export DIRECTORY_CLIENT_AUTH_MODE="github"
+
+    # Login - opens browser for GitHub authorization
+    dirctl auth login
+
+    # Use dirctl normally after login
+    dirctl routing list
+    ```
+
+    For CI/CD, use GitHub Personal Access Tokens or Actions' `GITHUB_TOKEN`:
+
+    ```bash
+    export DIRECTORY_CLIENT_AUTH_MODE="github"
+    export DIRECTORY_CLIENT_GITHUB_TOKEN="${GITHUB_PAT}"
+    # Or use GitHub Actions' automatic token:
+    # export DIRECTORY_CLIENT_GITHUB_TOKEN="${GITHUB_TOKEN}"
+
+    # Connect to Envoy gateway
+    export DIRECTORY_CLIENT_SERVER_ADDRESS="dev.gateway.example.org:443"
+
+    dirctl routing list
+    ```
+
+    !!! note
+        For CI/CD, your GitHub user or bot account must be assigned a role (admin or reader) in the RBAC configuration.
+
+### Configuration Options
+
+#### Available API Methods
+
+For a complete list of all 24 Directory API methods with their full gRPC paths and descriptions, see the [envoy-authz values.yaml reference](https://github.com/agntcy/dir/blob/main/install/charts/envoy-authz/values.yaml#L93-L151).
+
+#### User-based roles
+
+Specific users with specific permissions:
+
+```yaml
+authServer:
+  authorization:
+    defaultRole: ""  # No default role - explicit assignment required
+    roles:
+      admin:
+        allowedMethods: ["*"]
+        users:
+          - "github:alice"
+          - "github:bob"
+        orgs: []
+```
+
+#### Organization-based roles
+
+Entire GitHub org gets a role:
+
+```yaml
+authServer:
+  authorization:
+    defaultRole: "reader"  # All authenticated users get reader
+    roles:
+      admin:
+        allowedMethods: ["*"]
+        users: []
+        orgs:
+          - "your-org"  # All org members are admins
+```
+
+#### Combined roles
+
+Users override org roles:
+
+```yaml
+authServer:
+  authorization:
+    defaultRole: "reader"
+    userDenyList:
+      - "github:suspended-user"  # Block specific users
+    roles:
+      admin:
+        allowedMethods: ["*"]
+        users:
+          - "github:alice"  # Individual admin
+        orgs:
+          - "your-org"      # Org-wide admin
+      reader:
+        allowedMethods:
+          - "/agntcy.dir.store.v1.StoreService/Pull"
+          - "/agntcy.dir.search.v1.SearchService/SearchCIDs"
+        users: []
+        orgs: []
+```
+
+#### RBAC Precedence
+
+Deny > User Role > Org Role > Default Role
+
+See [Directory Helm Chart documentation](https://github.com/agntcy/dir/tree/main/install/charts/envoy-authz) for complete API method list and advanced configuration.
diff --git a/docs/dir/directory-testbed.md b/docs/dir/directory-testbed.md
@@ -1,8 +1,8 @@
-# Directory Sandbox
+# Directory Testbed
 
-The Directory Sandbox is a local environment for development and testing. It can be used to test your application with the Directory network. This environment provides a fully functional Directory instance for development, testing, and exploration purposes.
+The Directory Testbed is a local environment for development and testing. It can be used to test your application with the Directory network. This environment provides a fully functional Directory instance for development, testing, and exploration purposes.
 
-There are two ways to use the sandbox:
+There are two ways to use the testbed:
 
-- [Using the public staging environment](./directory-public-staging.md).
-- [Deploying the local sandbox environment](./directory-sandbox-deployment.md).
+- [Deploying the local testbed environment](./directory-testbed-deployment.md)
+- [Using the public staging environment](./directory-public-staging.md)
