HTTP

Delegate authentication to your own HTTP auth server.

HTTP passthrough authentication lets you delegate authorization decisions to your own HTTP auth server. Instead of implementing the Envoy gRPC external auth protocol, your server receives forwarded request headers over plain HTTP and responds with an allow or deny decision. This approach is useful when you have an existing HTTP auth service that you want to reuse without modifying it.

About HTTP passthrough auth

The Solo external auth service forwards each incoming request to your HTTP auth server. Your server inspects the forwarded headers and returns an HTTP response that the external auth service interprets as an allow or deny decision.

    sequenceDiagram
    participant C as Client
    participant AGW as Gateway
    participant EAS as ExtAuth Service
    participant Auth as HTTP Auth Server
    participant Backend as Backend

    C->>AGW: HTTP Request
    AGW->>EAS: Forward for auth decision
    EAS->>Auth: Forward selected headers (HTTP POST)

    alt Authorized
        Auth-->>EAS: 200 OK
        EAS-->>AGW: Allow
        AGW->>Backend: Forward request
        Backend-->>AGW: Response
        AGW-->>C: Response
    else Not Authorized
        Auth-->>EAS: 401 Unauthorized
        EAS-->>AGW: Deny
        AGW-->>C: 401 Unauthorized
    end

Before you begin

Follow the Get started guide to install Solo Enterprise for 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

kubectl port-forward deployment/http -n kgateway-system 8080:8080

Deploy your HTTP auth server

Deploy the example HTTP auth server. This server allows requests that include the authorization: authorize me header and denies all others.

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-http-auth-server
  namespace: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: example-http-auth-server
  template:
    metadata:
      labels:
        app: example-http-auth-server
    spec:
      containers:
      - name: http-extauth
        image: gcr.io/solo-public/passthrough-http-service-example
        imagePullPolicy: IfNotPresent
        ports:
        - containerPort: 9001
---
apiVersion: v1
kind: Service
metadata:
  name: example-http-auth-service
  namespace: httpbin
  labels:
    app: example-http-auth-server
spec:
  ports:
  - port: 9001
    protocol: TCP
  selector:
    app: example-http-auth-server
EOF

Verify that the auth server pod is running.

kubectl get pods -n httpbin -l app=example-http-auth-server

Set up HTTP passthrough auth

Create an AuthConfig resource that configures the external auth service to forward requests to your HTTP auth server. The example forwards the authorization header to the auth server at the /auth path.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
        connectionTimeout: 5s
        request:
          allowedHeaders:
          - authorization
EOF

Field	Description
`url`	The full URL of your HTTP auth server, including the path.
`connectionTimeout`	The maximum time to wait for the overall auth request to complete.
`request.allowedHeaders`	Headers from the original client request to forward to the auth server.

Create an EnterpriseKgatewayTrafficPolicy resource that applies the AuthConfig to all routes on the Gateway.

kubectl apply -f - <<EOF
apiVersion: enterprisekgateway.solo.io/v1alpha1
kind: EnterpriseKgatewayTrafficPolicy
metadata:
  name: http-passthrough-auth
  namespace: kgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
  entExtAuth:
    authConfigRef:
      name: http-passthrough-auth
      namespace: httpbin
EOF

Send a request without the required authorization header. Verify that the auth server denies the request.

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

curl -i localhost:8080/status/200 -H "host: www.example.com"

Example output:

HTTP/1.1 401 Unauthorized
server: envoy
content-length: 0

Send a request with the authorization: authorize me header. Verify that the request succeeds.

curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.example.com:8080" -H "authorization: authorize me"

curl -i localhost:8080/status/200 -H "host: www.example.com" -H "authorization: authorize me"

Example output:

HTTP/1.1 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
content-length: 0
x-envoy-upstream-service-time: 7
server: envoy

Cleanup

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

kubectl delete EnterpriseKgatewayTrafficPolicy http-passthrough-auth -n kgateway-system
kubectl delete authconfig http-passthrough-auth -n httpbin
kubectl delete deployment,service -n httpbin -l app=example-http-auth-server

Other configuration examples

Review other common configuration examples.

Tune the connection pool

By default, the external auth service maintains up to 100 concurrent connections to the HTTP auth server with no idle connection expiry. Use the connectionPool field to override these defaults when your auth server has different capacity limits or you want to reclaim idle connections.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
        connectionTimeout: 5s
        request:
          allowedHeaders:
          - authorization
        connectionPool:
          maxConns: 50
          idleTimeout: 30s
EOF

Field	Description
`connectionPool.maxConns`	Maximum concurrent connections to the auth server. Additional requests are blocked until a connection is free. Defaults to 100.
`connectionPool.idleTimeout`	How long an idle keep-alive connection stays in the pool before being closed. Defaults to 0 (no expiry).

Set a response header timeout

Use the responseHeaderTimeout field to set the maximum time to wait for the HTTP auth server to start sending response headers after the request is fully written. Both the responseHeaderTimeout and connectionTimeout fields run simultaneously. If either one expires before the auth server responds, the request fails. Set the responseHeaderTimeout field to a shorter value than the connectionTimeout to enforce a strict deadline on how long the auth server can stall before it starts responding.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
        connectionTimeout: 5s
        responseHeaderTimeout: 2s
        request:
          allowedHeaders:
          - authorization
EOF

Forward additional headers to the auth server

Use the request.allowedHeaders field to control which headers from the original client request are forwarded to your HTTP auth server. You can also inject static headers into every request that is sent to the auth server by using the request.headersToAdd field.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
        connectionTimeout: 5s
        request:
          allowedHeaders:
          - authorization
          - x-request-id
          headersToAdd:
            x-auth-source: kgateway
EOF

Pass response headers upstream

Use the response.allowedUpstreamHeaders field to pass headers from the auth server’s response to the upstream backend.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
        connectionTimeout: 5s
        request:
          allowedHeaders:
          - authorization
        response:
          allowedUpstreamHeaders:
          - x-user-id
EOF

Pass response headers to the client

You can send back headers to the client when a request is denied (response.allowedClientHeadersOnDenied) by the auth server. Only the headers that you list are added to the response. If you list a header that the auth server does not return, the header is not added to the client response.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
        connectionTimeout: 5s
        response:
          allowedClientHeadersOnDenied:
          - www-authenticate 
EOF

Use TLS

Use the tlsConfig section to enable TLS for the connection between the external auth service and your HTTP auth server. Note that you must store the TLS credentials that you want to use in a Kubernetes secret and reference that secret in the AuthConfig resource.

kubectl apply -f - <<EOF
apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: http-passthrough-auth
  namespace: httpbin
spec:
  configs:
  - passThroughAuth:
      http:
        url: https://example-http-auth-service.httpbin.svc.cluster.local:9443/auth
        connectionTimeout: 5s
        request:
          allowedHeaders:
          - authorization
        tlsConfig:
          secretName: auth-server-tls
          secretNamespace: httpbin
EOF

gRPC

Was this page helpful?