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

Authenticate requests with your own HTTP server.

Before you begin

1. Follow the Get started guide to install Gloo Gateway, set up a gateway resource, and deploy the httpbin sample app.

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

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

   kubectl port-forward deployment/gloo-proxy-http -n gloo-system 8080:8080

Create an HTTP auth server

1. Deploy the HTTP auth server.

   kubectl apply -f - <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: extauth-httpservice
     namespace: httpbin
   spec:
     selector:
       matchLabels:
         app: http-extauth
     replicas: 1
     template:
       metadata:
         labels:
           app: http-extauth
       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: http-extauth
   spec:
     ports:
     - port: 9001
       protocol: TCP
     selector:
       app: http-extauth
   EOF

2. Verify that the HTTP auth server is up and running.

   kubectl get pods -n gloo-system

Set up external auth

1. Create an AuthConfig resource and add your external authentication rules.

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

   Review the following table to understand this configuration.

   Setting	Description
   url	The URL of the HTTP auth server to use for authentication. The example server that you previously setup expects requests along the auth path.
   connectionTimeout	The connection timeout to the HTTP auth server.
   request.allowedHeaders	The headers that are allowed to be passed through to the HTTP auth server. The example server that you previously setup expects an authorization: authorize me header.
   tlsConfig	Use simple TLS when connecting to the passthrough server. You can also configure the passthrough server for mutual TLS. For more information, see the API reference.

2. Create a RouteOption resource and reference the AuthConfig resource that you just created.

   kubectl apply -f- <<EOF
   apiVersion: gateway.solo.io/v1
   kind: RouteOption
   metadata:
     name: passthrough-auth
     namespace: httpbin
   spec:
     options:
       extauth:
         configRef:
           name: passthrough-auth
           namespace: httpbin
   EOF

3. Create an HTTPRoute resource for the httpbin app that requires authentication for requests on the extauth.example domain.

   kubectl apply -f- <<EOF
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: httpbin-passthrough-auth
     namespace: httpbin
   spec:
     parentRefs:
     - name: http
       namespace: gloo-system
     hostnames:
       - extauth.example
     rules:
       - filters:
           - type: ExtensionRef
             extensionRef:
               group: gateway.solo.io
               kind: RouteOption
               name: passthrough-auth
         backendRefs:
           - name: httpbin
             port: 8000
   EOF

4. Send a request to the httpbin app on the extauth.example domain. Verify that your request is denied and that you get back a 401 HTTP response code.

   curl -v http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: extauth.example:8080"

   curl -v localhost:8080/status/200 -H "host: extauth.example"

   Example output:

   * Mark bundle as not supporting multiuse
   < HTTP/1.1 401 Unauthorized
   < www-authenticate: Basic realm="gloo"
   < date: Fri, 19 Apr 2024 17:41:01 GMT
   < server: envoy
   < content-length: 0

5. Send another request to the httpbin app. This time, you include the authorization: authorize me header that the example server expects. Verify that the request succeeds and that you get back a 200 HTTP response code.

   curl -v http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: extauth.example:8080" -H "authorization: authorize me"

   curl -v localhost:8080/status/200 -H "host: extauth.example" -H "authorization: authorize me"

   Example output:

   ...
   > GET /status/200 HTTP/1.1
   > Host: extauth.example
   > User-Agent: curl/8.7.1
   > Accept: */*
   > authorization: authorize me
   > 
   * Request completely sent off
   < HTTP/1.1 200 OK

Other configurations

Control how auth server response headers are forwarded

By default, no headers from the HTTP passthrough auth server response are forwarded to the client or upstream. Use the response block to configure which headers are forwarded and where.

kubectl apply -f- <<EOF
apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: passthrough-auth
  namespace: httpbin
spec:
  configs:
    - passThroughAuth:
        http:
          url: http://example-http-auth-service.httpbin.svc.cluster.local:9001/auth
          connectionTimeout: 3s
          response:
            allowedClientHeadersOnSuccess:
            - x-auth-user
            - x-auth-role
            allowedClientHeadersOnDenied:
            - www-authenticate
            allowedUpstreamHeaders:
            - x-auth-user
            allowedUpstreamHeadersToOverwrite:
            - x-forwarded-user
EOF

Configure connection pool settings

Use the connectionPool block and responseHeaderTimeout field to tune how the ext-auth service connects to the passthrough auth server.

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

Cleanup

kubectl delete authconfig passthrough-auth -n httpbin
kubectl delete routeoption passthrough-auth -n httpbin
kubectl delete httproute httpbin-passthrough-auth -n httpbin