For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Delegate authorization decisions to external services like OPA.

Attaches to:

When authorizationAuthorization (AuthZ)The process of determining what actions an authenticated user or service is allowed to perform. Agentgateway supports HTTP authorization, MCP authorization, and external authorization services. decisions need to be made out-of-process, use an external authorization policy. This policy has agentgateway send the request to an external server, such as Open Policy Agent which decides whether the request is allowed or denied. You can configure agentgateway to do this by using the External Authorization gRPC service or by using HTTP requests.

gRPC External Authorization

The Envoy External Authorization gRPC service provides a standardized API to make authorization decisions. Agentgateway is API-compatible with the Envoy External Authorization gRPC service.

When an ExtAuthz server returns header modifications, agentgateway uses insert instead of append for response headers. This ensures headers are properly set rather than potentially duplicated.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
llm:
  policies:
    extAuthz:
      host: localhost:9000
      protocol:
        grpc:
          # Optional: metadata to send to the external authorization service
          # The value is a CEL expression
          metadata:
            dev.agentgateway.jwt: '{"claims": jwt}'
  models:
  - name: "*"
    provider: openAI
    params:
      apiKey: "$OPENAI_API_KEY"

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    extAuthz:
      host: localhost:9000
      protocol:
        grpc:
          # Optional: metadata to send to the external authorization service
          # The value is a CEL expression
          metadata:
            dev.agentgateway.jwt: '{"claims": jwt}'
  targets:
  - name: everything
    stdio:
      cmd: npx
      args: ["@modelcontextprotocol/server-everything"]

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
gateways:
  default:
    port: 3000
routes:
- policies:
    extAuthz:
      host: localhost:9000
      protocol:
        grpc:
          # Optional: metadata to send to the external authorization service
          # The value is a CEL expression
          metadata:
            dev.agentgateway.jwt: '{"claims": jwt}'
  backends:
  - host: localhost:8080

The remaining examples in this section show only the extAuthz policy. Attach each one to a listener, route, or backend as needed.

Cache authorization results

You can cache gRPC external authorization decisions with extAuthz.cache. Caching is supported only for protocol.grpc; HTTP external authorization requests are always sent to the authorization service.

If any cache.key expression fails to evaluate or returns an unsupported value, agentgateway still sends the request to the authorization service, but skips both the cache lookup and the cache write for that request.

Use the following fields to configure the cache:

Example configuration:

extAuthz:
  host: localhost:9000
  protocol:
    grpc:
      metadata:
        dev.agentgateway.jwt: '{"claims": jwt}'
  cache:
    key:
      - request.method
      - request.path
      - request.headers["authorization"]
    ttl: '"5m"'
    maxEntries: 20000

HTTP External Authorization

HTTP External Authorization allows sending plain HTTP requests to an authorization service. If the service returns a 2xx status code, the request is allowed. Otherwise, it is denied.

Example configuration: For the full set of options, see the configuration reference.

extAuthz:
  host: localhost:9000
  protocol:
    includeRequestHeaders:
      # By default, only the Authorization header is included.
      - cookie
    http:
      # We send to /auth/<original request path>.
      path: |
        "/auth" + request.path
      includeResponseHeaders:
      # Pass the user request to the upstream service.
      # This is not required, and is just an example
      - x-auth-request-user

For advanced cases, configure settings for the request to the authorization service, as well as the response from the authorization service. For example, configure redirect to redirect users to a sign-in page, and metadata to extract information from the authorization response to include in logs. Review the following table for more advanced options.

Backend connection policies

You can configure connection policies on the extAuthz field to secure or tune how agentgateway connects to the external authorization service. This includes TLS, authentication, and connection timeouts.

extAuthz:
  host: authz-server:9001
  policies:
    backendTLS:
      root: /certs/ca.pem
      hostname: authz-server
    backendAuth:
      key:
        file: /secrets/api-key
    http:
      requestTimeout: "5s"
  protocol:
    grpc: {}

Backend-level external authorization

You can also attach an extAuthz policy directly to a backend. Backend-level external authorization runs after agentgateway selects the backend, so the policy applies even when a route load-balances or fails over across multiple backends. Attach at the backend level when the authorization service shapes the outgoing request, for example by inserting a token, rather than only deciding whether the incoming request is allowed.

gateways:
  default:
    port: 3000
routes:
- backends:
  - host: localhost:8080
    policies:
      extAuthz:
        host: localhost:9000
        protocol:
          grpc: {}

Conditional execution

To choose between multiple external authorization servers based on the request, use the conditional field. For example, you can send admin paths to a stricter authorization server and route every other request to a standard one. For details, see Conditional policies.

Connection-level external authorization

The extAuthz policy calls the authorization service once for each HTTP request. To call it once for each downstream connection instead, use the networkExtAuthz frontend policy.

Scoping external authorization to a downstream connection is useful in the following cases.

• The gateway carries TCP traffic that has no HTTP requests to authorize.
• The connection is long-lived, and a callout on every request costs more than the decision is worth.

Configure connection-level authorization under the frontendPolicies.networkExtAuthz section. The section takes the same fields as extAuthz, with one restriction.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  networkExtAuthz:
    host: localhost:9000
    protocol:
      http: {}

gateways:
  default:
    port: 3000
routes:
- backends:
  - host: localhost:8080

Because the policy runs before protocol handling, it also applies to a gateway that carries non-HTTP traffic.

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
frontendPolicies:
  networkExtAuthz:
    host: localhost:9000
    protocol:
      http: {}

gateways:
  default:
    port: 3000
    protocol: TCP
tcpRoutes:
- gateways: [default]
  backends:
  - host: localhost:8080

Choose between request-level and connection-level authorization

A gateway can carry an extAuthz policy, a networkExtAuthz policy, or both, so decide which policy a decision belongs in. The following table compares the request-level extAuthz policy that the rest of this page covers with the connection-level networkExtAuthz policy. The two policies differ in where they attach, in what the authorization service sees, and in what a denial affects.

You can set both policies at once. Use networkExtAuthz for a coarse decision that the connection either passes or fails, and extAuthz for a per-request decision that needs the path or the headers.

For a CEL-based decision on the connection that does not call an external service, use network authorization instead.