gRPC

Before you begin link

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 the gRPC auth server link

1. Deploy a sample gRPC auth server that is configured to authorize requests that include the authorization: authorize me request header. This example is based on the Envoy service specification. You can review the source code for the gRPC auth server in the Gloo Gateway GitHub repository.

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

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

     kubectl get pods -n httpbin
     

Set up external auth link

1. Create an AuthConfig resource and add your external authentication rules. The following example passes authentication requests through to the gRPC auth server that you deployed earlier.

     kubectl apply -f - <<EOF
   apiVersion: enterprise.gloo.solo.io/v1
   kind: AuthConfig
   metadata:
     name: passthrough-auth
     namespace: httpbin
   spec:
     configs:
     - passThroughAuth:
         grpc:
           # Address of the grpc auth server to query
           address: example-grpc-auth-service.httpbin.svc.cluster.local:9001
           # Set a connection timeout to external service, default is 5 seconds
           connectionTimeout: 3s
   EOF
     

   info

   The passthrough service in Gloo Gateway can be configured to fail open by using the failureModeAllow field. If set to true, the auth service responds with an OK message if the gRPC auth server returns a 5xx HTTP response code or the request times out.

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 403 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 403 Forbidden
   < date: Wed, 05 Jun 2024 14:12:36 GMT
   < server: envoy
   < content-length: 0
     

5. Send another request to the httpbin app. This time, you include the authorization: authorize me request header. 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:

     * Mark bundle as not supporting multiuse
   < HTTP/1.1 200 OK
   < access-control-allow-credentials: true
   < access-control-allow-origin: *
   < date: Wed, 05 Jun 2024 14:18:28 GMT
   < content-length: 0
   < x-envoy-upstream-service-time: 1
   < server: envoy
     

Configure retries for unresponsive passthrough servers link

You can configure the Gloo external auth server to retry the connection to the passthrough service in the case that the passthrough service becomes unavailable. Consider the following two scenarios to learn more about how retries to the passthrough service are executed:

Passthrough service becomes unavailable after initial connection link

In this scenario, the external auth server successfully established an initial connection to the passthrough service. However later on, the passthrough service becomes unavailable. You can add a retry policy to your AuthConfig resource to retry the connection to the passthrough service if the service becomes unavailable. In the following AuthConfig, the external auth server in Gloo Gateway is configured to retry the connection to the passthrough service 10 times.

To not overload the passthrough service, an optional exponential backoff strategy is defined. The backoff strategy configures the external auth server to start retries after 1 second (baseInterval). Retries are then executed exponentially, such as after 2 seconds, 4 seconds, 8 seconds, etc up to the maxInterval that defaults to 10 times the baseInterval. In this example, the maxInterval configures a maximum delay of 2 seconds between retries.

apiVersion: enterprise.gloo.solo.io/v1
kind: AuthConfig
metadata:
  name: passthrough-auth
  namespace: gloo-system
spec:
  configs:
  - passThroughAuth:
      grpc:
        # Address of the grpc auth server to query
        address: example-grpc-auth-service.default.svc.cluster.local:9001
        # Set a connection timeout to external service, default is 5 seconds
        connectionTimeout: 3s
        retryPolicy: 
          numRetries: 10
          retryBackOff:
            baseInterval: 1s
            maxInterval: 2s

Passthrough service is unavailable during the initial connection link

When you configure your AuthConfig with a retry policy, auth requests are retried only after the initial connection between the Gloo Gateway auth server and passthrough service is established successfully. If establishing the initial connection fails, the external auth server retries the connection up to the defined connectionTimeout in the AuthConfig. The settings in the retry policy are ignored and any auth requests that are sent to the external auth server during that time fail immediately. Auth requests continue to fail when the connectionTimeout is reached, even if the passthrough service becomes available afterwards. To mitigate this issue, you can try increasing the connectionTimeout setting if you think that your passthrough service can recover and become available within the specified connection timeout.

Cleanup link

  kubectl delete authconfig passthrough-auth -n httpbin
kubectl delete routeoption passthrough-auth -n httpbin
kubectl delete httproute httpbin-passthrough-auth -n httpbin
kubectl delete deployment extauth-grpcservice -n httpbin
kubectl delete service example-grpc-auth-service -n httpbin