External auth server setup

To enforce external authentication policies, your service mesh environment must have an external auth server. Choose from the following options.

• Use the Gloo external auth server.
• Bring your own external auth server.

Use the Gloo external auth server link

To enforce external auth policies across your service mesh environment, each Gloo Mesh Gateway workspace must have one and only one external auth server. You can configure an ExtAuthServer resource to customize the server behavior, or use the default settings.

1. Register your workload clusters with the ext-auth-service enabled setting. Gloo Mesh Gateway automatically creates a deployment and service of an external auth server.

   • The example steps deploy the external auth server to the default gloo-mesh namespace. Use this namespace to refer to your server in the ExtAuthServer resource.

2. Optional: To group the external auth services across clusters, create a virtual destination. This way, you get traffic management benefits like location-aware, priority-based routing.

     kubectl apply --context ${REMOTE_CONTEXT2} -f - <<EOF
   apiVersion: networking.gloo.solo.io/v2
   kind: VirtualDestination
   metadata:
     annotations:
       cluster.solo.io/cluster: ""
     name: ext-auth-service-global
     namespace: gloo-mesh
   spec:
     hosts:
     - ext-auth-service.vd
     ports:
     - number: 8083
       protocol: GRPC
     services:
     - labels:
         app: ext-auth-service
   EOF
     

   Review the following table to understand this configuration. For more information, see the API reference.

   Setting	Description
   --context ${REMOTE_CONTEXT2}	The virtual destination is created in cluster2 to demonstrate how virtual destinations group services across clusters.
   app: ext-auth-service	The virtual destination elects the default ext-auth-service that you enabled during installation. This default installation meets the requirements to use a virtual destination as the destination server: The service name (ext-auth-service) and namespace (gloo-mesh) match across clusters. The namespace is Istio-injected so that the ext auth service pods have sidecars.

3. 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 your Gloo Mesh Gateway installation, your own custom server, or the virtual destination that you optionally created in the previous step.

     kubectl apply --context ${REMOTE_CONTEXT1} -f - <<EOF
   apiVersion: admin.gloo.solo.io/v2
   kind: ExtAuthServer
   metadata:
     annotations:
       cluster.solo.io/cluster: ""
     name: default-server
     namespace: bookinfo
   spec:
     destinationServer:
       kind: VIRTUAL_DESTINATION
       ref:
         cluster: cluster-2
         name: ext-auth-service-global
         namespace: gloo-mesh
   EOF
     

     kubectl apply --context ${REMOTE_CONTEXT1} -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
   EOF
     

   Review the following table to understand this configuration.
   check_circle

   You can also use the ExtAuthServer resource to customize certain behaviors such as request timeouts, buffering, and HTTP status codes. For more information, see the API reference.

   Setting	Description
   metadata	The name and namespace for this external auth server resource. You can have only one external auth server resource per workspace. This resource does not have to be in the same namespace as the destination server. However, if this resource and the destination server are not in the same workspace, this resource’s workspace must import the destination server’s service.
   destinationServer	The external auth server for Gloo Mesh Gateway to use to enforce external auth policies. The examples select either a virtual destination or the default Gloo Mesh Gateway Kubernetes service. If unset, Gloo Mesh Gateway looks for a service with the name extauth in the same namespace as the Gloo Mesh Gateway agent on each cluster where the selected workload is deployed. This destination server does not have to be in the same workspace as the external auth server configuration or external auth policies. However, you must export the destination server’s service to those workspaces.

4. In your external auth policies, refer to the ExtAuthServer to use. In the example, the server configuration is referred to only by name because the policy is created in the same namespace.

     kubectl apply --context ${REMOTE_CONTEXT1} -f - <<EOF
   apiVersion: security.policy.gloo.solo.io/v2
   kind: ExtAuthPolicy
   metadata:
     annotations:
       cluster.solo.io/cluster: ""
     name: basic-auth
     namespace: bookinfo
   spec:
     applyToDestinations:
     - port:
         number: 9080
       selector:
         labels:
           app: ratings
     config:
       glooAuth:
         configs:
         - basicAuth:
             apr:
               users:
                 user:
                   hashedPassword: 8BvzLUO9IfGPGGsPnAgSu1
                   salt: TYiryv0/
       server:
         name: default-server
   EOF
     

     kubectl apply --context ${REMOTE_CONTEXT1} -f - <<EOF
   apiVersion: security.policy.gloo.solo.io/v2
   kind: ExtAuthPolicy
   metadata:
     annotations:
       cluster.solo.io/cluster: ""
     name: basic-auth
     namespace: bookinfo
   spec:
     applyToRoutes:
     - {}
     - route:
         labels:
           route: ratings
     config:
       glooAuth:
         configs:
         - basicAuth:
             apr:
               users:
                 user:
                   hashedPassword: 8BvzLUO9IfGPGGsPnAgSu1
                   salt: TYiryv0/
       server:
         name: default-server
   EOF
     

Bring your own external auth server link

Gloo Mesh Gateway comes with an external auth server that implements a wide array of authentication and authorization models. However, you can deploy your own external auth server. Then, configure Gloo Mesh Gateway to use this custom server to secure routes with external auth policies.

For example, you might create a custom external auth server to implement custom logic or to accept requests on certain routes.

The following steps demonstrate how to create a simple HTTP external auth server. Use these steps as a model to deploy your own gRPC server that implements the Envoy spec for an external authorization server.

Before you begin link

1. Set up Gloo Mesh Gateway in a single cluster.
2. Install Bookinfo and other sample apps.

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

