GRPC Passthrough documentation and test server update (#10676)

Author: sheidkamp

changelog/v1.19.0-beta13/passthrough-qol.yaml

@@ -0,0 +1,10 @@
+changelog:
+  - type: NON_USER_FACING
+    issueLink: https://github.com/solo-io/solo-projects/issues/7893
+    resolvesIssue: false
+    description: >-
+      Update grpc and http passthrough example servers to optionlly log full request info
+      Update grpc and http passthrough examples to be able to run at the same time.
+      Update PassThroughGrpc description to call out use of `settings.extauth.requestBody` to send request body to extauth server.
+
+

docs/content/guides/security/auth/extauth/passthrough_auth/grpc/_index.md

@@ -81,16 +81,16 @@ EOF
 Now let's configure Gloo Gateway to route requests to the upstream we just created. To do that, we define a simple Virtual 
 Service to match all requests that:
 
-- contain a `Host` header with value `foo` and
+- contain a `Host` header with value `foo-grpc` and
 - have a path that starts with `/` (this will match all requests).
 
 Apply the following virtual service:
-{{< readfile file="guides/security/auth/extauth/basic_auth/test-no-auth-vs.yaml" markdown="true">}}
+{{< readfile file="guides/security/auth/extauth/passthrough_auth/grpc/test-no-auth-vs.yaml" markdown="true">}}
 
 Let's send a request that matches the above route to the gateway proxy and make sure it works:
 
 ```shell
-curl -H "Host: foo" $(glooctl proxy url)/posts/1
+curl -H "Host: foo-grpc" $(glooctl proxy url)/posts/1
 ```
 
 The above command should produce the following output:
@@ -116,7 +116,7 @@ kubectl apply -f - <<EOF
 apiVersion: enterprise.gloo.solo.io/v1
 kind: AuthConfig
 metadata:
-  name: passthrough-auth
+  name: grpc-passthrough-auth
   namespace: gloo-system
 spec:
   configs:
@@ -141,12 +141,12 @@ kubectl apply -f - <<EOF
 apiVersion: gateway.solo.io/v1
 kind: VirtualService
 metadata:
-  name: auth-tutorial
+  name: grpc-auth-tutorial
   namespace: gloo-system
 spec:
   virtualHost:
     domains:
-      - 'foo'
+      - 'foo-grpc'
     routes:
       - matchers:
         - prefix: /
@@ -156,11 +156,11 @@ spec:
               name: json-upstream
               namespace: gloo-system
         options:
-          autoHostRewrite: true      
+          autoHostRewrite: true
     options:
       extauth:
         configRef:
-          name: passthrough-auth
+          name: grpc-passthrough-auth
           namespace: gloo-system
 EOF
 {{< /highlight >}}
@@ -193,19 +193,19 @@ For more information on how Gloo Gateway handles observability and metrics, view
 The virtual service that we have created should now be secured using our external authentication service. To test this, we can try our original command, and the request should not be allowed through because of missing authentication.
 
 ```shell
-curl -H "Host: foo" $(glooctl proxy url)/posts/1
+curl -H "Host: foo-grpc" $(glooctl proxy url)/posts/1
 ```
 
 The output should be empty. In fact, we can see the 403 (Unauthorized) HTTP status code if we run the same curl, but with a modification to print the http code to the console.
 
 ```shell
-curl -s -o /dev/null -w "%{http_code}" -H "Host: foo" $(glooctl proxy url)/posts/1
+curl -s -o /dev/null -w "%{http_code}" -H "Host: foo-grpc" $(glooctl proxy url)/posts/1
 ```
 
 The sample gRPC authentication service has been implemented such that any request with the header `authorization: authorize me` will be authorized. We can easily add this header to our curl request as follows:
 
 ```shell
-curl -H "Host: foo" -H "authorization: authorize me" $(glooctl proxy url)/posts/1
+curl -H "Host: foo-grpc" -H "authorization: authorize me" $(glooctl proxy url)/posts/1
 ```
 
 The request should now be authorized!
@@ -223,7 +223,7 @@ You can configure the Gloo ExtAuth server to retry the connection to the passthr
 apiVersion: enterprise.gloo.solo.io/v1
 kind: AuthConfig
 metadata:
-  name: passthrough-auth
+  name: grpc-passthrough-auth
   namespace: gloo-system
 spec:
   configs:
@@ -262,7 +262,7 @@ State from other auth steps is sent to the passthrough service via [CheckRequest
 
 State from the passthrough service can be sent to other auth steps via [CheckResponse DynamicMetadata](https://github.com/envoyproxy/envoy/blob/50e722cbb0486268c128b0f1d0ef76217387799f/api/envoy/service/auth/v3/external_auth.proto#L126) under a unique key: `solo.auth.passthrough`.
 
-### Passing in custom configuration to Passthrough Auth Service from AuthConfigs
+### Passing custom configuration to the Passthrough Auth Service from AuthConfigs
 {{% notice note %}}
 This feature was introduced with **Gloo Gateway Enterprise**, release 1.6.15. If you are using an earlier version, this will not work.
 {{% /notice %}}
@@ -274,7 +274,7 @@ kubectl apply -f - <<EOF
 apiVersion: enterprise.gloo.solo.io/v1
 kind: AuthConfig
   metadata:
-    name: passthrough-auth
+    name: grpc-passthrough-auth
     namespace: gloo-system
   spec:
     configs:
@@ -292,6 +292,9 @@ EOF
 
 This config is accessible via the [CheckRequest FilterMetadata](https://github.com/envoyproxy/envoy/blob/50e722cbb0486268c128b0f1d0ef76217387799f/api/envoy/service/auth/v3/external_auth.proto#L36) under a unique key: `solo.auth.passthrough.config`.
 
+## Pass request body to the Passthrough Auth Service
+In order for the body to be passed through to the auth service, the `settings.extauth.requestBody` must be set in the Gloo Gateway Settings CRD so that the request body is buffered and sent to the ext-auth service. Headers are always passed through.
+
 ## Summary
 
 In this guide, we installed Gloo Gateway Enterprise and created an unauthenticated Virtual Service that routes requests to a static upstream. We spun up an example gRPC authentication service that uses a simple header for authentication. We then created an `AuthConfig` and configured it to use Passthrough Auth, pointing it to the IP of our example gRPC service. In doing so, we instructed gloo to pass through requests from the external authentication server to the grpc authentication service provided by the user.

docs/content/guides/security/auth/extauth/passthrough_auth/grpc/test-no-auth-vs.yaml

@@ -0,0 +1,21 @@
+```yaml
+apiVersion: gateway.solo.io/v1
+kind: VirtualService
+metadata:
+  name: grpc-auth-tutorial
+  namespace: gloo-system
+spec:
+  virtualHost:
+    domains:
+      - 'foo-grpc'
+    routes:
+      - matchers:
+        - prefix: /
+        routeAction:
+          single:
+            upstream:
+              name: json-upstream
+              namespace: gloo-system
+        options:
+          autoHostRewrite: true
+```

docs/content/guides/security/auth/extauth/passthrough_auth/http/_index.md

@@ -76,16 +76,16 @@ EOF
 Now let's configure Gloo Gateway to route requests to the upstream we just created. To do that, we define a simple Virtual 
 Service to match all requests that:
 
-- contain a `Host` header with value `foo` and
+- contain a `Host` header with value `foo-http` and
 - have a path that starts with `/` (this will match all requests).
 
 Apply the following virtual service:
-{{< readfile file="guides/security/auth/extauth/basic_auth/test-no-auth-vs.yaml" markdown="true">}}
+{{< readfile file="guides/security/auth/extauth/passthrough_auth/http/test-no-auth-vs.yaml" markdown="true">}}
 
 Let's send a request that matches the above route to the gateway proxy and make sure it works:
 
 ```shell
-curl -H "Host: foo" $(glooctl proxy url)/posts/1
+curl -H "Host: foo-http" $(glooctl proxy url)/posts/1
 ```
 
 The above command should produce the following output:
@@ -111,14 +111,14 @@ kubectl apply -f - <<EOF
 apiVersion: enterprise.gloo.solo.io/v1
 kind: AuthConfig
 metadata:
-  name: passthrough-auth
+  name: http-passthrough-auth
   namespace: gloo-system
 spec:
   configs:
   - passThroughAuth:
       http:
         # Url of the http auth server to use for auth
-        url: http://example-http-auth-service.default.svc.cluster.local:9001
+        url: http://example-http-auth-service.default.svc.cluster.local:9001/auth
         # Set a connection timeout to external service, default is 5 seconds
         connectionTimeout: 3s
 EOF
@@ -136,12 +136,12 @@ kubectl apply -f - <<EOF
 apiVersion: gateway.solo.io/v1
 kind: VirtualService
 metadata:
-  name: auth-tutorial
+  name: http-auth-tutorial
   namespace: gloo-system
 spec:
   virtualHost:
     domains:
-      - 'foo'
+      - 'foo-http'
     routes:
       - matchers:
         - prefix: /
@@ -151,11 +151,11 @@ spec:
               name: json-upstream
               namespace: gloo-system
         options:
-          autoHostRewrite: true      
+          autoHostRewrite: true
     options:
       extauth:
         configRef:
-          name: passthrough-auth
+          name: http-passthrough-auth
           namespace: gloo-system
 EOF
 {{< /highlight >}}
@@ -189,7 +189,7 @@ If the auth config has been received successfully, you should see the log line:
 The virtual service that we have created should now be secured using our external authentication service. To test this, we can try our original command, and the request should not be allowed through because of missing authentication.
 
 ```shell
-curl -v -H "Host: foo" $(glooctl proxy url)/posts/1
+curl -v -H "Host: foo-http" $(glooctl proxy url)/posts/1
 ```
 
 In fact, if we check the logs of our sample http auth service, we see the following message:
@@ -205,7 +205,7 @@ kubectl apply -f - <<EOF
 apiVersion: enterprise.gloo.solo.io/v1
 kind: AuthConfig
 metadata:
-  name: passthrough-auth
+  name: http-passthrough-auth
   namespace: gloo-system
 spec:
   configs:
@@ -226,7 +226,7 @@ The sample Http authentication service has been implemented such that any reques
 passthrough auth to use the `/auth` path with the http auth server and to passthrough `Authorization` header. We can now add this header to our curl request as follows:
 
 ```shell
-curl -H "Host: foo" -H "authorization: authorize me" $(glooctl proxy url)/posts/1
+curl -H "Host: foo-http" -H "authorization: authorize me" $(glooctl proxy url)/posts/1
 ```
 
 The request should now be authorized!
@@ -239,7 +239,7 @@ For more information about configuration options, see the [API docs]({{< version
 apiVersion: enterprise.gloo.solo.io/v1
 kind: AuthConfig
 metadata:
-  name: passthrough-auth
+  name: http-passthrough-auth
   namespace: gloo-system
 spec:
   configs:
@@ -248,7 +248,7 @@ spec:
         # Url of the http auth server to use for auth
         # This can include path, and can also use https. 
         # In order to use a https passthrough server, provide the cert in the HTTPS_PASSTHROUGH_CA_CERT environment variable to the ext-auth-service pod as a base64-encoded string.
-        url: http://example-http-auth-service.default.svc.cluster.local:9001
+        url: http://example-http-auth-service.default.svc.cluster.local:9001/auth
         # Set a connection timeout to external service, default is 5 seconds
         connectionTimeout: 3s
         # These options will modify the request going to the passthrough auth server

docs/content/guides/security/auth/extauth/passthrough_auth/http/test-no-auth-vs.yaml

@@ -0,0 +1,21 @@
+```yaml
+apiVersion: gateway.solo.io/v1
+kind: VirtualService
+metadata:
+  name: http-auth-tutorial
+  namespace: gloo-system
+spec:
+  virtualHost:
+    domains:
+      - 'foo-http'
+    routes:
+      - matchers:
+        - prefix: /
+        routeAction:
+          single:
+            upstream:
+              name: json-upstream
+              namespace: gloo-system
+        options:
+          autoHostRewrite: true
+```

docs/content/reference/api/github.com/solo-io/gloo/projects/gloo/api/v1/enterprise/options/extauth/v1/extauth.proto.sk.md

@@ -0,0 +1,7 @@
+# GRPC Passthrough Auth Server
+
+This server's `/auth` endpoint will return a 200 if the `authorization: authorize me` header is set, and a 403 otherwise
+
+If the `REQUEST_LOGGING` environment variable is set the full request will be written to the logs
+
+Build the `quay.io/solo-io/passthrough-grpc-service-example` image by running `make docker-local` from this directory.

docs/examples/grpc-passthrough-auth/README.md

@@ -1,10 +1,22 @@
 module github.com/envoyproxy/envoy/examples/ext_authz/auth/grpc-service
 
-go 1.14
+go 1.24
 
 require (
-	github.com/envoyproxy/go-control-plane v0.9.8
-	github.com/golang/protobuf v1.4.2
-	google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55
-	google.golang.org/grpc v1.27.0
+	github.com/envoyproxy/go-control-plane/envoy v1.32.3
+	github.com/golang/protobuf v1.5.4
+	github.com/solo-io/gloo v1.18.10
+	google.golang.org/genproto v0.0.0-20250224174004-546df14abb99
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20250219182151-9fdb1cabc7b2
+	google.golang.org/grpc v1.70.0
+)
+
+require (
+	github.com/cncf/xds/go v0.0.0-20240905190251-b4127c9b8d78 // indirect
+	github.com/envoyproxy/protoc-gen-validate v1.1.0 // indirect
+	github.com/planetscale/vtprotobuf v0.6.1-0.20240409071808-615f978279ca // indirect
+	golang.org/x/net v0.35.0 // indirect
+	golang.org/x/sys v0.30.0 // indirect
+	golang.org/x/text v0.22.0 // indirect
+	google.golang.org/protobuf v1.36.5 // indirect
 )