☰
Navigation :

Passthrough external auth

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

This feature is available with a Gloo Mesh Gateway license only.

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 Mesh external auth implementations, such as OIDC and API key auth. A custom auth server is not integrated with the Gloo Mesh 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 Mesh 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

  1. Complete the demo setup to install Gloo Mesh, Istio, and Bookinfo in your cluster.

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

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

  3. Create the Gloo Mesh resources for this policy in the management and workload clusters, including a Gloo Mesh external auth server.

    The following files are examples only for testing purposes. Your actual setup might vary. You can use the files as a reference for creating your own tests.

    1. Download the following Gloo Mesh resources:

    2. Apply the files to your management cluster.

      kubectl apply -f kubernetes-cluster_gloo-mesh_cluster-1.yaml --context ${MGMT_CONTEXT}
kubectl apply -f kubernetes-cluster_gloo-mesh_cluster-2.yaml --context ${MGMT_CONTEXT}
kubectl apply -f workspace_gloo-mesh_anything.yaml --context ${MGMT_CONTEXT}

    1. Download the following Gloo Mesh resources:

    2. Apply the files to your workload cluster.

      kubectl apply -f ext-auth-server_bookinfo_default-server.yaml --context ${REMOTE_CONTEXT1}
kubectl apply -f route-table_bookinfo_www-example-com.yaml --context ${REMOTE_CONTEXT1}
kubectl apply -f virtual-gateway_bookinfo_north-south-gw.yaml --context ${REMOTE_CONTEXT1}
kubectl apply -f workspace-settings_bookinfo_anything.yaml --context ${REMOTE_CONTEXT1}

Configure a passthrough gRPC service

Gloo Mesh 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 --context ${REMOTE_CONTEXT1} -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 --context ${REMOTE_CONTEXT1} -f- <<EOF
apiVersion: v1
kind: Service
metadata:
  name: example-grpc-auth-service
  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 --context ${REMOTE_CONTEXT1}

Secure routes with an external auth policy

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

  1. Verify that you can access the ratings service, based on the virtual gateway and route table settings that you created in the before you begin section.

    curl -v http://${INGRESS_GW_IP}/ratings/1 -H "Host: www.example.com"

    Example output:

    {"id":1,"ratings":{"Reviewer1":5,"Reviewer2":4}}

  2. Create an external auth policy for the ratings route.

    kubectl apply --context ${REMOTE_CONTEXT1} -f- <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: basic-auth
  namespace: bookinfo
spec:
  applyToRoutes:
  - route:
      labels:
        route: ratings
  config:
    glooAuth:
      configs:
      - passThroughAuth:
          grpc:
            address: example-grpc-auth-service.bookinfo.svc.cluster.local:9001
EOF
Review the following table to understand this configuration.
Setting Description
spec.applyToRoutes Configure which routes to apply the policy to, by using labels. The label matches the app and the route from the route table. If omitted, the policy applies to all routes in the workspace.
spec.config.glooAuth.configs.passThroughAuth Set the gRPC service address. The example uses the service address and port that you created in the previous section. For more options, see the API reference.

Verify external auth policies

  1. View the ext-auth-service deployment logs to verify that the policy was accepted. Look for a message similar to the following: "logger":"extauth","caller":"runner/run.go:179","msg":"got new config"

    kubectl logs -n gloo-mesh deploy/ext-auth-service -c ext-auth-service -f --context $REMOTE_CONTEXT1

  2. Send the same request to the ratings app that previously succeeded.

    curl -v http://${INGRESS_GW_IP}/ratings/1 -H "Host: www.example.com"

    You get back a 403 (Unauthorized) response, because the request is not authenticated.

  3. 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.

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

    Your request succeeds again!

Share state with other auth steps

You can set up the Gloo Mesh 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:

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 --context ${REMOTE_CONTEXT1} -f- <<EOF
apiVersion: security.policy.gloo.solo.io/v2
kind: ExtAuthPolicy
metadata:
  name: basic-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
EOF