Passthrough external auth

Authenticate requests with an external gRPC service. The gRPC service implements Envoy's Authorization Service API to authenticate requests.

Passthrough or custom external auth

You might wonder, why should I use passthrough instead of a custom external auth server?

Benefits of passthrough: With gRPC passthrough, you can set up your own custom logic in the external gRPC service. You can still use the other Gloo Gateway external auth implementations, such as OIDC and API key auth. A custom auth server is not integrated with the Gloo Gateway external auth server, so you cannot use both at the same time.

Drawbacks of passthrough: To provide additional flexibility in auth configuration, passthrough sets up a separate gRPC service that the Gloo Gateway external auth server forwards requests to for authentication. This step requires an additional network hop, so you might notice an impact to latency.

Before you begin

Follow the getting started instructions to:

1. Set up Gloo Gateway in a single cluster.

2. Deploy sample apps.

3. Configure an HTTP listener on your gateway and set up basic routing for the sample apps.

4. Make sure that the external auth service is installed and running. If not, install the external auth service in your single or multicluster environment.

   kubectl get pods -A -l app=ext-auth-service
   

5. Make sure that you have the following CLI tools, or something comparable:

   • htpasswd to generate hashed, salted passwords.
   • base64 to encode strings.

6. If you did not already do so, create an ExtAuthServer resource for your workspace. This resource points to the destination server to use for external auth policies. The destination server can be the default ext-auth-service from Gloo Gateway, or your own custom server. Note: Change the cluster-1 value as needed.

   kubectl apply -f - <<EOF
   apiVersion: admin.gloo.solo.io/v2
   kind: ExtAuthServer
   metadata:
     annotations:
       cluster.solo.io/cluster: ""
     name: default-server
     namespace: bookinfo
   spec:
     destinationServer:
       port:
         number: 8083
       ref:
         cluster: cluster-1
         name: ext-auth-service
         namespace: gloo-mesh-addons
   EOF
   

Configure a passthrough gRPC service

Gloo Gateway supports adding an external gRPC service that implements Envoy's Authorization Service API. The following steps use a sample image for the gRPC passthrough service, but you can use your own.

1. Deploy a sample gRPC service that runs on port 9001. For more information, review the service spec in the Envoy docs.

   kubectl apply -f- <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: extauth-grpcservice
     namespace: bookinfo # <-- this namespace assumes auto injection is enabled
   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
   EOF
   

2. Create a service to assign the deployment a static cluster IP address.

   kubectl apply -f- <<EOF
   apiVersion: v1
   kind: Service
   metadata:
     name: extauth-grpcservice
     namespace: bookinfo
     labels:
         app: grpc-extauth
   spec:
     ports:
     - port: 9001
       protocol: TCP
     selector:
         app: grpc-extauth
   EOF
   

3. Confirm that the deployment is ready and the cluster IP address is assigned.

   kubectl get all -l app=grpc-extauth -n bookinfo
   

Secure routes with an external auth policy

Create an external auth policy for the ratings route so that requests are authenticated by the gRPC service that you previously deployed.

kubectl apply -f- <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: passthrough-auth
  namespace: bookinfo
spec:
  applyToRoutes:
  - route:
      labels:
        route: ratings
  config:
    glooAuth:
      configs:
      - passThroughAuth:
          grpc:
            address: extauth-grpcservice.bookinfo.svc.cluster.local:9001
    server:
      name: default-server
      namespace: bookinfo
      cluster: $CLUSTER_NAME
EOF

Verify external auth policies

1. Send a request to the ratings app. You get back a 403 (Unauthorized) response, because the request is not authenticated.

   • HTTP
   • HTTPS

   curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/1
   

   curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/ratings/1
   

2. Send an authenticated request to the ratings app. The gRPC service that you deployed is set up to accept any request with an authorization: authorize me header.

   • HTTP
   • HTTPS

   curl -vik --resolve www.example.com:80:${INGRESS_GW_IP} http://www.example.com:80/ratings/1 -H "authorization: authorize me"
   

   curl -vik --resolve www.example.com:443:${INGRESS_GW_IP} https://www.example.com:443/ratings/1 -H "authorization: authorize me"
   

   Your request succeeds again!

3. Optional: Clean up the resources that you created.

   kubectl -n bookinfo delete Deployment extauth-grpcservice
   kubectl -n bookinfo delete Service extauth-grpcservice
   kubectl -n bookinfo delete ExtAuthServer default-server
   kubectl -n bookinfo delete ExtAuthPolicy passthrough-auth
   

Share state with other auth steps

You can set up the Gloo Gateway external auth server to share state between the passthrough service and other auth steps, such as OPA, an API key, or a custom auth plug-in.

If you make a custom auth plug-in, you can use a state map to chain together the auth steps that you want to require. For more information, see the following resources:

• Gloo Edge docs
• Example .go implementation code in the Gloo Edge open source project

Reading state from other auth steps

State from other auth steps is sent to the passthrough service via CheckRequest FilterMetadata under a unique key: solo.auth.passthrough.

Writing state to be used by other auth steps

State from the passthrough service can be sent to other auth steps via CheckResponse DynamicMetadata under a unique key: solo.auth.passthrough.

Passing in custom configuration to Passthrough Auth Service from AuthConfigs

You can pass a custom config to the passthrough authentication service by using the config.passThroughAuth section in the external auth policy. You might use a custom config to add extra authentication information to passed-through requests, such as a custom key.

This config is accessible via the CheckRequest FilterMetadata under a unique key: solo.auth.passthrough.config.

kubectl apply -f- <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: passthrough-auth
  namespace: bookinfo
spec:
  applyToRoutes:
  - route:
      labels:
        route: ratings
  config:
    glooAuth:
      configs:
      - passThroughAuth:
          grpc:
            address: example-grpc-auth-service.bookinfo.svc.cluster.local:9001
          config:
            customKey1: "customConfigStringValue"
            customKey2: false
    server:
      name: default-server
      namespace: bookinfo
      cluster: $CLUSTER_NAME
EOF