4. Get the external address of your ingress gateway. The steps vary depending on the type of load balancer that backs the ingress gateway.

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

   Note: Depending on your environment, you might see <pending> instead of an external IP address. For example, if you are testing locally in kind or minikube, or if you have insufficient permissions in your cloud platform, you can instead port-forward the service port of the ingress gateway:

     kubectl -n gloo-mesh-gateways port-forward deploy/istio-ingressgateway-1-20 8081
     

5. Send a request to verify that you can reach the ratings app without authorization. By default, Gloo allows any request on routes that do not specify authentication. Note that you are sending the request along /ratings/2.

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

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

   Example output:

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

Create a simple HTTP external auth server link

When a request matches a route that has an external auth policy applied, Gloo Mesh Gateway forwards the request to an external auth service.

If that external auth service returns a 200 OK response, Gloo Mesh Gateway considers the request to be authorized and sends it to its original destination. If not, Gloo Mesh Gateway denies the request.

You can fine tune settings such as sending headers or forwarding the body by configuring the ExtAuthServer resource as shown in the previous section. Or, you can create your own external auth server to handle requests.

1. Implement your external auth server. For example, you might use the following Python app for a simple HTTP server. In this example, only requests to /ratings/1 are authorized. All other requests are denied with a 401 response.

     import http.server
   import socketserver
   
   class Server(http.server.SimpleHTTPRequestHandler):
       def do_GET(self):
           path = self.path
           print("path", path)
           if path.startswith("/ratings/1"):
               self.send_response(200, 'OK')
           else:
               self.send_response(401, 'Not authorized')
           self.send_header('x-server', 'pythonauth')
           self.end_headers()
   
   def serve_forever(port):
       socketserver.TCPServer(('', port), Server).serve_forever()
   
   if __name__ == "__main__":
       serve_forever(8000)
     

2. Create the a deployment for your HTTP server app. The following example uses the gcr.io/solo-public/docs/sample-auth:latest sample image, which is based on the HTTP server Python code in the previous step. The deployment is created in the bookinfo namespace.

     kubectl apply -f - <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: sample-auth
     namespace: bookinfo
     labels:
       app: sample-auth
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: sample-auth
     template:
       metadata:
         labels:
           app: sample-auth
       spec:
         containers:
         - name: sample-auth
           image: gcr.io/solo-public/docs/sample-auth:latest
           imagePullPolicy: IfNotPresent
           ports:
           - containerPort: 8000
   EOF
     

3. Create a service for your external auth server deployment.

     kubectl apply -f - <<EOF
   kind: Service
   apiVersion: v1
   metadata:
     name: auth-service
     namespace: bookinfo
     labels:
       app: sample-auth
   spec:
     selector:
       app: sample-auth # Selects the external auth deployment
     ports:
     - protocol: TCP
       port: 80 # For HTTP traffic
       targetPort: 8000 # Matches the container port of the external auth deployment
       name: http # Include this name so that Gloo Mesh Gateway knows that this is the HTTP port to use
   EOF
     

4. Verify that the external auth server is running.

     kubectl get all -l app=sample-auth -n bookinfo 
     

5. Optional: Depending on your setup, repeat these steps for each workspace where you want to use the external auth server.

Configure Gloo to use your custom external auth server link

Now that you have an external auth server running in your cluster, configure Gloo Mesh Gateway to use the server for authentication requests. You use an ExtAuthServer custom resource.

1. Create an ExtAuthServer resource to configure the server.

     kubectl apply -f - <<EOF
   apiVersion: admin.gloo.solo.io/v2
   kind: ExtAuthServer
   metadata:
     name: custom-server
     namespace: bookinfo
     labels:
        app: sample-auth
   spec:
     destinationServer:
       port:
         number: 8000
       ref:
         cluster: ${CLUSTER_NAME}
         name: auth-service
         namespace: bookinfo
   EOF
     

   Review the following table to understand this configuration.
   check_circle

   You can also use the ExtAuthServer resource to customize certain behaviors such as request timeouts, buffering, and HTTP status codes. For more information, see the API reference.

   Setting	Description
   metadata	The name and namespace for this external auth server resource. You can have only one external auth server resource per workspace. This resource does not have to be in the same namespace as the destination server. However, if this resource and the destination server are not in the same workspace, this resource’s workspace must import the destination server’s service.
   destinationServer	The external auth server for Gloo Mesh Gateway to use to authentic requests with an external auth policy. If unset, Gloo Mesh Gateway looks for a service with the name extauth in the same namespace as the Gloo Mesh Gateway agent on each cluster where the selected workload is deployed. This destination server does not have to be in the same workspace as the external auth server configuration or external auth policies. However, you must export the destination server’s service to those workspaces.

2. Create an external auth policy that uses your custom auth server.

     kubectl apply -f - <<EOF
   apiVersion: security.policy.gloo.solo.io/v2
   kind: ExtAuthPolicy
   metadata:
     name: custom-auth
     namespace: bookinfo
     labels:
        app: sample-auth
   spec:
     applyToRoutes:
     - route:
         labels:
           route: ratings
     config:
       customAuth: {}
       server:
         name: custom-server
   EOF
     

   Review the following table to understand this configuration. For more information, see the API reference.

   Setting	Description
   applyToRoutes	Use labels to configure which routes to apply the policy to. This example label matches the app and route from the example route table that you apply separately. If omitted and you do not have another selector such as applyToDestinations, the policy applies to all routes in the workspace.
   customAuth	Set this field to use your own custom auth server.
   server	The external auth server to use for the policy.

3. Send a request to the ratings app along the /ratings/2 path. Now, your request is denied because the external auth server allows requests only along the /ratings/1 path.

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

4. Repeat the previous request along the /ratings/1 path.

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

   The request succeeds:

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

Cleanup link

  kubectl delete deploy,svc,extauthserver,extauthpolicy -n bookinfo -l app=sample-auth