Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: guide for agentgateway in front of the mesh
HosniBelfeki324fd16b10b1
diff --git a/development/examples/agentgateway/README.md b/development/examples/agentgateway/README.mdnew file mode 100644index 00000000..f9ea367f--- /dev/null+++ b/development/examples/agentgateway/README.md@@ -0,0 +1,52 @@+# agentgateway in front of the mesh++Everything the guide at `site/content/docs/guides/agentgateway.md` walks+through, as one `docker compose` project and a script that checks each step:++- Keycloak 26.4.0 with the realm `mesh` (client `agentmesh`, an audience+ mapper so access tokens carry `aud: agentmesh`, `alice` in group `devs`,+ `bob` in group `ops`) and a second realm, `elsewhere`;+- agentgateway v1.6.0 ([`agentgateway.yaml`](agentgateway.yaml)), which+ validates each caller's access token and exchanges it at a shared+ `agentmesh-node` for a mesh credential of that caller;+- `agentmesh-control-plane` with the realm as its issuer, one router, the+ calculator of [`../calc-mcp`](../calc-mcp) published as `mcp://calc`, and a+ header echo (`echo.py`) behind the same agentgateway policies.++```sh+./run.sh # bring it up, run every case, exit non-zero on a mismatch+./run.sh down # remove the containers and the generated tokens+```++`run.sh` prints one line per case:++```+== Calling mcp://calc through agentgateway+ PASS alice (calc-user through group:devs) 200+ PASS bob (no calc-user), refused by the provider 403++== Refused at agentgateway+ PASS no token 401+ PASS not a token 401+ PASS alice, token for client other-app (audience) 401+ PASS alice, token from realm elsewhere (issuer) 401++== What a backend behind agentgateway receives+ PASS the exchanged credential in x-mesh-authentication present+ PASS the caller's token in authorization absent++== A token through its expiry (60s lifetime in this realm)+ PASS alice, before exp 200+ PASS alice, 20s after exp: accepted by agentgateway, refused at the exchange 400+ PASS alice, 80s after exp: refused by agentgateway 401+ PASS alice, a new token 200+```++The agentmesh images are pinned to the commit the example was tested with.+`AGENTMESH_TAG` selects another published commit or release, and+`AGENTMESH_REGISTRY` another registry.++`.run/` holds the admin, API and bootstrap tokens `run.sh` generates on each+run, and is not committed. The users' passwords in the realm files are for+this example only. Keycloak runs `start-dev` over plain `http` inside the+Compose network; the guide lists what to change for a real deployment.diff --git a/site/content/docs/guides/_index.md b/site/content/docs/guides/_index.mdindex afed5ca6..e518d5b2 100644--- a/site/content/docs/guides/_index.md+++ b/site/content/docs/guides/_index.md@@ -9,7 +9,8 @@ aliases:Step-by-step pages for common tasks: publish a service, connect an agentclient, enroll machines that cannot log in, use Keycloak as the identity-provider, put an agent in an OpenShell sandbox or a Substrate actor on the+provider, put agentgateway in front of the mesh, put an agent in an+OpenShell sandbox or a Substrate actor on themesh, and deploy a control plane onKubernetes, Cloud Run, SkyPilot or a GitHub codespace. Each page assumesthat you have read the [quick start](../getting-started/quickstart/).diff --git a/site/content/docs/guides/agentgateway.md b/site/content/docs/guides/agentgateway.mdnew file mode 100644index 00000000..cb4354ef--- /dev/null+++ b/site/content/docs/guides/agentgateway.md@@ -0,0 +1,204 @@+---+title: "agentgateway in front of the mesh"+linkTitle: "agentgateway"+weight: 3+---++This guide puts [agentgateway](https://agentgateway.dev/) in front of the+mesh, so a gateway that already authenticates your users passes each of them+on with a credential of their own. agentgateway validates the caller's token+from your identity provider, exchanges it at an `agentmesh-node` for a mesh+credential of that caller, and calls the mesh with it. The call never becomes+the gateway's own identity: agentgateway holds no mesh credential, and the+caller's own token does not travel past it.++The whole setup runs on one machine with Docker:+[`development/examples/agentgateway/`](https://github.com/google/agentmesh/tree/main/development/examples/agentgateway)+in the repository has the Compose project, and its `run.sh` runs every step+below and checks each result. It uses Keycloak as the identity provider, as+in [Keycloak as the identity provider](../keycloak/).++## How the pieces fit++```mermaid+flowchart LR+ Client["caller<br/>Keycloak access token"]+ subgraph Docker["one Compose network"]+ AGW["agentgateway<br/>jwtAuth, token exchange"]+ KC["Keycloak<br/>realm mesh"]+ GW["agentmesh-node<br/>/oauth/token, /mesh/"]+ CP["agentmesh-control-plane"]+ R["router"]+ P["agentmesh-node<br/>mcp://calc"]+ end+ Client -- "Authorization: Bearer" --> AGW+ AGW -. "JWKS" .-> KC+ AGW -- "POST /oauth/token" --> GW+ GW -- "POST /token/exchange" --> CP+ AGW -- "X-Mesh-Authentication" --> GW+ GW --> R --> P+```++agentgateway sends the caller's token to the node's+[token endpoint](../../reference/node-api/#token-endpoint-oauthtoken-and-revocation-oauthrevoke),+which exchanges it at the control plane for a credential bound to that+caller. agentgateway then calls the node's `/mesh/` proxy with that+credential, and the node that publishes the service checks it against the+mesh policy.++## Before you start++You need Docker with Compose v2 and bash (Linux, macOS, or Git Bash on+Windows).++```sh+cd development/examples/agentgateway+./run.sh+```++## 1. Keycloak: access tokens for the mesh++An agent or MCP client sends agentgateway an access token. An access token+from this realm carries no `aud` claim unless a mapper adds one, so the+realm's `agentmesh` client has an audience mapper:++```json+{+ "name": "audience",+ "protocolMapper": "oidc-audience-mapper",+ "config": { "included.client.audience": "agentmesh", "access.token.claim": "true" }+}+```++`alice`'s access token then carries `"aud": "agentmesh"` and+`"groups": ["devs"]`, which is what the control plane checks+(`--allowed-audiences agentmesh`) and what the policy binds+(`calc-user` to `group:devs`).++## 2. agentgateway: validate the caller++The route validates the token before anything else, so a request without a+valid token is refused with `401`:++```yaml+policies:+ jwtAuth:+ mode: strict+ issuer: http://keycloak:8080/realms/mesh+ audiences: [agentmesh]+ jwks:+ url: http://keycloak:8080/realms/mesh/protocol/openid-connect/certs+```++After it validates the token, agentgateway removes it from the request, so no+backend receives it.++## 3. agentgateway: exchange the token at the node++The backend's `oauthTokenExchange` sends the validated token to the node's+`/oauth/token` as an RFC 8693 subject token, and places the credential it gets+back in `X-Mesh-Authentication`, the header the node's `/mesh/` proxy reads:++```yaml+backends:+- host: gateway:8080+ policies:+ backendAuth:+ oauthTokenExchange:+ host: gateway:8080+ path: /oauth/token+ subjectToken:+ tokenType: urn:ietf:params:oauth:token-type:jwt+ source:+ expression: jwt.rawToken.unredacted()+ authorizationLocation:+ header:+ name: x-mesh-authentication+ prefix: "Bearer "+```++- `subjectToken.source` reads the token from the result of `jwtAuth`, because+ `jwtAuth` has already removed it from the `Authorization` header.+- There is no `clientAuth`. The node exchanges a JWT subject token without+ client authentication: the control plane verifies the token's issuer and+ audience, and mints a credential bound to that node that carries the+ caller's identity and roles. agentgateway has no identity of its own in+ it.++## 4. Call a service++```sh+curl -X POST http://agentgateway:3000/mesh/<provider-peer-id>/mcp/calc \+ -H "Authorization: Bearer $ACCESS_TOKEN" \+ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example","version":"0"}}}'+```++| Caller | Result |+|---|---|+| `alice`, group `devs` | `200`, the server's `initialize` response |+| `bob`, group `ops` | `403` from the node that publishes `mcp://calc` |+| No token, or not a token | `401` at agentgateway |+| A token for another client | `401` at agentgateway: it has no `aud` claim |+| A token from another realm | `401` at agentgateway: its signing key is not in the realm's JWKS |++## 5. What a backend receives++The example puts a server that answers with the headers it received behind+the same agentgateway policies. For `alice`'s request it gets:++```json+{"host": "echo", "x-mesh-authentication": "Bearer EsUDCtoCCgpleHBpc...", ...}+```++The exchanged mesh credential is there, and there is no `Authorization`+header: `alice`'s Keycloak token went no further than agentgateway.++## 6. When the caller's token expires++| Moment | Result |+|---|---|+| Before `exp` | `200` |+| Up to 60 seconds after `exp` | `400 invalid request` |+| More than 60 seconds after `exp` | `401` at agentgateway |+| A new token | `200` |++agentgateway accepts a token for 60 seconds after its `exp`: that is the+default leeway of the `jsonwebtoken` library it validates tokens with, and+agentgateway v1.6.0 has no setting for it. The control plane allows none, so+in that minute it refuses the exchange and agentgateway answers `400`. A+client that refreshes its token before `exp` never sees this; one that waits+for a `401` to refresh waits up to a minute longer.++## Where each refusal is logged++| Refusal | Logged by | Line |+|---|---|---|+| A missing, malformed, expired or foreign token | agentgateway | `authentication failure: ...` with `reason=JwtAuth` |+| An exchange the control plane refuses | control plane | `Border Crossing` with `"decision": "deny"` |+| A call the caller's credential does not grant | the node that publishes the service | `[Ingress] AuthZ Denied` with the failed check |++## What to change for a real deployment++- Run Keycloak for production: TLS, a database and a fixed hostname+ ([Configuring Keycloak for production](https://www.keycloak.org/server/configuration-production)).+ Serve the control plane over `https` and drop `--insecure-control-plane`+ from the router and the nodes.+- Put agentgateway and the node it exchanges at on the same trusted host or+ network, and give the token exchange `policies.backendTLS` when the node is+ served over TLS.+- The example gets tokens with the password grant so it runs unattended. Your+ agents and MCP clients get theirs from their own login flow.+- The example's control plane runs with `--auto-approve-enrollment` so the+ router and the two nodes enroll with the bootstrap tokens the script mints.+ Without it, an administrator approves each bootstrap enrollment+ ([Headless enrollment](../headless-enrollment/#3-approve)).++## Cleaning up++```sh+./run.sh down+```++This stops every container and deletes the tokens the script generated+under `.run/`.