BYO ext auth service

Bring your own external authorization service to protect requests that go through your Gateway.

About external auth

Agentgateway lets you integrate your own external authorization service to your Gateway. Then, this external authorization service makes authorization decisions for requests that go through the Gateway, as shown in the following diagram.

Review the following diagram to understand the flow of a request:

    sequenceDiagram
    participant C as Client / Agent
    participant AGW as Agentgateway Proxy
    participant BYO as Your Ext Auth Service<br/>(gRPC)
    participant Backend as Backend<br/>(LLM / MCP / Agent / HTTP)

    C->>AGW: Request to protected route

    AGW->>BYO: gRPC Authorization Request<br/>(headers, path, method)

    BYO->>BYO: Custom authorization logic<br/>(check headers, tokens,<br/>database lookups, etc.)

    alt Authorized
        BYO-->>AGW: ALLOW<br/>(optional: inject headers)
        AGW->>Backend: Forward request
        Backend-->>AGW: Response
        AGW-->>C: 200 OK + Response
    else Not Authorized
        BYO-->>AGW: DENY<br/>(status code, message)
        AGW-->>C: 403 Forbidden<br/>"denied by ext_authz"
    end

Before you begin

Set up an agentgateway proxy.
Set up access to the OpenAI LLM provider.

Note that this guide assumes that you want to apply the policy to the OpenAI LLM provider. You can use other LLM providers or apply external auth to an MCP server, agents, and Kubernetes services. Make sure to adjust these steps to apply to your AgentgatewayBackend type or Kubernetes service.

Deploy your own external authorization service

Deploy your own external authorization service as a backend service that is accessible to your agentgateway proxy.

Keep in mind that your external authorization service must conform to the Envoy external auth proto. The external authorization service also configures the conditions for authorizing a request, such as the inclusion of a certain header or other credentials.

Deploy your external authorization service. The following example uses the Istio external authorization service for quick testing purposes. This service is configured to allow requests with the x-ext-authz: allow header.

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: agentgateway-system
  name: ext-authz
  labels:
    app: ext-authz
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ext-authz
  template:
    metadata:
      labels:
        app: ext-authz
        app.kubernetes.io/name: ext-authz
    spec:
      containers:
      - image: gcr.io/istio-testing/ext-authz:1.25-dev
        name: ext-authz
        ports:
        - containerPort: 9000
EOF

Create a Service for the Deployment that your proxy can access.

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  namespace: agentgateway-system
  name: ext-authz
  labels:
    app: ext-authz
spec:
  ports:
  - port: 4444
    targetPort: 9000
    protocol: TCP
    appProtocol: kubernetes.io/h2c
  selector:
    app: ext-authz
EOF

Create external auth policy

You can attach an external authorization policy to a Gateway, HTTPRoute, or backend (an AgentgatewayBackend or a Kubernetes Service). If you attach policies at multiple levels, the request must pass each one to be authorized.

Gateway and HTTPRoute targets use the traffic.extAuth section so that authorization runs before the proxy selects a backend. Backend targets use the backend.extAuth section so that authorization runs after backend selection, which is useful when the authorization service shapes the outgoing request, for example by inserting a token, or when a route load-balances or fails over across multiple backends.

Send a test request to the OpenAI backend. Verify that you get back a 200 HTTP response code and that no authorization is required.

curl -v "${INGRESS_GW_ADDRESS}:8080/openai" -H content-type:application/json -d '{
 "model": "gpt-3.5-turbo",
 "messages": [
   {
     "role": "system",
     "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."
   },
   {
     "role": "user",
     "content": "Write 5 sentences."
   }
 ]
}'

curl -v "localhost:8080/openai" -H content-type:application/json -d '{
 "model": "gpt-3.5-turbo",
 "messages": [
   {
     "role": "system",
     "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."
   },
   {
     "role": "user",
     "content": "Write 5 sentences."
   }
 ]
}'

Example output:

HTTP/1.1 200 OK
...

Create an AgentgatewayPolicy that references the external authorization service. Choose the tab for the target you want to attach the policy to. The Gateway and HTTPRoute tabs apply external authorization before backend selection. The AgentgatewayBackend tab applies it after backend selection.

kubectl apply -f - <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  namespace: agentgateway-system
  name: gateway-ext-auth-policy
  labels:
    app: ext-authz
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: agentgateway-proxy
  traffic:
    extAuth:
      backendRef:
        name: ext-authz
        namespace: agentgateway-system
        port: 4444
      grpc: {}
EOF

kubectl apply -f - <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  namespace: agentgateway-system
  name: route-ext-auth-policy
  labels:
    app: ext-authz
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: openai
  traffic:
    extAuth:
      backendRef:
        name: ext-authz
        namespace: agentgateway-system
        port: 4444
      grpc: {}
EOF

Backend-level policies can also target a Kubernetes Service. To target a Service, set kind: Service and group: "" in targetRefs, and use the same backend.extAuth configuration shown in the AgentgatewayBackend tab.

kubectl apply -f - <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  namespace: agentgateway-system
  name: backend-ext-auth-policy
  labels:
    app: ext-authz
spec:
  targetRefs:
  - group: agentgateway.dev
    kind: AgentgatewayBackend
    name: openai
  backend:
    extAuth:
      backendRef:
        name: ext-authz
        port: 4444
      grpc: {}
EOF

Repeat your request to the OpenAI backend and verify that the request is denied.

curl -v "${INGRESS_GW_ADDRESS}:8080/openai" -H content-type:application/json -d '{
 "model": "gpt-3.5-turbo",
 "messages": [
   {
     "role": "system",
     "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."
   },
   {
     "role": "user",
     "content": "Write 5 sentences."
   }
 ]
}'

curl -v "localhost:8080/openai" -H content-type:application/json -d '{
 "model": "gpt-3.5-turbo",
 "messages": [
   {
     "role": "system",
     "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."
   },
   {
     "role": "user",
     "content": "Write 5 sentences."
   }
 ]
}'

Example output: Note the 403 Forbidden response, along with the special x-ext-authz* headers that the Istio external authorization service adds to the request to explain the decision.

* upload completely sent off: 268 bytes
< HTTP/1.1 403 Forbidden
< content-type: text/plain
< content-length: 29
< 
* Connection #0 to host localhost left intact
denied by ext_authz for not found header `x-ext-authz: allow` in the request%

Send another request, this time with the x-ext-authz: allow header. The Istio external authorization service is configured to allow requests with this header. Therefore, the request succeeds.

curl -v "${INGRESS_GW_ADDRESS}:8080/openai" -H content-type:application/json \
-H "x-ext-authz: allow" \
-H "x-ai-api-key:N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy" \
-d '{
 "model": "gpt-3.5-turbo",
 "messages": [
   {
     "role": "system",
     "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."
   },
   {
     "role": "user",
     "content": "Write 5 sentences."
   }
 ]
}'

curl -v "localhost:8080/openai" -H content-type:application/json \
 -H "x-ext-authz: allow" \
 -H "x-ai-api-key:N2YwMDIxZTEtNGUzNS1jNzgzLTRkYjAtYjE2YzRkZGVmNjcy" \
 -d '{
  "model": "gpt-3.5-turbo",
  "messages": [
   {
     "role": "system",
     "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."
   },
   {
     "role": "user",
     "content": "Write 5 sentences."
   }
 ]
}'

Cleanup

You can remove the resources that you created in this guide.

kubectl delete AgentgatewayPolicy -n agentgateway-system
kubectl delete deployment ext-authz -n agentgateway-system
kubectl delete service ext-authz -n agentgateway-system

Was this page helpful?