Getting started: the lab
Envoy calls visado through ext_authz. visado asks OPA with the AuthZEN plugin, and allowed requests reach an echo server that returns the headers it received. SPIRE v1.16.0 issues the workloads’ WITs, X.509-SVIDs and JWT-SVIDs.
Envoy listens on two ports: 10000 (plain HTTP) and 10443 (mTLS).
docker compose up -d --build./demo.shSPIRE v1.16.0 issues WIT-SVIDs as an experimental feature, turned on with experimental { enable_wit_svids = true } in spire/server.conf and spire/agent.conf. The server sets the WIT iss to https://spire.td.example (wit_issuer).
spire-setupregistersspiffe://td.example/agent-a,agent-b,agent-zandgateway, and writes a join token for the agent. It also writes the X.509 CA (x509-bundle.pem) and the bundle in SPIFFE format (spiffe-bundle.json) for visado’s[mtls]and[jwt_svid]. The SPIFFE format marks each key’suse; the JWT bundle from the Workload API leavesuseout, and visado takes only keys markedjwt-svid.- The agent attests with the join token. Each lab workload is a Unix user in the agent container (uid 1001, 1002, 1003), and the
unixworkload attestor tells them apart by uid. wit-configruns before visado. It fetches thetd.exampleWIT bundle (a JWKS) from the Workload API and writes it to a shared volume.visado.tomltrusts it withjwks_fileand expects the SPIREiss. visado reads the bundle at startup, so restart it after SPIRE rotates the WIT key.gateway-svidruns before Envoy. It fetches thegatewayX.509-SVID (with the DNS nametools.td.example), its key and the X.509 bundle from the Workload API. Envoy serves the SVID on the mTLS listener and validates client certificates against the bundle. Envoy reads the files once: the SVID expires after an hour and the CA after a day, so restart the lab after that. A deployment would have Envoy fetch them over SDS.demo.shrunsspire-agent api fetch witas each user and gets the WIT-SVID and its private key. The agent generates the key; the WIT binds it incnf.jwk(ES256). The demo signs each WPT, the AAT holder proofs and the HTTP message signatures with that key. It also fetches agent-a’s X.509-SVID (fetch x509) for mTLS and two JWT-SVIDs (fetch jwt), one for visado’s audiencehttp://tools.td.exampleand one for another.
SPIRE’s private key JWK and its bundle keys carry no alg. The demo takes it from the WIT’s cnf.jwk; visado gives a P-256 bundle key ES256, the only algorithm that key type allows.
User tokens, the DPoP-bound access token and the AAT root are still signed with the fixed demo keys in ../local/keys. The DPoP proof key is a fixed testkit key.
Scenarios
Section titled “Scenarios”demo.sh checks each response status and, where the table names one, visado’s error code:
| Scenario | Expected |
|---|---|
| No credentials | 401 |
Encoded / in the path |
400 from Envoy (path_with_escaped_slashes_action: REJECT_REQUEST) |
agent-a reads tickets for bob (tickets.read) |
200; the upstream sees Txn-Token and no user token |
| agent-b forwards bob’s transaction to the admin API | 403 from the PDP: the token still carries tickets.read |
| agent-b forwards bob’s transaction to tickets | 200 with the same Txn-Token |
A workload not in internal_callers forwards the transaction |
403 |
A user token without roles.write on the admin API |
403 |
carol with roles.write through agent-a |
200 |
AAT: agent-b reads /data/report.pdf, which agent-a delegated to it |
200 |
AAT: agent-b reads /etc/passwd |
403, outside the delegated constraint |
AAT: agent-b calls delete_file, which agent-a kept |
403 |
| AAT: agent-z presents agent-b’s chain | 403, the proof is not signed by the holder |
| agent-a POSTs a ticket with an HTTP message signature instead of a WPT | 200 |
| The same signed request again | 400 httpsig.invalid: the nonce was seen |
A signed request whose body differs from the covered Content-Digest |
400 httpsig.invalid |
| mTLS: agent-a’s X.509-SVID | 200 |
mTLS: agent-a’s X.509-SVID with an X-User-Token |
401 credential.unbound_user_token: nothing binds the token to the certificate |
| mTLS: a certificate for agent-a’s SPIFFE ID from another CA | No response: Envoy refuses the handshake (curl reports 000) |
agent-a’s JWT-SVID as Authorization: Bearer |
200 |
| A JWT-SVID for another audience | 401 jwt_svid.invalid |
| bob’s access token, DPoP-bound, with its proof | 200 |
The same token as Bearer, without the proof |
401 token.dpop_bound |
The AAT chains are bound to the keys SPIRE issued: agent-a’s WIT key holds the root and signs the delegation to agent-b’s WIT key.
The signed requests need the body: the ext_authz filters set with_request_body with pack_as_bytes: true. The mTLS listener’s filter sets include_peer_certificate: true. visado’s gRPC port listens only on its address on authz, an internal network that only Envoy shares, so visado.toml can set grpc_reachable_only_by_proxy = true: no other container can send a check request with someone else’s certificate.
Envoy also normalizes %2e%2e and // before visado sees the path; visado rejects any that still arrive.
Each decision is also a visado.authorize span in Jaeger at http://127.0.0.1:16686.
The chain view at http://127.0.0.1:8080/chain draws each recent decision: principal, delegation hops (verified or declared), caller, PDP decision and the deny reason. It shows caller and principal identities, so the port is published to the host’s loopback address only.
The policy is in policy/visado.rego: /admin/ needs roles.write, everything else tickets.read.
The demo keys are public. Do not reuse them.
© 2026 The visado Authors. Licensed under Apache-2.0.
Third-party logos are trademarks of their respective owners and are used to show compatibility; their use does not imply endorsement.