HTTP

Bring your own HTTP-based external authorizationExternal AuthorizationDelegate authorization decisions to an external service via an Envoy extension. service to protect requests that go through your Gateway.

This guide covers HTTP-based external authorization services. For gRPC-based services, see the gRPC guide.

About external auth

Kgateway lets you integrate your own external authorization service to your Gateway, based on the Envoy external authorization filter.

When using an HTTP authorization service, kgateway forwards only a minimal set of request headers to the authorization service by default, including Host, Method, Path, Content-Length, and Authorization. Use the headersToForward field to forward additional headers such as cookies or custom auth headers.

    sequenceDiagram
    participant Client
    participant Gateway
    participant Ext Auth
    participant Backend

    Client->>Gateway: 1. HTTP Request
    Gateway->>Ext Auth: 2. Authorization Request (HTTP)
    Ext Auth-->>Gateway: 3. Authorization Decision
    
    alt Authorized
        Gateway->>Backend: 4. Forward Request
        Backend-->>Gateway: Response
        Gateway-->>Client: Response
    else Not Authorized
        Gateway-->>Client: 5. 403 Forbidden
    end

The Client sends a request to the Gateway.
The Gateway forwards the request to the Ext Auth service over HTTP.
The Ext Auth service makes a decision as to whether the request is authorized, based on headers, parameters, or other credentials.
If authorized, the Gateway forwards the request to the Backend app, which then sends back a response to the Client through the Gateway.
If not authorized, the Gateway rejects the request and by default returns a 403 Forbidden response to the Client.

Before you begin

Follow the Get started guide to install kgateway.
Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

Get the external address of the gateway and save it in an environment variable.

export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

Bring your own HTTP external authorization service

Deploy your own HTTP-based external authorization service as a backend service that is accessible to your gateway proxy. Then, configure a GatewayExtension to point to the external auth server by using the httpService field.

Note that in the following example, resources are created in the same namespace to simplify the setup. To create resources in different namespaces, set up a Kubernetes ReferenceGrant from the GatewayExtension to the Services that back the external auth service.

Deploy your external authorization service. The following example uses the Istio external authorization service for quick testing purposes. This image exposes both a gRPC server on port 9000 and an HTTP server on port 8000. The HTTP server allows requests with the x-ext-authz: allow header.

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: kgateway-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: 8000
EOF

Create a Service for the Deployment that exposes the HTTP port.

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  namespace: kgateway-system
  name: ext-authz
  labels:
    app: ext-authz
spec:
  ports:
  - port: 4444
    targetPort: 8000
    protocol: TCP
  selector:
    app: ext-authz
EOF

Create a GatewayExtension resource that points to your HTTP authorization service by using the httpService field. Unlike gRPC, HTTP authorization services receive only a minimal set of client request headers by default, including the Host, Method, Path, Content-Length, and Authorization headers. Use the headersToForward field to specify any additional headers the auth service needs to make its decision.

kubectl apply -f - <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: GatewayExtension
metadata:
  namespace: kgateway-system
  name: basic-ext-auth
  labels:
    app: ext-authz
spec:
  type: ExtAuth
  extAuth:
    headersToForward:
      - x-ext-authz
    httpService:
      backendRef:
        name: ext-authz
        port: 4444
EOF

The httpService field supports additional optional configuration:

Field	Description
`pathPrefix`	Prefix prepended to the authorization request path. Use this field when your auth server expects requests at a specific path, such as `/check` or `/verify`.
`requestTimeout`	Timeout for the authorization request. Defaults to 2 seconds.
`authorizationRequest.headersToAdd`	Additional headers to add to every authorization request that is sent to the auth service.
`authorizationResponse.headersToBackend`	Headers from the authorization response to forward to the upstream service when the request is allowed.
`headersToForward`	Client request headers to forward to the authorization service. HTTP services receive only `Host`, `Method`, `Path`, `Content-Length`, and `Authorization` by default.

Create external auth policy

You can apply a policy at two levels: the Gateway level or the HTTPRoute level. If you apply the policy at both levels, the request must pass both policies to be authorized.

Send a test request to the httpbin sample app. Verify that you get back a 200 HTTP response code and that no authorization is required.
curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"
curl -i localhost:8080/headers -H "host: www.example.com"
Example output:
```
HTTP/1.1 200 OK
...
```

Create a TrafficPolicy that references the GatewayExtension resource that you created earlier to apply external authorization at the Gateway level.

kubectl apply -f - <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  namespace: kgateway-system
  name: gateway-ext-auth-policy
  labels:
    app: ext-authz
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
  extAuth:
    extensionRef: 
      name: basic-ext-auth
EOF

Repeat the request to the httpbin sample app and verify that the request is denied with a 403 HTTP response.

curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"

Example output:

HTTP/1.1 403 Forbidden
...
denied by ext_authz for not found header `x-ext-authz: allow` in the request

Send another request with the x-ext-authz: allow header. The Istio external authorization service is configured to allow requests with this header. Verify that you get back a 200 HTTP response code.
curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080" -H "x-ext-authz: allow"
curl -i localhost:8080/headers -H "host: www.example.com" -H "x-ext-authz: allow"
Example output:
```
HTTP/1.1 200 OK
...
```

Create another TrafficPolicy to disable external authorization for a particular HTTPRoute. This way, requests that do not require external authorization, such as health checks, are allowed through while the external authorization service is still in place for requests to other routes on the Gateway.

kubectl apply -f - <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: TrafficPolicy
metadata:
  namespace: httpbin
  name: route-ext-auth-policy
  labels:
    app: ext-authz
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: httpbin
  extAuth:
    disable: {}
EOF

Send a request to the httpbin app without the x-ext-authz header and verify that you now get back a 200 HTTP response.
curl -i http://$INGRESS_GW_ADDRESS:8080/headers -H "host: www.example.com:8080"
curl -i localhost:8080/headers -H "host: www.example.com"
Example output:
```
HTTP/1.1 200 OK
...
```

Cleanup

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

Delete the TrafficPolicy for the Gateway and HTTPRoute.
```
kubectl delete TrafficPolicy -A -l app=ext-authz
```

Delete the sample external authorization service and GatewayExtension resource.

kubectl delete gatewayextension,deployment,service -n kgateway-system -l app=ext-authz

gRPC

Was this page helpful?