Skip to content

Agent Mesh

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.md
index 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()` and
diff --git a/site/content/docs/contributing/security-architecture.md b/site/content/docs/contributing/security-architecture.md
index 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` on
MCP `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 RFC
8693 `/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.md
index 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` acts
as their external Policy Decision Point and Token Service over three standard
interfaces:
-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`):** the
body-aware counterpart to `ext_authz`. Because MCP tool names travel inside
the JSON-RPC request body (`params.name`), `ext_proc` inspects the buffered
diff --git a/site/content/docs/preview/sandboxed-agents.md b/site/content/docs/preview/sandboxed-agents.md
index 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 Policy
Decision 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 directly
at `http://sam-node:8080/oauth/token` to exchange workload JWTs or narrow
diff --git a/site/content/docs/reference/node-api.md b/site/content/docs/reference/node-api.md
index 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 on
the 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`**: the
body-aware gateway processor. It inspects JSON-RPC bodies on MCP `tools/call`
requests to enforce `operation.allowed_tools` in `TaskAuthorizationRule`