Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: describe the ext_authz credential path as implemented
Antonio Ojeaa539e3247796
diff --git a/site/content/docs/concepts/authorization.md b/site/content/docs/concepts/authorization.mdindex 544fd1e9..1f7302fa 100644--- a/site/content/docs/concepts/authorization.md+++ b/site/content/docs/concepts/authorization.md@@ -202,8 +202,8 @@ permissions:- On `/mcp` and `/v1/*` (or via RFC 8693 `POST /oauth/token` and Envoy`ext_authz` / `ext_proc`), the caller presents its own platform JWT (OIDC ID- token, Kubernetes projected SA JWT, SPIFFE JWT-SVID, or Istio mTLS XFCC- identity) or a task-attenuated Biscuit.+ token, Kubernetes projected SA JWT, or SPIFFE JWT-SVID) or a task-attenuated+ Biscuit.- `sam-node` exchanges platform JWTs via `POST /token/exchange` into a**Delegated Session Biscuit** carrying the caller's own `user()`, `email()`,`group()`, and `role()` facts, bound to the node via `client_peer_id()` anddiff --git a/site/content/docs/contributing/security-architecture.md b/site/content/docs/contributing/security-architecture.mdindex 9ad1ff69..d0c905a6 100644--- a/site/content/docs/contributing/security-architecture.md+++ b/site/content/docs/contributing/security-architecture.md@@ -79,7 +79,7 @@ SAM separates caller attestation from task authorization:| Layer | Question answered | Primitive | Role in SAM || :--- | :--- | :--- | :--- |-| **1. Workload / Subject & Channel Attestation** | *"Which workload or user initiated this request, and through which node is it travelling?"* | **OIDC ID tokens**, **Kubernetes projected SA JWTs**, **GCE/Cloud Run identity tokens**, **SPIFFE JWT-SVIDs**, or **Istio XFCC**. | Verified at `POST /register` (node enrollment) or `POST /token/exchange` (caller delegation) to mint a Biscuit bound to the transport channel (`client_peer_id`, `actor_node`). |+| **1. Workload / Subject & Channel Attestation** | *"Which workload or user initiated this request, and through which node is it travelling?"* | **OIDC ID tokens**, **Kubernetes projected SA JWTs**, **GCE/Cloud Run identity tokens**, or **SPIFFE JWT-SVIDs**. | Verified at `POST /register` (node enrollment) or `POST /token/exchange` (caller delegation) to mint a Biscuit bound to the transport channel (`client_peer_id`, `actor_node`). || **2. Task / Session Authorization (TAR)** | *"What subset of standing permissions may this specific task or sub-agent hop exercise right now?"* | **SAM Task Biscuit** (Block 0 Authority + appended `tar_block` blocks carrying `api.TaskAuthorizationRule`). | Attenuated offline across hops, enforced at every SAM Policy Enforcement Point (PEP), and translated into downscoped upstream cloud credentials by `CloudTokenExchanger` at egress. |---@@ -366,11 +366,13 @@ as a standard OIDC issuer:1. Envoy `ext_authz` (`/ext_authz` and`/envoy.service.auth.v3.Authorization/Check`) evaluates standing Datalog- policy and `tar_block` rules on incoming Envoy `CheckRequest` calls, accepts- verified SPIFFE IDs from `AttributeContext.Source.Principal` or- `X-Forwarded-Client-Cert` (XFCC) on trusted proxy listeners, and injects- brokered upstream credentials (`Authorization: Bearer ...`,- `X-Sam-Principal`, `X-Sam-Task-Id`).+ policy and `tar_block` rules on incoming Envoy `CheckRequest` calls. The+ caller presents a Biscuit (`X-Sam-Biscuit`, or a Bearer value in+ `X-Sam-Authentication` or `Authorization`) or a platform JWT, which+ `sam-node` exchanges at the control plane into a delegated Biscuit. On `OK`+ it returns `X-Sam-Biscuit`, `X-Sam-Principal`, `X-Sam-Roles`,+ `X-Sam-Task-Id` and, for `egress://` targets with a credential broker, the+ brokered upstream `Authorization` header.2. Envoy `ext_proc` (`/envoy.service.ext_proc.v3.ExternalProcessor/Process`)inspects buffered JSON-RPC request bodies so `operation.allowed_tools` onMCP `tools/call` is enforced before injecting the upstream credential.@@ -463,8 +465,8 @@ projected service account JWT) to authenticate to a local or cluster#### Blueprint 3: `agentgateway` / Istio service mesh-Workloads authenticate to `agentgateway` or Istio via mTLS SPIFFE XFCC or a-Task Biscuit; the gateway calls `sam-node` over `ext_authz`, `ext_proc`, or RFC+Workloads authenticate to `agentgateway` or Istio with a platform JWT (for+example a SPIFFE JWT-SVID) or a Task Biscuit; the gateway calls `sam-node` over `ext_authz`, `ext_proc`, or RFC8693 `/oauth/token` for local policy enforcement and routes cross-cluster MCP,A2A, and cloud egress calls through `sam-node`.diff --git a/site/content/docs/preview/agent-architecture.md b/site/content/docs/preview/agent-architecture.mdindex 42a785f0..e909adee 100644--- a/site/content/docs/preview/agent-architecture.md+++ b/site/content/docs/preview/agent-architecture.md@@ -56,7 +56,7 @@ SAM separates the two layers:| Layer | Question answered | Primitive ||---|---|---|-| **Subject & channel attestation** | *Which user or workload initiated this request, and through which node?* | OIDC ID token, Kubernetes projected SA JWT, SPIFFE JWT-SVID, or Istio mTLS identity (`source.principal` / XFCC), exchanged into a Biscuit bound to the channel (`client_peer_id`, `actor_node`). |+| **Subject & channel attestation** | *Which user or workload initiated this request, and through which node?* | OIDC ID token, Kubernetes projected SA JWT, or SPIFFE JWT-SVID, exchanged into a Biscuit bound to the channel (`client_peer_id`, `actor_node`). || **Task authorization (TAR)** | *What subset of standing permissions may this task or sub-agent hop exercise?* | Appended `tar_block` blocks carrying `api.TaskAuthorizationRule`, intersected across hops and translated into downscoped cloud credentials at egress. |## Separation of responsibilities@@ -158,12 +158,12 @@ Where a cluster already runs Envoy, Istio, or `agentgateway`, `sam-node` actsas their external Policy Decision Point and Token Service over three standardinterfaces:-1. **Envoy `ext_authz` (`--ext-authz-addr`):** evaluates standing policy and- `tar_block` chains on incoming `CheckRequest` calls, accepts verified- SPIFFE principals from `AttributeContext.Source.Principal` or- `X-Forwarded-Client-Cert` (XFCC) on trusted proxy listeners, and injects- brokered upstream credentials (`Authorization: Bearer ...`,- `X-Sam-Principal`, `X-Sam-Task-Id`).+1. **Envoy `ext_authz` (on the local API listeners):** evaluates standing+ policy and `tar_block` chains on incoming `CheckRequest` calls. The caller+ presents a Biscuit, or a platform JWT that `sam-node` exchanges at the+ control plane into a delegated Biscuit. On `OK` it returns `X-Sam-Biscuit`,+ `X-Sam-Principal`, `X-Sam-Roles`, `X-Sam-Task-Id` and, for `egress://`+ targets with a credential broker, the brokered `Authorization` header.2. **Envoy `ext_proc` (`envoy.service.ext_proc.v3.ExternalProcessor`):** thebody-aware counterpart to `ext_authz`. Because MCP tool names travel insidethe JSON-RPC request body (`params.name`), `ext_proc` inspects the buffereddiff --git a/site/content/docs/preview/sandboxed-agents.md b/site/content/docs/preview/sandboxed-agents.mdindex ca8ad265..1bd3f34e 100644--- a/site/content/docs/preview/sandboxed-agents.md+++ b/site/content/docs/preview/sandboxed-agents.md@@ -127,15 +127,14 @@ In clusters that already route agent traffic through **`agentgateway`**,continues to flow through those proxies while `sam-node` serves as the PolicyDecision Point and Token Service:-- **Envoy `ext_authz` (`--ext-authz-addr`) and `ext_proc`:**+- **Envoy `ext_authz` and `ext_proc` (on the local API listeners):**Istio `AuthorizationPolicy (action: CUSTOM)` or `agentgateway` calls- `sam-node`. When no Bearer token is present on a trusted proxy listener,- `sam-node` reads the caller's verified SPIFFE ID from- `AttributeContext.Source.Principal` or `X-Forwarded-Client-Cert` (XFCC),- exchanges it into a Delegated Session Biscuit, evaluates the standing Datalog- policy and any `TaskAuthorizationRule` chain (including MCP tool names in- JSON-RPC bodies via `ext_proc`), and injects the upstream credential into- `Authorization` before the gateway forwards the request.+ `sam-node` with the caller's Biscuit, or with a platform JWT that+ `sam-node` exchanges at the control plane into a delegated Biscuit.+ `sam-node` evaluates the standing Datalog policy and any+ `TaskAuthorizationRule` chain (including MCP tool names in JSON-RPC bodies+ via `ext_proc`), and for `egress://` targets injects the brokered upstream+ credential into `Authorization` before the gateway forwards the request.- **RFC 8693 backend token exchange (`POST /oauth/token`):**`agentgateway`'s built-in RFC 8693 token exchange policy can point directlyat `http://sam-node:8080/oauth/token` to exchange workload JWTs or narrowdiff --git a/site/content/docs/reference/node-api.md b/site/content/docs/reference/node-api.mdindex d41355e6..6e6e7911 100644--- a/site/content/docs/reference/node-api.md+++ b/site/content/docs/reference/node-api.md@@ -8,9 +8,9 @@ aliases:The local API that `sam-node run` serves to agents, gateways, and scripts onthe same machine or cluster. It is available on TCP (`--bind-addr`, default-`127.0.0.1:8080`), on a Unix socket (`--socket-path`, default-`<data-dir>/sam.sock`), and optionally on a dedicated Envoy `ext_authz` /-`ext_proc` listener (`--ext-authz-addr`).+`127.0.0.1:8080`) and on a Unix socket (`--socket-path`, default+`<data-dir>/sam.sock`). The Envoy `ext_authz` and `ext_proc` endpoints are+served on the same listeners.## Authentication@@ -85,17 +85,21 @@ revocation ID in the node's local revocation cache until the token expires.## Envoy `ext_authz` and `ext_proc` gateway integration-When `--ext-authz-addr` (`host:port` or `unix:/path`) is set (or on the local-API listener), `sam-node` serves:+On the local API listeners, `sam-node` serves:- **Envoy HTTP `ext_authz` (`/ext_authz`, `/ext_authz/*`)** and **gRPC`envoy.service.auth.v3.Authorization/Check`**: evaluates standing Datalog- policy and any `tar_block` chain on the request. On a trusted `--ext-authz-addr`- listener, if no Bearer token is present, `sam-node` extracts the caller's- verified SPIFFE principal from `AttributeContext.Source.Principal` or- `X-Forwarded-Client-Cert` (XFCC) and exchanges it into a Delegated Session- Biscuit. On `OK`, it injects `Authorization: Bearer <upstream-token>`,- `X-Sam-Principal`, and `X-Sam-Task-Id`.+ policy and any `tar_block` chain on the request. The credential is read+ from `X-Sam-Biscuit`, or from a Bearer value in `X-Sam-Authentication` or+ `Authorization`. A Bearer value that is a platform JWT is exchanged at the+ control plane (`POST /token/exchange`) into a delegated Biscuit before+ evaluation; a request with no credential is refused with `401`. The target+ service is taken from `X-Sam-Target-Service` or from the `/sam/<peer>/<type>/<name>`+ request path. On `OK`, the response carries `X-Sam-Biscuit`,+ `X-Sam-Principal`, `X-Sam-Roles`, and, when the token is task-attenuated,+ `X-Sam-Task` (the last `TaskAuthorizationRule` as protojson) and+ `X-Sam-Task-Id`. For an `egress://` target with a configured credential+ broker it also carries the brokered `Authorization` header for the upstream.- **Envoy gRPC `envoy.service.ext_proc.v3.ExternalProcessor/Process`**: thebody-aware gateway processor. It inspects JSON-RPC bodies on MCP `tools/call`requests to enforce `operation.allowed_tools` in `TaskAuthorizationRule`